aternos/codex

PHP library to read, parse, print and analyse log files.

v2.2.0 2024-09-11 12:33 UTC

Requires

• php: >=8.1

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Matthias Neid

README

About

Codex (lat. roughly for "log") is a PHP library to read, parse, print and analyse log files to find problems and suggest possible solutions. It was created mainly for Minecraft server logs but could be used for any other logs as well. This library provides a set up for a structured log parsing implementation and provides some useful basic implementation, mainly based on RegEx. Every part of this library can or even must be extended/overwritten while still following the interfaces, which ensure interoperability between the different parts of this library.

Installation

composer require aternos/codex

Usage

This is a short introduction to the idea of Codex, for some more examples check the test folder and/or read the code.

Logfile

A LogFile object implementing the LogFileInterface object is required to start reading a log. There are currently three different log file classes in this library.

<?php

$logFile = new \Aternos\Codex\Log\File\StringLogFile("This is the log content");
$logFile = new \Aternos\Codex\Log\File\PathLogFile("/path/to/log");
$logFile = new \Aternos\Codex\Log\File\StreamLogFile(fopen("/path/to/log", "r"));

Log

A Log object implementing the LogInterface is the most important object for the different operations. It represents the log content, which is split in Entries and Lines. And it offers quick access to the detection, parsing and analysing functions and can define which classes are used for those functions. If you know which log type you have or just want to test the default Log class, you can directly create a new instance, otherwise you can use detection as described below.

<?php

$log = new \Aternos\Codex\Log\Log();
$log->setLogFile($logFile);

Detection

If the log type (specifically the class name of the log type) is unknown you can use the Detective class to automatically detect the log type. The Detective class gets a list of possible log class names and executes their given Detectors.

<?php

$detective = new \Aternos\Codex\Detective\Detective();
$detective->addPossibleLogClass(\Aternos\Codex\Log\Log::class);
$log = $detective->detect();

The detect() function always returns a log object, if necessary it defaults to Log.

Parsing

Parsing reads the entire log and creates the Entry and Line objects which are parts of a Log object. Different log types can use different parsers by overwriting the LogInterface::getDefaultParser() function or by passing a parser object to the parse function.

<?php

$log->parse();

Analysing

An analysis is performed by an Analyser on an AnalysableLog and returns an Analysis object containing various Insight objects, e.g. a Problem or an Information object. Different log types can use different analysers by overwriting the AnalysableLogInterface::getDefaultAnalyser() function or by passing an analyser object to the analyse function.

<?php

$analysis = $log->analyse();

Printing

The entire Log or just an Entry can be printed through a Printer. The basic DefaultPrinter only prints the plain content line by line. The ModifiableDefaultPrinter allows Modification, e.g. to highlight certain characters/words.

<?php

$printer = new \Aternos\Codex\Printer\DefaultPrinter();
$printer->setLog($log);
$printer->print();

$printer = new \Aternos\Codex\Printer\DefaultPrinter();
$printer->setEntry($entry);
$printer->print();

$printer = new \Aternos\Codex\Printer\ModifiableDefaultPrinter();
$printer->setLog($log);
$modification = new \Aternos\Codex\Printer\PatternModification();
$modification->setPattern('/foo/');
$modification->setReplacement('bar');
$printer->addModification($modification);
$printer->print();