vendor/monolog/monolog/src/Monolog/Logger.php line 630

  1. <?php declare(strict_types=1);
  3. /*
  4.  * This file is part of the Monolog package.
  5.  *
  6.  * (c) Jordi Boggiano <j.boggiano@seld.be>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Monolog;
  14. use Closure;
  15. use DateTimeZone;
  16. use Fiber;
  17. use Monolog\Handler\HandlerInterface;
  18. use Monolog\Processor\ProcessorInterface;
  19. use Psr\Log\LoggerInterface;
  20. use Psr\Log\InvalidArgumentException;
  21. use Psr\Log\LogLevel;
  22. use Throwable;
  23. use Stringable;
  24. use WeakMap;
  26. /**
  27.  * Monolog log channel
  28.  *
  29.  * It contains a stack of Handlers and a stack of Processors,
  30.  * and uses them to store records that are added to it.
  31.  *
  32.  * @author Jordi Boggiano <j.boggiano@seld.be>
  33.  * @final
  34.  */
  35. class Logger implements LoggerInterface, ResettableInterface
  36. {
  37.     /**
  38.      * Detailed debug information
  39.      *
  40.      * @deprecated Use \Monolog\Level::Debug
  41.      */
  42.     public const DEBUG = 100;
  44.     /**
  45.      * Interesting events
  46.      *
  47.      * Examples: User logs in, SQL logs.
  48.      *
  49.      * @deprecated Use \Monolog\Level::Info
  50.      */
  51.     public const INFO = 200;
  53.     /**
  54.      * Uncommon events
  55.      *
  56.      * @deprecated Use \Monolog\Level::Notice
  57.      */
  58.     public const NOTICE = 250;
  60.     /**
  61.      * Exceptional occurrences that are not errors
  62.      *
  63.      * Examples: Use of deprecated APIs, poor use of an API,
  64.      * undesirable things that are not necessarily wrong.
  65.      *
  66.      * @deprecated Use \Monolog\Level::Warning
  67.      */
  68.     public const WARNING = 300;
  70.     /**
  71.      * Runtime errors
  72.      *
  73.      * @deprecated Use \Monolog\Level::Error
  74.      */
  75.     public const ERROR = 400;
  77.     /**
  78.      * Critical conditions
  79.      *
  80.      * Example: Application component unavailable, unexpected exception.
  81.      *
  82.      * @deprecated Use \Monolog\Level::Critical
  83.      */
  84.     public const CRITICAL = 500;
  86.     /**
  87.      * Action must be taken immediately
  88.      *
  89.      * Example: Entire website down, database unavailable, etc.
  90.      * This should trigger the SMS alerts and wake you up.
  91.      *
  92.      * @deprecated Use \Monolog\Level::Alert
  93.      */
  94.     public const ALERT = 550;
  96.     /**
  97.      * Urgent alert.
  98.      *
  99.      * @deprecated Use \Monolog\Level::Emergency
  100.      */
  101.     public const EMERGENCY = 600;
  103.     /**
  104.      * Monolog API version
  105.      *
  106.      * This is only bumped when API breaks are done and should
  107.      * follow the major version of the library
  108.      */
  109.     public const API = 3;
  111.     /**
  112.      * Mapping between levels numbers defined in RFC 5424 and Monolog ones
  113.      *
  114.      * @phpstan-var array<int, Level> $rfc_5424_levels
  115.      */
  116.     private const RFC_5424_LEVELS = [
  117.         7 => Level::Debug,
  118.         6 => Level::Info,
  119.         5 => Level::Notice,
  120.         4 => Level::Warning,
  121.         3 => Level::Error,
  122.         2 => Level::Critical,
  123.         1 => Level::Alert,
  124.         0 => Level::Emergency,
  125.     ];
  127.     protected string $name;
  129.     /**
  130.      * The handler stack
  131.      *
  132.      * @var list<HandlerInterface>
  133.      */
  134.     protected array $handlers;
  136.     /**
  137.      * Processors that will process all log records
  138.      *
  139.      * To process records of a single handler instead, add the processor on that specific handler
  140.      *
  141.      * @var array<(callable(LogRecord): LogRecord)|ProcessorInterface>
  142.      */
  143.     protected array $processors;
  145.     protected bool $microsecondTimestamps = true;
  147.     protected DateTimeZone $timezone;
  149.     protected Closure|null $exceptionHandler = null;
  151.     /**
  152.      * Keeps track of depth to prevent infinite logging loops
  153.      */
  154.     private int $logDepth = 0;
  156.     /**
  157.      * @var WeakMap<Fiber<mixed, mixed, mixed, mixed>, int> Keeps track of depth inside fibers to prevent infinite logging loops
  158.      */
  159.     private WeakMap $fiberLogDepth;
  161.     /**
  162.      * Whether to detect infinite logging loops
  163.      * This can be disabled via {@see useLoggingLoopDetection} if you have async handlers that do not play well with this
  164.      */
  165.     private bool $detectCycles = true;
  167.     /**
  168.      * @param string             $name       The logging channel, a simple descriptive name that is attached to all log records
  169.      * @param HandlerInterface[] $handlers   Optional stack of handlers, the first one in the array is called first, etc.
  170.      * @param callable[]         $processors Optional array of processors
  171.      * @param DateTimeZone|null  $timezone   Optional timezone, if not provided date_default_timezone_get() will be used
  172.      *
  173.      * @phpstan-param array<(callable(LogRecord): LogRecord)|ProcessorInterface> $processors
  174.      */
  175.     public function __construct(string $name, array $handlers = [], array $processors = [], DateTimeZone|null $timezone = null)
  176.     {
  177.         $this->name = $name;
  178.         $this->setHandlers($handlers);
  179.         $this->processors = $processors;
  180.         $this->timezone = $timezone ?? new DateTimeZone(date_default_timezone_get());
  181.         $this->fiberLogDepth = new \WeakMap();
  182.     }
  184.     public function getName(): string
  185.     {
  186.         return $this->name;
  187.     }
  189.     /**
  190.      * Return a new cloned instance with the name changed
  191.      */
  192.     public function withName(string $name): self
  193.     {
  194.         $new = clone $this;
  195.         $new->name = $name;
  197.         return $new;
  198.     }
  200.     /**
  201.      * Pushes a handler on to the stack.
  202.      */
  203.     public function pushHandler(HandlerInterface $handler): self
  204.     {
  205.         array_unshift($this->handlers, $handler);
  207.         return $this;
  208.     }
  210.     /**
  211.      * Pops a handler from the stack
  212.      *
  213.      * @throws \LogicException If empty handler stack
  214.      */
  215.     public function popHandler(): HandlerInterface
  216.     {
  217.         if (0 === \count($this->handlers)) {
  218.             throw new \LogicException('You tried to pop from an empty handler stack.');
  219.         }
  221.         return array_shift($this->handlers);
  222.     }
  224.     /**
  225.      * Set handlers, replacing all existing ones.
  226.      *
  227.      * If a map is passed, keys will be ignored.
  228.      *
  229.      * @param list<HandlerInterface> $handlers
  230.      */
  231.     public function setHandlers(array $handlers): self
  232.     {
  233.         $this->handlers = [];
  234.         foreach (array_reverse($handlers) as $handler) {
  235.             $this->pushHandler($handler);
  236.         }
  238.         return $this;
  239.     }
  241.     /**
  242.      * @return list<HandlerInterface>
  243.      */
  244.     public function getHandlers(): array
  245.     {
  246.         return $this->handlers;
  247.     }
  249.     /**
  250.      * Adds a processor on to the stack.
  251.      *
  252.      * @phpstan-param ProcessorInterface|(callable(LogRecord): LogRecord) $callback
  253.      */
  254.     public function pushProcessor(ProcessorInterface|callable $callback): self
  255.     {
  256.         array_unshift($this->processors, $callback);
  258.         return $this;
  259.     }
  261.     /**
  262.      * Removes the processor on top of the stack and returns it.
  263.      *
  264.      * @phpstan-return ProcessorInterface|(callable(LogRecord): LogRecord)
  265.      * @throws \LogicException If empty processor stack
  266.      */
  267.     public function popProcessor(): callable
  268.     {
  269.         if (0 === \count($this->processors)) {
  270.             throw new \LogicException('You tried to pop from an empty processor stack.');
  271.         }
  273.         return array_shift($this->processors);
  274.     }
  276.     /**
  277.      * @return callable[]
  278.      * @phpstan-return array<ProcessorInterface|(callable(LogRecord): LogRecord)>
  279.      */
  280.     public function getProcessors(): array
  281.     {
  282.         return $this->processors;
  283.     }
  285.     /**
  286.      * Control the use of microsecond resolution timestamps in the 'datetime'
  287.      * member of new records.
  288.      *
  289.      * As of PHP7.1 microseconds are always included by the engine, so
  290.      * there is no performance penalty and Monolog 2 enabled microseconds
  291.      * by default. This function lets you disable them though in case you want
  292.      * to suppress microseconds from the output.
  293.      *
  294.      * @param bool $micro True to use microtime() to create timestamps
  295.      */
  296.     public function useMicrosecondTimestamps(bool $micro): self
  297.     {
  298.         $this->microsecondTimestamps = $micro;
  300.         return $this;
  301.     }
  303.     public function useLoggingLoopDetection(bool $detectCycles): self
  304.     {
  305.         $this->detectCycles = $detectCycles;
  307.         return $this;
  308.     }
  310.     /**
  311.      * Adds a log record.
  312.      *
  313.      * @param  int               $level    The logging level (a Monolog or RFC 5424 level)
  314.      * @param  string            $message  The log message
  315.      * @param  mixed[]           $context  The log context
  316.      * @param  DateTimeImmutable $datetime Optional log date to log into the past or future
  317.      * @return bool              Whether the record has been processed
  318.      *
  319.      * @phpstan-param value-of<Level::VALUES>|Level $level
  320.      */
  321.     public function addRecord(int|Level $level, string $message, array $context = [], DateTimeImmutable $datetime = null): bool
  322.     {
  323.         if (is_int($level) && isset(self::RFC_5424_LEVELS[$level])) {
  324.             $level = self::RFC_5424_LEVELS[$level];
  325.         }
  327.         if ($this->detectCycles) {
  328.             if (null !== ($fiber = Fiber::getCurrent())) {
  329.                 $logDepth = $this->fiberLogDepth[$fiber] = ($this->fiberLogDepth[$fiber] ?? 0) + 1;
  330.             } else {
  331.                 $logDepth = ++$this->logDepth;
  332.             }
  333.         } else {
  334.             $logDepth = 0;
  335.         }
  337.         if ($logDepth === 3) {
  338.             $this->warning('A possible infinite logging loop was detected and aborted. It appears some of your handler code is triggering logging, see the previous log record for a hint as to what may be the cause.');
  339.             return false;
  340.         } elseif ($logDepth >= 5) { // log depth 4 is let through, so we can log the warning above
  341.             return false;
  342.         }
  344.         try {
  345.             $recordInitialized = count($this->processors) === 0;
  347.             $record = new LogRecord(
  348.                 message: $message,
  349.                 context: $context,
  350.                 level: self::toMonologLevel($level),
  351.                 channel: $this->name,
  352.                 datetime: $datetime ?? new DateTimeImmutable($this->microsecondTimestamps, $this->timezone),
  353.                 extra: [],
  354.             );
  355.             $handled = false;
  357.             foreach ($this->handlers as $handler) {
  358.                 if (false === $recordInitialized) {
  359.                     // skip initializing the record as long as no handler is going to handle it
  360.                     if (!$handler->isHandling($record)) {
  361.                         continue;
  362.                     }
  364.                     try {
  365.                         foreach ($this->processors as $processor) {
  366.                             $record = $processor($record);
  367.                         }
  368.                         $recordInitialized = true;
  369.                     } catch (Throwable $e) {
  370.                         $this->handleException($e, $record);
  372.                         return true;
  373.                     }
  374.                 }
  376.                 // once the record is initialized, send it to all handlers as long as the bubbling chain is not interrupted
  377.                 try {
  378.                     $handled = true;
  379.                     if (true === $handler->handle($record)) {
  380.                         break;
  381.                     }
  382.                 } catch (Throwable $e) {
  383.                     $this->handleException($e, $record);
  385.                     return true;
  386.                 }
  387.             }
  389.             return $handled;
  390.         } finally {
  391.             if ($this->detectCycles) {
  392.                 if (isset($fiber)) {
  393.                     $this->fiberLogDepth[$fiber]--;
  394.                 } else {
  395.                     $this->logDepth--;
  396.                 }
  397.             }
  398.         }
  399.     }
  401.     /**
  402.      * Ends a log cycle and frees all resources used by handlers.
  403.      *
  404.      * Closing a Handler means flushing all buffers and freeing any open resources/handles.
  405.      * Handlers that have been closed should be able to accept log records again and re-open
  406.      * themselves on demand, but this may not always be possible depending on implementation.
  407.      *
  408.      * This is useful at the end of a request and will be called automatically on every handler
  409.      * when they get destructed.
  410.      */
  411.     public function close(): void
  412.     {
  413.         foreach ($this->handlers as $handler) {
  414.             $handler->close();
  415.         }
  416.     }
  418.     /**
  419.      * Ends a log cycle and resets all handlers and processors to their initial state.
  420.      *
  421.      * Resetting a Handler or a Processor means flushing/cleaning all buffers, resetting internal
  422.      * state, and getting it back to a state in which it can receive log records again.
  423.      *
  424.      * This is useful in case you want to avoid logs leaking between two requests or jobs when you
  425.      * have a long running process like a worker or an application server serving multiple requests
  426.      * in one process.
  427.      */
  428.     public function reset(): void
  429.     {
  430.         foreach ($this->handlers as $handler) {
  431.             if ($handler instanceof ResettableInterface) {
  432.                 $handler->reset();
  433.             }
  434.         }
  436.         foreach ($this->processors as $processor) {
  437.             if ($processor instanceof ResettableInterface) {
  438.                 $processor->reset();
  439.             }
  440.         }
  441.     }
  443.     /**
  444.      * Gets the name of the logging level as a string.
  445.      *
  446.      * This still returns a string instead of a Level for BC, but new code should not rely on this method.
  447.      *
  448.      * @throws \Psr\Log\InvalidArgumentException If level is not defined
  449.      *
  450.      * @phpstan-param  value-of<Level::VALUES>|Level $level
  451.      * @phpstan-return value-of<Level::NAMES>
  452.      *
  453.      * @deprecated Since 3.0, use {@see toMonologLevel} or {@see \Monolog\Level->getName()} instead
  454.      */
  455.     public static function getLevelName(int|Level $level): string
  456.     {
  457.         return self::toMonologLevel($level)->getName();
  458.     }
  460.     /**
  461.      * Converts PSR-3 levels to Monolog ones if necessary
  462.      *
  463.      * @param  int|string|Level|LogLevel::* $level Level number (monolog) or name (PSR-3)
  464.      * @throws \Psr\Log\InvalidArgumentException      If level is not defined
  465.      *
  466.      * @phpstan-param value-of<Level::VALUES>|value-of<Level::NAMES>|Level|LogLevel::* $level
  467.      */
  468.     public static function toMonologLevel(string|int|Level $level): Level
  469.     {
  470.         if ($level instanceof Level) {
  471.             return $level;
  472.         }
  474.         if (\is_string($level)) {
  475.             if (\is_numeric($level)) {
  476.                 $levelEnum = Level::tryFrom((int) $level);
  477.                 if ($levelEnum === null) {
  478.                     throw new InvalidArgumentException('Level "'.$level.'" is not defined, use one of: '.implode(', ', Level::NAMES + Level::VALUES));
  479.                 }
  481.                 return $levelEnum;
  482.             }
  484.             // Contains first char of all log levels and avoids using strtoupper() which may have
  485.             // strange results depending on locale (for example, "i" will become "İ" in Turkish locale)
  486.             $upper = strtr(substr($level, 0, 1), 'dinweca', 'DINWECA') . strtolower(substr($level, 1));
  487.             if (defined(Level::class.'::'.$upper)) {
  488.                 return constant(Level::class . '::' . $upper);
  489.             }
  491.             throw new InvalidArgumentException('Level "'.$level.'" is not defined, use one of: '.implode(', ', Level::NAMES + Level::VALUES));
  492.         }
  494.         $levelEnum = Level::tryFrom($level);
  495.         if ($levelEnum === null) {
  496.             throw new InvalidArgumentException('Level "'.var_export($level, true).'" is not defined, use one of: '.implode(', ', Level::NAMES + Level::VALUES));
  497.         }
  499.         return $levelEnum;
  500.     }
  502.     /**
  503.      * Checks whether the Logger has a handler that listens on the given level
  504.      *
  505.      * @phpstan-param value-of<Level::VALUES>|value-of<Level::NAMES>|Level|LogLevel::* $level
  506.      */
  507.     public function isHandling(int|string|Level $level): bool
  508.     {
  509.         $record = new LogRecord(
  510.             datetime: new DateTimeImmutable($this->microsecondTimestamps, $this->timezone),
  511.             channel: $this->name,
  512.             message: '',
  513.             level: self::toMonologLevel($level),
  514.         );
  516.         foreach ($this->handlers as $handler) {
  517.             if ($handler->isHandling($record)) {
  518.                 return true;
  519.             }
  520.         }
  522.         return false;
  523.     }
  525.     /**
  526.      * Set a custom exception handler that will be called if adding a new record fails
  527.      *
  528.      * The Closure will receive an exception object and the record that failed to be logged
  529.      */
  530.     public function setExceptionHandler(Closure|null $callback): self
  531.     {
  532.         $this->exceptionHandler = $callback;
  534.         return $this;
  535.     }
  537.     public function getExceptionHandler(): Closure|null
  538.     {
  539.         return $this->exceptionHandler;
  540.     }
  542.     /**
  543.      * Adds a log record at an arbitrary level.
  544.      *
  545.      * This method allows for compatibility with common interfaces.
  546.      *
  547.      * @param mixed             $level   The log level (a Monolog, PSR-3 or RFC 5424 level)
  548.      * @param string|Stringable $message The log message
  549.      * @param mixed[]           $context The log context
  550.      *
  551.      * @phpstan-param Level|LogLevel::* $level
  552.      */
  553.     public function log($level, string|\Stringable $message, array $context = []): void
  554.     {
  555.         if (!$level instanceof Level) {
  556.             if (!is_string($level) && !is_int($level)) {
  557.                 throw new \InvalidArgumentException('$level is expected to be a string, int or '.Level::class.' instance');
  558.             }
  560.             if (isset(self::RFC_5424_LEVELS[$level])) {
  561.                 $level = self::RFC_5424_LEVELS[$level];
  562.             }
  564.             $level = static::toMonologLevel($level);
  565.         }
  567.         $this->addRecord($level, (string) $message, $context);
  568.     }
  570.     /**
  571.      * Adds a log record at the DEBUG level.
  572.      *
  573.      * This method allows for compatibility with common interfaces.
  574.      *
  575.      * @param string|Stringable $message The log message
  576.      * @param mixed[]           $context The log context
  577.      */
  578.     public function debug(string|\Stringable $message, array $context = []): void
  579.     {
  580.         $this->addRecord(Level::Debug, (string) $message, $context);
  581.     }
  583.     /**
  584.      * Adds a log record at the INFO level.
  585.      *
  586.      * This method allows for compatibility with common interfaces.
  587.      *
  588.      * @param string|Stringable $message The log message
  589.      * @param mixed[]           $context The log context
  590.      */
  591.     public function info(string|\Stringable $message, array $context = []): void
  592.     {
  593.         $this->addRecord(Level::Info, (string) $message, $context);
  594.     }
  596.     /**
  597.      * Adds a log record at the NOTICE level.
  598.      *
  599.      * This method allows for compatibility with common interfaces.
  600.      *
  601.      * @param string|Stringable $message The log message
  602.      * @param mixed[]           $context The log context
  603.      */
  604.     public function notice(string|\Stringable $message, array $context = []): void
  605.     {
  606.         $this->addRecord(Level::Notice, (string) $message, $context);
  607.     }
  609.     /**
  610.      * Adds a log record at the WARNING level.
  611.      *
  612.      * This method allows for compatibility with common interfaces.
  613.      *
  614.      * @param string|Stringable $message The log message
  615.      * @param mixed[]           $context The log context
  616.      */
  617.     public function warning(string|\Stringable $message, array $context = []): void
  618.     {
  619.         $this->addRecord(Level::Warning, (string) $message, $context);
  620.     }
  622.     /**
  623.      * Adds a log record at the ERROR level.
  624.      *
  625.      * This method allows for compatibility with common interfaces.
  626.      *
  627.      * @param string|Stringable $message The log message
  628.      * @param mixed[]           $context The log context
  629.      */
  630.     public function error(string|\Stringable $message, array $context = []): void
  631.     {
  632.         $this->addRecord(Level::Error, (string) $message, $context);
  633.     }
  635.     /**
  636.      * Adds a log record at the CRITICAL level.
  637.      *
  638.      * This method allows for compatibility with common interfaces.
  639.      *
  640.      * @param string|Stringable $message The log message
  641.      * @param mixed[]           $context The log context
  642.      */
  643.     public function critical(string|\Stringable $message, array $context = []): void
  644.     {
  645.         $this->addRecord(Level::Critical, (string) $message, $context);
  646.     }
  648.     /**
  649.      * Adds a log record at the ALERT level.
  650.      *
  651.      * This method allows for compatibility with common interfaces.
  652.      *
  653.      * @param string|Stringable $message The log message
  654.      * @param mixed[]           $context The log context
  655.      */
  656.     public function alert(string|\Stringable $message, array $context = []): void
  657.     {
  658.         $this->addRecord(Level::Alert, (string) $message, $context);
  659.     }
  661.     /**
  662.      * Adds a log record at the EMERGENCY level.
  663.      *
  664.      * This method allows for compatibility with common interfaces.
  665.      *
  666.      * @param string|Stringable $message The log message
  667.      * @param mixed[]           $context The log context
  668.      */
  669.     public function emergency(string|\Stringable $message, array $context = []): void
  670.     {
  671.         $this->addRecord(Level::Emergency, (string) $message, $context);
  672.     }
  674.     /**
  675.      * Sets the timezone to be used for the timestamp of log records.
  676.      */
  677.     public function setTimezone(DateTimeZone $tz): self
  678.     {
  679.         $this->timezone = $tz;
  681.         return $this;
  682.     }
  684.     /**
  685.      * Returns the timezone to be used for the timestamp of log records.
  686.      */
  687.     public function getTimezone(): DateTimeZone
  688.     {
  689.         return $this->timezone;
  690.     }
  692.     /**
  693.      * Delegates exception management to the custom exception handler,
  694.      * or throws the exception if no custom handler is set.
  695.      */
  696.     protected function handleException(Throwable $e, LogRecord $record): void
  697.     {
  698.         if (null === $this->exceptionHandler) {
  699.             throw $e;
  700.         }
  702.         ($this->exceptionHandler)($e, $record);
  703.     }
  705.     /**
  706.      * @return array<string, mixed>
  707.      */
  708.     public function __serialize(): array
  709.     {
  710.         return [
  711.             'name' => $this->name,
  712.             'handlers' => $this->handlers,
  713.             'processors' => $this->processors,
  714.             'microsecondTimestamps' => $this->microsecondTimestamps,
  715.             'timezone' => $this->timezone,
  716.             'exceptionHandler' => $this->exceptionHandler,
  717.             'logDepth' => $this->logDepth,
  718.             'detectCycles' => $this->detectCycles,
  719.         ];
  720.     }
  722.     /**
  723.      * @param array<string, mixed> $data
  724.      */
  725.     public function __unserialize(array $data): void
  726.     {
  727.         foreach (['name', 'handlers', 'processors', 'microsecondTimestamps', 'timezone', 'exceptionHandler', 'logDepth', 'detectCycles'] as $property) {
  728.             if (isset($data[$property])) {
  729.                 $this->$property = $data[$property];
  730.             }
  731.         }
  733.         $this->fiberLogDepth = new \WeakMap();
  734.     }
  735. }