Download the PHP package qubus/log without Composer

Qubus Logger

PSR-3 logging for PHP 8.4+, with Flysystem, locked local streams, PDO, and Symfony-backed Qubus Mail. See UPGRADE.md before moving from v4 to v5.

Local files and standard output

StreamLogger appends without reading the existing file. Local file writes use an exclusive advisory lock, including flushing the record. Parent directories must already exist. File permissions follow your process umask; place logs outside the public web directory.

php://stdout and php://stderr use no lock. Writable stream resources are also accepted; locking defaults to whether the stream supports it. Use ['useLock' => false] for streams that cannot be locked. Seekable resources are moved to the end before writing. Caller-owned resources remain open when the logger closes or is destroyed. close() releases owned handles; the next record reopens the path, which allows integration with external rotation tools.

Flysystem

FileLogger accepts any League\Flysystem\FilesystemOperator, including Qubus filesystem implementations when installed separately. Install the adapter for your storage provider; the example below uses league/flysystem-local.

Flysystem provides no atomic append operation. This backend reads and rewrites the whole log file, so it is suitable for small logs with a single writer. Concurrent writers can lose records. Use StreamLogger for concurrent local logging, or a centralized logging service for remote ingestion. There is no automatic retention or rotation in either backend.

filenameFormat, filenameExtension, logFormat, and logFilename can be supplied in constructor options or through their setters. Default filenames prohibit path separators/control characters and require an alphanumeric extension. Custom Filename implementations may provide storage-relative subdirectories.

Email

MailerLogger uses qubus/mail:^6, which composes Symfony messages. Supply a configured Qubus\Mail\Mailer. Its selected default/named transport or DSN is preserved, so SMTP, provider bridges, and failover configurations work without logger-specific transport settings.

Sender and at least one recipient are required when a record is sent. Recipients accept a single address, a list of addresses, or address => display name pairs. Each qualifying record sends one plain-text message. Text resembling HTML is never automatically rendered as HTML. Mail header fields reject control characters.

PhpMailLogger takes the same constructor arguments and selects Symfony's native transport via withMail(). Raw mail() headers and shell parameters are no longer supported. PHPMailerLogger remains as a deprecated compatibility name for MailerLogger.

Transport exceptions propagate to the caller, and a false send result raises RuntimeException. The logger never recursively emails its own delivery failures. Configure retry/failover on your transport or handle the exception using a separate logger. See Symfony's transport documentation.

Database

Create the table before logging. This schema works with SQLite, MySQL, and PostgreSQL:

The PDO driver for your database must be installed. Table names must match [A-Za-z_][A-Za-z0-9_]*; schema-qualified names and SQL fragments are rejected. Values use bound parameters. Empty context is stored as []. PDO exceptions propagate, and silent prepare/execute failures raise RuntimeException. The logger uses the supplied connection and its transaction without committing it.

Filtering and fan-out

Every backend honors enabled and a minimum severity threshold. File, stream, and database loggers default to debug; mail loggers default to error. Use PSR-3 level strings such as LogLevel::WARNING ('warning'). Unknown levels throw Psr\Log\InvalidArgumentException, including when logging is disabled.

Logger accepts any iterable of PSR-3 loggers and snapshots it at construction, including generators. It delivers in order and stops on the first exception. It does not buffer, retry, or suppress backend failures.

Formatting and context

LogFormat produces one text line with date, level, interpolated message, and JSON context. JsonFormat produces one JSON object with date, level, message, and context. Backends append the newline, so custom Format implementations should return a record without a trailing newline. Custom formatters are responsible for their own escaping and redaction.

Both default formatters normalize context once, interpolate only message placeholders, and redact common credential keys recursively. Key matching ignores case, hyphens, and underscores. Context::SENSITIVE_KEYS lists defaults. Extend or replace them explicitly:

Passing sensitiveKeys: [] disables key redaction. Redaction does not detect secrets embedded in free-form message text, exception messages, or arbitrary string values. Avoid putting credentials in those fields. The database backend uses the default redaction list.

Context normalization limits nesting to eight levels and traversal to 1,000 values; it does not impose a byte limit on individual strings. Recursive/oversized structures receive [truncated] markers. Resources, non-finite numbers, and invalid UTF-8 remain serializable. Throwing string conversions produce a marker; arbitrary JsonSerializable, property/debug hooks, and lazy-object initializers are not invoked. Exceptions retain class, message, code, file, line, previous exception, and up to 50 stack frames, subject to those limits. Trace arguments are omitted. Text output escapes line breaks and terminal control characters.

LogFormat accepts a dateFormat and timezone; JsonFormat uses an RFC 3339 timestamp. The default timezone is PHP's configured timezone. The database backend's dateFormat option controls its date column.