Phalcon Logger

Logger\AbstractLogger

Abstract Logger Class

Abstract logger class, providing common functionality. A formatter interface is available as well as an adapter one. Adapters can be created easily using the built in AdapterFactory. A LoggerFactory is also available that allows developers to create new instances of the Logger or load them from config files (see Phalcon\Config\Config object).

@property AdapterInterface[] $adapters @property array<array-key, bool> $excluded @property int $logLevel @property string $name @property DateTimeZone $timezone

Uses DateTimeZone · Exception · Phalcon\Contracts\Logger\LoggerTypes · Phalcon\Logger\Adapter\AdapterInterface · Phalcon\Logger\Exceptions\AdapterNotFound · Phalcon\Logger\Exceptions\NoAdaptersConfigured · Phalcon\Time\Clock\ClockInterface · Phalcon\Time\Clock\SystemClock

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $name,
    array $adapters = [],
    DateTimeZone|null $timezone = null,
    ClockInterface|null $clock = null
);

Constructor.

addAdapter()

public function addAdapter(
    string $name,
    AdapterInterface $adapter
): static;

Add an adapter to the stack. For processing we use FIFO

begin()

public function begin(): static;

Starts a transaction on every (non-excluded) adapter in the stack.

commit()

public function commit(): static;

Commits the transaction on every (non-excluded) adapter in the stack.

excludeAdapters()

public function excludeAdapters( array $adapters = [] ): static;

Exclude certain adapters.

getAdapter()

public function getAdapter( string $name ): AdapterInterface;

Returns an adapter from the stack

getAdapters()

public function getAdapters(): array;

Returns the adapter stack array

getLogLevel()

public function getLogLevel(): int;

Returns the log level

getName()

public function getName(): string;

Returns the name of the logger

removeAdapter()

public function removeAdapter( string $name ): static;

Removes an adapter from the stack

rollback()

public function rollback(): static;

Rolls back the transaction on every (non-excluded) adapter in the stack.

setAdapters()

public function setAdapters( array $adapters ): static;

Sets the adapters stack overriding what is already there

setLogLevel()

public function setLogLevel( int $level ): static;

Sets the minimum log level for the logger.

An unknown level is not rejected: it is stored as CUSTOM, which sits between DEBUG and TRACE in the ordering, so the threshold becomes “everything except TRACE”.

addMessage()

protected function addMessage(
    int $level,
    string $message,
    array $context = []
): bool;

Adds a message to each handler for processing

getLevelNumber()

protected function getLevelNumber( mixed $level ): int;

Converts the level from string/word to an integer

getLevels()

protected function getLevels(): array;

Returns an array of log levels with integer to string conversion

Logger\AdapterFactory

Factory used to create adapters used for Logging

Uses Exception · Phalcon\Contracts\Logger\LoggerTypes · Phalcon\Factory\AbstractFactory · Phalcon\Logger\Adapter\AdapterInterface · Phalcon\Logger\Adapter\Noop · Phalcon\Logger\Adapter\Stream · Phalcon\Logger\Adapter\Syslog

Method Summary

Methods

__construct()

public function __construct( array $services = [] );

AdapterFactory constructor.

newInstance()

public function newInstance(
    string $name,
    string $fileName,
    array $options = []
): AdapterInterface;

Create a new instance of the adapter

getExceptionClass()

protected function getExceptionClass(): string;

getServices()

protected function getServices(): array;

Returns the available adapters

Logger\Adapter\AbstractAdapter

Class AbstractAdapter

Uses Phalcon\Contracts\Logger\LoggerTypes · Phalcon\Logger\Exceptions\DeserializationFailed · Phalcon\Logger\Exceptions\SerializationFailed · Phalcon\Logger\Exceptions\TransactionAlreadyActive · Phalcon\Logger\Exceptions\TransactionNotActive · Phalcon\Logger\Formatter\FormatterInterface · Phalcon\Logger\Formatter\Line · Phalcon\Logger\Item

Method Summary

Properties

Methods

__destruct()

public function __destruct();

Destructor cleanup

Throwing from a destructor is fatal during script shutdown, so an open transaction is auto-committed here (flushing the queued items) rather than throwing.

__serialize()

public function __serialize(): array;

__unserialize()

public function __unserialize( array $data ): void;

add()

public function add( Item $item ): AdapterInterface;

Adds a message to the queue

begin()

public function begin(): AdapterInterface;

Starts a transaction

close()

abstract public function close(): bool;

Closes the logger

commit()

public function commit(): AdapterInterface;

Commits the internal transaction

getFormatter()

public function getFormatter(): FormatterInterface;

Return the formatter used

getQueueLimit()

public function getQueueLimit(): int;

Returns the configured transaction-queue cap (0 = unlimited)

inTransaction()

public function inTransaction(): bool;

Returns the whether the logger is currently in an active transaction or not

process()

abstract public function process( Item $item ): void;

Processes the message in the adapter

rollback()

public function rollback(): AdapterInterface;

Rollbacks the internal transaction

setFormatter()

public function setFormatter( FormatterInterface $formatter ): AdapterInterface;

Sets the message formatter

setQueueLimit()

public function setQueueLimit( int $queueLimit ): AdapterInterface;

Sets the maximum number of items retained in the transaction queue. 0 disables the cap (the default; preserves the original unbounded behavior).

getFormattedItem()

protected function getFormattedItem( Item $item ): string;

Returns the formatted item

Logger\Adapter\AdapterInterface

Phalcon\Logger\AdapterInterface

Interface for Phalcon\Logger adapters

Uses Phalcon\Contracts\Logger\Adapter\Adapter

Logger\Adapter\Exceptions\FileOpenFailed

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $name,
    string $mode
);

Logger\Adapter\Exceptions\InvalidStreamMode

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct();

Logger\Adapter\Exceptions\SyslogOpenFailed

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct(
    string $name,
    int $facility
);

Logger\Adapter\Noop

Class Noop

@package Phalcon\Logger\Adapter

Uses Phalcon\Logger\Item

Method Summary

Methods

close()

public function close(): bool;

Closes the stream

process()

public function process( Item $item ): void;

Processes the message i.e. writes it to the file

Logger\Adapter\Stream

Phalcon\Logger\Adapter\Stream

Adapter to store logs in plain text files

$logger = new \Phalcon\Logger\Adapter\Stream('app/logs/test.log');

$logger->log('This is a message');
$logger->log(\Phalcon\Logger\Enum::ERROR, 'This is an error');
$logger->error('This is another error');

$logger->close();

@property resource|null $handler @property string $mode @property string $name

Uses Phalcon\Contracts\Logger\LoggerTypes · Phalcon\Logger\Adapter\Exceptions\FileOpenFailed · Phalcon\Logger\Adapter\Exceptions\InvalidStreamMode · Phalcon\Logger\Item · Phalcon\Traits\Php\FileTrait

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $name,
    array $options = []
);

Stream constructor.

close()

public function close(): bool;

Closes the stream

getName()

public function getName(): string;

Stream name

process()

public function process( Item $item ): void;

Processes the message i.e. writes it to the file

Logger\Adapter\Syslog

Class Syslog

@property string $defaultFormatter @property int $facility @property string $name @property bool $opened @property int $option

Uses Phalcon\Contracts\Logger\LoggerTypes · Phalcon\Logger\Adapter\Exceptions\SyslogOpenFailed · Phalcon\Logger\Enum · Phalcon\Logger\Item

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $name,
    array $options = []
);

Syslog constructor.

close()

public function close(): bool;

Closes the logger

process()

public function process( Item $item ): void;

Processes the message i.e. writes it to the syslog

openlog()

protected function openlog(
    string $ident,
    int $option,
    int $facility
): bool;

Open connection to system logger

Logger\Enum

Log Level Enum constants

Constants

Logger\Exception

Phalcon\Logger\Exception

Exceptions thrown in Phalcon\Logger will use this class

Logger\Exceptions\AdapterNotFound

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct( string $name );

Logger\Exceptions\DeserializationFailed

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct();

Logger\Exceptions\NoAdaptersConfigured

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct();

Logger\Exceptions\SerializationFailed

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct();

Logger\Exceptions\TransactionAlreadyActive

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct();

Logger\Exceptions\TransactionNotActive

Uses Phalcon\Logger\Exception

Method Summary

Methods

__construct()

public function __construct();

Logger\Formatter\AbstractFormatter

Class AbstractFormatter

Uses Phalcon\Contracts\Logger\LoggerTypes · Phalcon\Logger\Item · Phalcon\Traits\Support\Helper\Str\InterpolateTrait · Stringable

Method Summary

Properties

Methods

getDateFormat()

public function getDateFormat(): string;

setDateFormat()

public function setDateFormat( string $format ): void;

getFormattedDate()

protected function getFormattedDate( Item $item ): string;

Returns the date formatted for the logger.

getInterpolatedMessage()

protected function getInterpolatedMessage(
    Item $item,
    string $message
): string;

Returns the interpolated message, replacing context placeholders.

stringifyContext()

protected function stringifyContext( array $context ): array;

Reduces the log context to the string map interpolation requires.

Log context is PSR-3 shaped, so its values are arbitrary, while interpolation replaces a placeholder with a string. Anything that cannot be expressed as one - an array, an object without __toString() - substitutes as an empty string, so a placeholder is never left dangling and a non-stringable value can never abort the formatter mid-log.

Logger\Formatter\FormatterInterface

Phalcon\Logger\FormatterInterface

This interface must be implemented by formatters in Phalcon\Logger

Uses Phalcon\Contracts\Logger\Formatter\Formatter

Logger\Formatter\Json

Formats messages using JSON encoding

Uses JsonException · Phalcon\Logger\Item · Phalcon\Traits\Support\Helper\Json\EncodeTrait

Method Summary

Methods

__construct()

public function __construct(
    string $dateFormat = "c",
    string $interpolatorLeft = "%",
    string $interpolatorRight = "%"
);

Json constructor.

format()

public function format( Item $item ): string;

Applies a format to a message before sent it to the internal log

Logger\Formatter\Line

Class Line

Uses Exception · Phalcon\Logger\Item

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $format = "[%date%][%level%] %message%",
    string $dateFormat = "c",
    string $interpolatorLeft = "%",
    string $interpolatorRight = "%"
);

Line constructor.

format()

public function format( Item $item ): string;

Applies a format to a message before sent it to the internal log

getFormat()

public function getFormat(): string;

Return the format applied to each message

setFormat()

public function setFormat( string $format ): static;

Set the format applied to each message

Logger\Item

Phalcon\Logger\Item

Represents each item in a logging transaction

@property array<string, mixed> $context @property string $message @property int $level @property string $levelName @property DateTimeImmutable $dateTime

Uses DateTimeImmutable · Phalcon\Contracts\Logger\LoggerTypes

Method Summary

Properties

Methods

__construct()

public function __construct(
    string $message,
    string $levelName,
    int $level,
    DateTimeImmutable $dateTime,
    array $context = []
);

Item constructor.

getContext()

public function getContext(): array;

getDateTime()

public function getDateTime(): DateTimeImmutable;

getLevel()

public function getLevel(): int;

getLevelName()

public function getLevelName(): string;

getMessage()

public function getMessage(): string;

Logger\Logger

Phalcon Logger.

A logger, with various adapters and formatters. A formatter interface is available as well as an adapter one. Adapters can be created easily using the built-in AdapterFactory. A LoggerFactory is also available that allows developers to create new instances of the Logger or load them from config files (see Phalcon\Config\Config object).

Uses Phalcon\Contracts\Logger\LoggerTypes

Method Summary

Methods

alert()

public function alert(
    string $message,
    array $context = []
): void;

Action must be taken immediately.

Example: Entire website down, database unavailable, etc. This should trigger the SMS alerts and wake you up.

critical()

public function critical(
    string $message,
    array $context = []
): void;

Critical conditions.

Example: Application component unavailable, unexpected exception.

debug()

public function debug(
    string $message,
    array $context = []
): void;

Detailed debug information.

emergency()

public function emergency(
    string $message,
    array $context = []
): void;

System is unusable.

error()

public function error(
    string $message,
    array $context = []
): void;

Runtime errors that do not require immediate action but should typically be logged and monitored.

info()

public function info(
    string $message,
    array $context = []
): void;

Interesting events.

Example: User logs in, SQL logs.

log()

public function log(
    mixed $level,
    string $message,
    array $context = []
): void;

Logs with an arbitrary level.

An unknown level (a typo or an unmapped value) is not rejected; it maps to the CUSTOM level and is logged, rather than raising an exception.

notice()

public function notice(
    string $message,
    array $context = []
): void;

Normal but significant events.

trace()

public function trace(
    string $message,
    array $context = []
): void;

Extra-verbose diagnostic output.

Use for high-frequency, fine-grained events such as raw socket frames, HTTP response bodies, or internal state transitions that are too noisy for DEBUG.

warning()

public function warning(
    string $message,
    array $context = []
): void;

Exceptional occurrences that are not errors.

Example: Use of deprecated APIs, poor use of an API, undesirable things that are not necessarily wrong.

Logger\LoggerFactory

Factory creating logger objects

Uses DateTimeZone · Exception · Phalcon\Config\ConfigInterface · Phalcon\Contracts\Logger\LoggerTypes · Phalcon\Factory\AbstractConfigFactory

Method Summary

Methods

__construct()

public function __construct( AdapterFactory $factory );

Constructor

load()

public function load( mixed $config ): Logger;

Factory to create an instance from a Config object

The adapter list lives under options, not at the top level.

newInstance()

public function newInstance(
    string $name,
    array $adapters = [],
    DateTimeZone|null $timezone = null
): Logger;

Returns a Logger object

getExceptionClass()

protected function getExceptionClass(): string;

Logger\LoggerInterface

Interface for Phalcon based logger objects.

Uses Phalcon\Contracts\Logger\Logger