0

Abstract Class Yiisoft\Log\Target

All Classes | Methods | Constants
InheritanceYiisoft\Log\Target
SubclassesYiisoft\Log\PsrTarget, Yiisoft\Log\StreamTarget

Target is the base class for all log target classes.

A log target object will filter the messages logged by {@see \Yiisoft\Log\Logger} according to its {@see \Yiisoft\Log\Target::setLevels()} and {@see \Yiisoft\Log\Target::setCategories()}. It may also export the filtered messages to specific destination defined by the target, such as emails, files.

Level filter and category filter are combinatorial, i.e., only messages satisfying both filter conditions will be handled. Additionally, you may specify {@see \Yiisoft\Log\Target::setExcept()} to exclude messages of certain categories.

Public Methods

Hide inherited methods

Method Description Defined By
__construct() When defining a constructor in child classes, you must call parent::__construct(). Yiisoft\Log\Target
collect() Processes the given log messages. Yiisoft\Log\Target
disable() Disables the log target. Yiisoft\Log\Target
enable() Enables the log target. Yiisoft\Log\Target
isEnabled() Check whether the log target is enabled. Yiisoft\Log\Target
setCategories() Sets a list of log message categories that this target is interested in. Yiisoft\Log\Target
setCommonContext() Sets a user parameters in the key => value format that should be logged in a each message. Yiisoft\Log\Target
setEnabled() Sets a PHP callable that returns a boolean indicating whether this log target is enabled. Yiisoft\Log\Target
setExcept() Sets a list of log message categories that this target is NOT interested in. Yiisoft\Log\Target
setExportInterval() Sets how many messages should be accumulated before they are exported. Yiisoft\Log\Target
setFormat() Sets a PHP callable that returns a string representation of the log message. Yiisoft\Log\Target
setLevels() Sets a list of {@see LogLevel log message levels} that current target is interested in. Yiisoft\Log\Target
setPrefix() Sets a PHP callable that returns a string to be prefixed to every exported message. Yiisoft\Log\Target
setTimestampFormat() Sets a date format for the log timestamp. Yiisoft\Log\Target

Protected Methods

Hide inherited methods

Method Description Defined By
export() Exports log messages to a specific destination. Yiisoft\Log\Target
formatMessages() Formats all log messages for display as a string. Yiisoft\Log\Target
getCommonContext() Gets a user parameters in the key => value format that should be logged in a each message. Yiisoft\Log\Target
getFormattedMessages() Gets a list of formatted log messages. Yiisoft\Log\Target
getMessages() Gets a list of log messages that are retrieved from the logger so far by this log target. Yiisoft\Log\Target

Constants

Hide inherited constants

Constant Value Description Defined By
DEFAULT_EXPORT_INTERVAL 1000 Yiisoft\Log\Target

Method Details

Hide inherited methods

__construct() public method

When defining a constructor in child classes, you must call parent::__construct().

public mixed __construct ( string[] $levels = [], string[] $categories = [], string[] $exceptCategories = [], callable|null $format = null, callable|null $prefix = null, string|null $timestampFormat = null, integer $exportInterval = self::DEFAULT_EXPORT_INTERVAL, boolean|callable $enabled = true )
$levels string[]

The {@see \Psr\Log\LogLevel log message levels} that this target is interested in.
$categories string[]

The log message categories that this target is interested in.
$exceptCategories string[]

The log message categories that this target is NOT interested in.
$format callable|null

A PHP callable that returns a string representation of the log message.
$prefix callable|null

A PHP callable that returns a string to be prefixed to every exported message.
$timestampFormat string|null

The date format for the log timestamp.
$exportInterval integer

How many messages should be accumulated before they are exported.
$enabled boolean|callable

Whether this target is enabled, or a PHP callable that returns a boolean.

 

                public function __construct(
    array $levels = [],
    array $categories = [],
    array $exceptCategories = [],
    ?callable $format = null,
    ?callable $prefix = null,
    ?string $timestampFormat = null,
    private int $exportInterval = self::DEFAULT_EXPORT_INTERVAL,
    bool|callable $enabled = true,
) {
    $this->categories = new CategoryFilter($categories, $exceptCategories);
    $this->formatter = new Formatter($format, $prefix, $timestampFormat);
    /** @psalm-suppress DeprecatedMethod */
    $this->setLevels($levels);
    $this->enabled = $enabled;
}
collect() public method

Processes the given log messages.

This method will filter the given messages with levels and categories. And if requested, it will also export the filtering result to specific medium (e.g. email).

public void collect ( Yiisoft\Log\Message[] $messages, boolean $final )
$messages Yiisoft\Log\Message[]

Log messages to be processed.
$final boolean

Whether this method is called at the end of the current application.

 

                public function collect(array $messages, bool $final): void
{
    $this->filterMessages($messages);
    $count = count($this->messages);
    if ($count > 0 && ($final || ($this->exportInterval > 0 && $count >= $this->exportInterval))) {
        // set exportInterval to 0 to avoid triggering export again while exporting
        $oldExportInterval = $this->exportInterval;
        $this->exportInterval = 0;
        $this->export();
        $this->exportInterval = $oldExportInterval;
        $this->messages = [];
    }
}
disable() public method

Disables the log target.

See also \Yiisoft\Log\Target::$enabled.

public self disable ( )

                public function disable(): self
{
    $this->enabled = false;
    return $this;
}
enable() public method

Enables the log target.

See also \Yiisoft\Log\Target::$enabled.

public self enable ( )

                public function enable(): self
{
    $this->enabled = true;
    return $this;
}
export() protected abstract method

Exports log messages to a specific destination.

Child classes must implement this method.

protected abstract void export ( )

                abstract protected function export(): void;
formatMessages() protected method

Formats all log messages for display as a string.

protected string formatMessages ( string $separator = '' )
$separator string

The log messages string separator.
return string

The string formatted log messages.

 

                protected function formatMessages(string $separator = ''): string
{
    $formatted = '';
    foreach ($this->messages as $message) {
        $formatted .= $this->formatter->format($message, $this->commonContext) . $separator;
    }
    return $formatted;
}
getCommonContext() protected method
Deprecated since 2.1, to be removed in 3.0. Use {@see \Yiisoft\Log\ContextProvider\CommonContextProvider} instead.

Gets a user parameters in the key => value format that should be logged in a each message.

protected array getCommonContext ( )
return array

The user parameters in the key => value format.

 

                protected function getCommonContext(): array
{
    return $this->commonContext;
}
getFormattedMessages() protected method

Gets a list of formatted log messages.

protected string[] getFormattedMessages ( )
return string[]

The list of formatted log messages.

 

                protected function getFormattedMessages(): array
{
    $formatted = [];
    foreach ($this->messages as $key => $message) {
        $formatted[$key] = $this->formatter->format($message, $this->commonContext);
    }
    return $formatted;
}
getMessages() protected method

Gets a list of log messages that are retrieved from the logger so far by this log target.

protected Yiisoft\Log\Message[] getMessages ( )
return Yiisoft\Log\Message[]

The list of log messages.

 

                protected function getMessages(): array
{
    return $this->messages;
}
isEnabled() public method

Check whether the log target is enabled.

See also \Yiisoft\Log\Target::$enabled.

public boolean isEnabled ( )
return boolean

The value indicating whether this log target is enabled.
throws RuntimeException

for a callable "enabled" that does not return a boolean.

 

                public function isEnabled(): bool
{
    if (is_bool($this->enabled)) {
        return $this->enabled;
    }
    if (!is_bool($enabled = ($this->enabled)())) {
        throw new RuntimeException(sprintf(
            'The PHP callable "enabled" must returns a boolean, %s received.',
            get_debug_type($enabled),
        ));
    }
    return $enabled;
}
setCategories() public method
Deprecated To be removed in 3.0. Use the $categories constructor parameter instead.

Sets a list of log message categories that this target is interested in.

See also \Yiisoft\Log\Message\CategoryFilter::$include.

public self setCategories ( string[] $categories )
$categories string[]

The list of log message categories.
throws InvalidArgumentException

for invalid log message categories structure.

 

                public function setCategories(array $categories): self
{
    $this->categories->include($categories);
    return $this;
}
setCommonContext() public method
Deprecated since 2.1, to be removed in 3.0. Use {@see \Yiisoft\Log\ContextProvider\CommonContextProvider} instead.

Sets a user parameters in the key => value format that should be logged in a each message.

See also \Yiisoft\Log\Target::$commonContext.

public self setCommonContext ( array $commonContext )
$commonContext array

The user parameters in the key => value format.

 

                public function setCommonContext(array $commonContext): self
{
    $this->commonContext = $commonContext;
    return $this;
}
setEnabled() public method
Deprecated To be removed in 3.0. Use the $enabled constructor parameter instead.

Sets a PHP callable that returns a boolean indicating whether this log target is enabled.

The signature of the callable should be function (): bool;.

See also \Yiisoft\Log\Target::$enabled.

public self setEnabled ( callable $value )
$value callable

The PHP callable to get a boolean value.

 

                public function setEnabled(callable $value): self
{
    $this->enabled = $value;
    return $this;
}
setExcept() public method
Deprecated To be removed in 3.0. Use the $exceptCategories constructor parameter instead.

Sets a list of log message categories that this target is NOT interested in.

See also \Yiisoft\Log\Message\CategoryFilter::$exclude.

public self setExcept ( string[] $except )
$except string[]

The list of log message categories.
throws InvalidArgumentException

for invalid log message categories structure.

 

                public function setExcept(array $except): self
{
    $this->categories->exclude($except);
    return $this;
}
setExportInterval() public method
Deprecated To be removed in 3.0. Use the $exportInterval constructor parameter instead.

Sets how many messages should be accumulated before they are exported.

See also \Yiisoft\Log\Target::$exportInterval.

public self setExportInterval ( integer $exportInterval )
$exportInterval integer

The number of log messages to accumulate before exporting.

 

                public function setExportInterval(int $exportInterval): self
{
    $this->exportInterval = $exportInterval;
    return $this;
}
setFormat() public method
Deprecated To be removed in 3.0. Use the $format constructor parameter instead.

Sets a PHP callable that returns a string representation of the log message.

See also \Yiisoft\Log\Message\Formatter::$format.

public self setFormat ( callable $format )
$format callable

The PHP callable to get a string value from.

 

                public function setFormat(callable $format): self
{
    $this->formatter->setFormat($format);
    return $this;
}
setLevels() public method
Deprecated To be removed in 3.0. Use the $levels constructor parameter instead.

Sets a list of {@see LogLevel log message levels} that current target is interested in.

See also \Yiisoft\Log\Target::$levels.

public self setLevels ( string[] $levels )
$levels string[]

The list of log message levels.
throws InvalidArgumentException

for invalid log message level.

 

                public function setLevels(array $levels): self
{
    foreach ($levels as $level) {
        Logger::assertLevelIsValid($level);
    }
    $this->levels = $levels;
    return $this;
}
setPrefix() public method
Deprecated To be removed in 3.0. Use the $prefix constructor parameter instead.

Sets a PHP callable that returns a string to be prefixed to every exported message.

See also \Yiisoft\Log\Message\Formatter::$prefix.

public self setPrefix ( callable $prefix )
$prefix callable

The PHP callable to get a string prefix of the log message.

 

                public function setPrefix(callable $prefix): self
{
    $this->formatter->setPrefix($prefix);
    return $this;
}
setTimestampFormat() public method
Deprecated To be removed in 3.0. Use the $timestampFormat constructor parameter instead.

Sets a date format for the log timestamp.

See also \Yiisoft\Log\Target::$timestampFormat.

public self setTimestampFormat ( string $format )
$format string

The date format for the log timestamp.

 

                public function setTimestampFormat(string $format): self
{
    $this->formatter->setTimestampFormat($format);
    return $this;
}