6.0.0-git
2021-12-04
Last Modified 2021-11-21 by Ralf Lang (B1 Systems GmbH)

Horde\Log

Description

Horde's Logging component.

The Horde Logging library was loosely based on the Zend 1 logging component back in H4. Recent upgrades implement PSR-3 logging and are informed by native PSR-3 implementations as well as Zend\Log's successor Laminas\Log

Horde\Log internally delegates different aspects of log handling to formatters, filters and handlers, but exposes a unified Logger facade.

Horde's Logger contains multiple building blocks:

  • The Logger is the facade implementing the PSR-3 LoggerInterface. This is the only surface consuming code needs to worry about
  • LogLevels have a criticality (integer) and a name (string). Multiple log levels of the same criticality might exist. The logger will only deal with messages for known log levels. You can either deliver custom log levels or fall back to a sane default.
  • The LoggerAware interface enables automatically configuring the logger into an application
  • Filters can control if a message is going to be processed. Filters can be applied globally or to individual handlers.
  • Handlers can deliver the message to filesystem or external resources like syslog, a logger software or similar. A Logger can have multiple handlers. Handler-level filters can deliver only certain messages to certain files or backends while others are delivered to some default facility.
  • Formatters can control how a message is supposed to look like. While you can stack multiple formatters, if might not make sense for all combinations. A formatter may combine message text with message context into an XML or JSON format or it may fill placeholders with data from context. It may also truncate messages, obfuscate passwords or add line breaks etc.
  • The LogMessage class is the common interchange format the Logger presents to Filters, Formatters and Handlers. It combines LogLevel, text and context.

Usage

Bugs

List any tickets on http://bugs.horde.org/ that cover this issue or are relevant to it.

People

Ralf Lang for the H6 upgrade

Resources

Include links to protocol descriptions, specifications, RFCs, external applications, presentations on http://horde.org/papers/ or elsewhere that are relevant, articles, API docs from http://dev.horde.org/ - anything that might be useful to someone working on this.

UPGRADING

3.x (H6)

Type hinting

  • Users should Type hint against either Horde\Log\LoggerInterface or Psr\Log\LoggerInterface
    • Use Psr if you only want to emit logs
      • Use Horde if you want to call into horde specific extensions

While both technically work, more specific typing improves static analysis and IDE hints.

Awareness

  • Use Psr/Log/LoggerAwareInterface for classes consuming loggers via setter injection
  • If you use setter injection and depend on horde-specific functionality, rather use the Horde\Log\LoggerAwareInterface. As both conflict and have different use cases, choose wisely.

Constraint Filter

  • The constraint filter is likely to go into a separate package soon.

Back to the Project List