Yiisoft\Log\Message\Formatter

Complexity

Total Complexity

23

Size/Duplication

Total Lines	237
Duplicated Lines	0 %

Test Coverage

Coverage

100%

Importance

Changes	2
Bugs	0	Features	0

10 Methods

Rating	Name	Duplication	Size	Complexity
A	setFormat()	0	3	1
A	setTimestampFormat()	0	3	1
A	setPrefix()	0	3	1
B	getContext()	0	29	7
A	defaultFormat()	0	9	1
A	convertToString()	0	7	3
A	getTrace()	0	14	2
A	format()	0	16	3
A	getPrefix()	0	16	3
A	getTime()	0	12	1

<?php

declare(strict_types=1);

namespace Yiisoft\Log\Message;

use DateTime;
use RuntimeException;
use Yiisoft\Log\Message;
use Yiisoft\VarDumper\VarDumper;

use function gettype;
use function implode;
use function is_string;
use function is_object;
use function method_exists;
use function microtime;
use function sprintf;

/**
 * Formatter formats log messages.
 *
 * @internal
 *
 * @psalm-import-type Backtrace from Message
 */
final class Formatter
{
    /**
     * @var callable|null PHP callable that returns a string representation of the log message.
     *
     * If not set, {@see Formatter::defaultFormat()} will be used.
     *
     * The signature of the callable should be `function (Message $message, array $commonContext): string;`.
     */
    private $format;

    /**
     * @var callable|null PHP callable that returns a string to be prefixed to every exported message.
     *
     * If not set, {@see Formatter::getPrefix()} will be used, which prefixes
     * the message with context information such as user IP, user ID and session ID.
     *
     * The signature of the callable should be `function (Message $message, array $commonContext): string;`.
     */
    private $prefix;

    /**
     * @var string The date format for the log timestamp. Defaults to `Y-m-d H:i:s.u`.
     */
    private string $timestampFormat = 'Y-m-d H:i:s.u';

    /**
     * Sets the format for the string representation of the log message.
     *
     * @param callable $format The PHP callable to get a string representation of the log message.
     *
     * @see Formatter::$format
     */
    public function setFormat(callable $format): void
    {
        $this->format = $format;
    }

    /**
     * Sets a PHP callable that returns a string to be prefixed to every exported message.
     *
     * @param callable $prefix The PHP callable to get a string prefix of the log message.
     *
     * @see Formatter::$prefix
     */
    public function setPrefix(callable $prefix): void
    {
        $this->prefix = $prefix;
    }

    /**
     * Sets a date format for the log timestamp.
     *
     * @param string $timestampFormat The date format for the log timestamp.
     *
     * @see Formatter::$timestampFormat
     */
    public function setTimestampFormat(string $timestampFormat): void
    {
        $this->timestampFormat = $timestampFormat;
    }

    /**
     * Formats a log message for display as a string.
     *
     * @param Message $message The log message to be formatted.
     * @param array $commonContext The user parameters in the `key => value` format.
     *
     * @throws RuntimeException for a callable "format" that does not return a string.
     *
     * @return string The formatted log message.
     */
    public function format(Message $message, array $commonContext): string
    {
        if ($this->format === null) {
            return $this->defaultFormat($message, $commonContext);
        }

        $formatted = ($this->format)($message, $commonContext);

        if (!is_string($formatted)) {
            throw new RuntimeException(sprintf(
                'The PHP callable "format" must return a string, %s received.',
                gettype($formatted)
            ));
        }

        return $this->getPrefix($message, $commonContext) . $formatted;
    }

    /**
     * Default formats a log message for display as a string.
     *
     * @param Message $message The log message to be default formatted.
     * @param array $commonContext The user parameters in the `key => value` format.
     *
     * @return string The default formatted log message.
     */
    private function defaultFormat(Message $message, array $commonContext): string
    {
        $time = $this->getTime($message);
        $prefix = $this->getPrefix($message, $commonContext);
        $context = $this->getContext($message, $commonContext);
        /** @var string $category */
        $category = $message->context('category', CategoryFilter::DEFAULT);

        return "{$time} {$prefix}[{$message->level()}][{$category}] {$message->message()}{$context}";
    }

    /**
     * Gets formatted timestamp for message, according to {@see Formatter::$timestampFormat}.
     *
     * @param Message $message The log message.
     *
     * @return string Formatted timestamp for message.
     */
    private function getTime(Message $message): string
    {
        /** @psalm-suppress PossiblyInvalidCast */
        $timestamp = (string) $message->context('time', microtime(true));

        $format = match (true) {
            str_contains($timestamp, '.') => 'U.u',
            str_contains($timestamp, ',') => 'U,u',
            default => 'U',
        };

        return DateTime::createFromFormat($format, $timestamp)->format($this->timestampFormat);
    }

    /**
     * Gets a string to be prefixed to the given message.
     *
     * If {@see Formatter::$prefix} is configured it will return the result of the callback.
     * The default implementation will return user IP, user ID and session ID as a prefix.
     *
     * @param Message $message The log message being exported.
     * @param array $commonContext The user parameters in the `key => value` format.
     *
     * @throws RuntimeException for a callable "prefix" that does not return a string.
     *
     * @return string The log prefix string.
     */
    private function getPrefix(Message $message, array $commonContext): string
    {
        if ($this->prefix === null) {
            return '';
        }

        $prefix = ($this->prefix)($message, $commonContext);

        if (!is_string($prefix)) {
            throw new RuntimeException(sprintf(
                'The PHP callable "prefix" must return a string, %s received.',
                gettype($prefix)
            ));
        }

        return $prefix;
    }

    /**
     * Gets the context information to be logged.
     *
     * @param Message $message The log message.
     * @param array $commonContext The user parameters in the `key => value` format.
     *
     * @return string The context information. If an empty string, it means no context information.
     */
    private function getContext(Message $message, array $commonContext): string
    {
        $trace = $this->getTrace($message);
        $context = [];
        $common = [];

        if ($trace !== '') {
            $context[] = $trace;
        }

        /**
         * @var array-key $name
         * @var mixed $value
         */
        foreach ($message->context() as $name => $value) {
            if ($name !== 'trace') {
                $context[] = "{$name}: " . $this->convertToString($value);
            }
        }

        /**
         * @var mixed $value
         */
        foreach ($commonContext as $name => $value) {
            $common[] = "{$name}: " . $this->convertToString($value);
        }

        return (empty($context) ? '' : "\n\nMessage context:\n\n" . implode("\n", $context))
            . (empty($common) ? '' : "\n\nCommon context:\n\n" . implode("\n", $common)) . "\n";
    }

    /**
     * Gets debug backtrace in string representation.
     *
     * @param Message $message The log message.
     *
     * @return string Debug backtrace in string representation.
     */
    private function getTrace(Message $message): string
    {
        /** @psalm-var Backtrace $traces */
        $traces = $message->context('trace', []);
        if (empty($traces)) {
            return '';
        }

        $lines = array_map(
            static fn (array $trace): string => "in {$trace['file']}:{$trace['line']}",
            $traces,
        );

        return "trace:\n    " . implode("\n    ", $lines);
    }

    /**
     * Converts a value to a string.
     *
     * @param mixed $value The value to convert.
     *
     * @return string Converted string.
     */
    private function convertToString(mixed $value): string
    {
        if (is_object($value) && method_exists($value, '__toString')) {
            return (string) $value;
        }

        return VarDumper::create($value)->asString();
    }
}