Download the PHP package terrazza/logger without Composer

Terrazza/Logger

This component is an implementation of PSR/Log standard with some extensions.

Structure

1. the Logger component
   has to be initialized with 0-n ChannelHandler
   and provides the common known methods:
   • warning
   • error
   • notice
   • ...
2. the ChannelHandler component
   is responsible to determine
   1. the target/writer (required)
   2. the recordFormatter (required)
   3. a channelFilter (optional)
   4. all related LogHandler for this channel
3. the LogHandler component
   determines
   • the logLevel
   • the format (optional, default: from ChannelHandler->recordFormatter)

The Terrazza/Logger component differ to the common PSR/Log implementation in handling the "Format". The Writer Component handles multiple "rows" and combines it. Within this difference its possible to forward a transformed format and keep his keys per row.
For example: write the message/format into a json object or db.

Object/Classes

1. Logger
   1. method: registerChannelHandler
   2. method: registerExceptionHandler
   3. method: registerErrorHandler
   4. method: registerFatalHandler
   5. method: setExceptionFileName
   6. constructor: context (array)
2. Handler
   1. ChannelHandler
   2. LogHandler
3. LogRecord
   1. LogRecordTrace
4. LogRecordFormatter
5. LogHandlerFilter
6. Converter
7. Install
8. Requirements
9. Examples

Logger

The Logger object/methods is/are close to the common PSR implementations but!
The Logger is initialized with channelHandler(s) and not Handler

each channelHandler executes only one logHandler

method: registerChannelHandler

adds a channelHandler to the logger (not immutable).

method: registerExceptionHandler

register a callback for php exception handler.

well-developed projects should handle/cover all exceptions by themselves, but ;-)

method: registerErrorHandler

register a callback for php error handler.

sometime this kind of errors can't be catched without this workaround

method: registerFatalHandler

register a callback for php shutdown.

sometime this kind of errors can't be catched without this workaround

method: setExceptionFileName

The method:addMessage itself is covered with try/catch.
The catch handler writes the Exception.Message to a file which can be set with the method setExceptionFileName.

notice:
default: php://stderr

constructor: context (array)

The logger can be initialized, next to the name, with an initialized context.
This context can be addressed separately.

example of usage
a class is injected with the component and inside the constructor

Handler

ChannelHandler

A ChannelHandler collects LogHandler to the same channel and provides

• the same writer
• the same formatter
  for each LogHandler.

A ChannelHandler can be registered through the Logger with

• the method: registerChannelHandler
• the __constructor (3rd argument as variadic)

method: getWriter

method: getFormatter

method: getFilter

method: getLogHandler (LogHandlerInterface[])

method: pushLogHandler

Method to add a new LogHandler.
The logHandler-array will be key-sorted, to prevent multiple write transaction for different LogLevels.

method: getEffectedHandler

return the matched LogHandler for a given LogRecord.

method: writeRecord

for a passed LogHandler the record will be

• formatted
• and written to the Writer

LogHandler

The SingleHandler provides the common way to create a handler for a Logger. The only difference to the common implementation:

• instead of logLevel
• the SingleHandler has to be injected within a Channel

LogRecord

Against the common PSR implementation our component deals with an object and not an array.
LogRecord properties:

• logDate (\Datetime)
• loggerName (string)
• logLevel (int)
• logMessage (string)
• memUsed (int)
• memAllocated (int)
• LogRecordTrace
• context (array)
• initContext (array)

additional, the object provides

• logLevelName (string)

method/static createRecord

this method is used inside Logger to create a new LogRecord object.

method: getToken()

this method is used in the LogRecordFormatterInterface to get the LogRecord "encoded". Every element can be accessed through his "format" e.g. {Level}{LevelName}{Context.name}

LogRecordTrace

The LogRecordTrace object is generated in the LogRecord is created.
Base on _debug_backtrace(DEBUG_BACKTRACE_IGNOREARGS) every Record get additional properties:

• Namespace
• Classname
• Function
• Line

LogRecordFormatter

The LogRecordFormatter converts/maps a record to an array
. Initialized properties:

• NonScalarConverterInterface
• format (array)
• valueConverter (array, optional)

NonScalarConverter (NonScalarConverterInterface)

The NonScalarConverter convert a nonScalar value (e.g. from Context) into a string.
Actually the provided class NonScalarJsonEncode use json_encode and prefix it with the attribute name.

The NonScalarConverter is used, when a formatter-line includes a nonScalar and a scalar content.

example of usage:

a ValueConverter (LogRecordValueConverterInterface) can be used to convert special value based on his key.

method: pushConverter

to map/convert a special value, based on his key, push a special converter.
This converter has to fulfill LogRecordValueConverterInterface.

method: formatRecord

Maps the Record against the $format and returns a mapped array.
Unknown patterns (e.g. {undefined}) are removed from the response.
Empty "Lines" are also removed.

example

The example uses an additional ValueConverter for the Record value "Date". `

LogHandlerFilter

LogHandler can have a LogHandlerFilter.
Properties:

• include (array, optional)
• exclude (array, optional)
• start (array, optional)

  method: isHandling (string $callerNamespace) : bool

  include
  preg_match callerNamespace against include patterns
  exclude
  preg_match callerNamespace against exclude patterns
  start
  preg_match callerNamespace against start patterns
  if pregmatch is true all further isHandling will be true. (exclude filter overrules start)_

Converter

A RecordFormatter
Afterwards, it depends on the target/writer the array has to be formatted again.

We actually include/provide two Converter:

• convert to a string, json type
• convert to a string, e.g. for console logging In any case the Converter is injected into the Writer.

FormattedRecordFlat

Converts the mapped LogRecord into a string within a delimiter for each row.
For nonScalar values we use json_encode to convert the value.

method: setNonScalarPrefix(string $delimiter)

by using this method nonScalar values will be prefixed with the dataKey and the delimiter.
arguments:

• delimiter (string, required)
• encodingFlags (int, optional)

example of usage:

FormattedRecordJson

Converts the mapped LogRecord into a string by using json_encode.
arguments:

• encodingFlags (int, optional)

example of usage:

Writer

StreamFile

Save converted record to a file.
arguments:

• converter (IFormattedRecordConverter, required)
• filename (string required)
• flags (int, optional, default: 0)

the converter should convert the formatted LogRecord into a string.

How to install

Install via composer

Requirements

• php >= 7.4

  composer packages

• psr/log

Examples

1. create a ChannelHandler

2. create a LogHandler

notice
next code lines depends on previous example... (create a ChannelHandler)

3. create within a handler

notice:
next code lines depends on previous example... (create a LogHandler)

create and registerChannelHandler

Usage of Logger

produce a NOTICE

produce an ERROR