Download the PHP package lezhnev74/psr-logging-masking-middleware without Composer

PSR-compatible Logging Masking Middleware

A logging middleware for any PSR-7 HTTP client that logs every request and response for later debugging, with secrets redacted - headers, query-string args and body keys masked per message. Built on PSR-7 (messages), PSR-17 (factories, auto-discovered) and PSR-3 (logging), so it works with any PSR-7 impl and PSR-3 logger - none a hard dependency.

Requirements

• PHP 8.1 - 8.5
• Any PSR-7 / PSR-17 implementation in your app (e.g. guzzlehttp/psr7 or nyholm/psr7), discovered via php-http/discovery.

Installation

Usage

The core is a MessageLogger: give it a PSR-3 logger and a Masker - the config-bound masking policy. It masks each message and writes the exchange as a single debug record. Bodies are masked by content-type - JSON by key (recursively), x-www-form-urlencoded by field name, any other type replaced with a <content-type: N bytes> note so an opaque body never leaks.

One config masks both messages - list every secret name wherever it may appear. MessageMasker's further constructor arguments pin a PSR-17 stream factory or customize the replacement string; pass a NullMasker to the logger to log exchanges unmasked. See tests/MessageLoggerTest.php.

Fluent builder

MessageLoggerBuilder::for($psr3Logger) wires the same MessageLogger in one chain - no hand-built MaskingConfig or MessageMasker:

Call withMaskingConfig() more than once to merge configs (deduped case-insensitively), and placeholder()/replaceWith() share one slot so the last one set wins. See tests/MessageLoggerBuilderTest.php.

Guzzle

HandlerMiddleware::for($logger) returns a generic fn(callable): callable middleware for any handler stack. Push it onto Guzzle's:

See tests/GuzzleClientTest.php and tests/HandlerMiddlewareTest.php.

More

Each is a green test - the executable, always-current spec:

• Per-message masking - subclass MessageLogger and override the single resolveMasker() seam to vary the masking by path, method, headers, etc.; it receives the message being masked and the exchange's request, so it can key on either (return a NullMasker = unmasked): tests/MessageLoggerTest.php.
• Custom replacement - pass a replacer: closure to MessageMasker; it receives a MaskTarget (message, kind, path, value) and returns the string to substitute (default '***'): tests/MessageMaskerTest.php.
• Laravel Http facade - pass the same handler stack via Http::withOptions(['handler' => $stack]) (or Http::globalOptions(...) in a provider): tests/LaravelHttpFacadeTest.php.
• Any PSR-18 client (no handler stack) - wrap it with the LoggingClient decorator: tests/LoggingClientTest.php.
• Standalone masking (no logging) - the Masker interface is the masking contract (mask(MessageInterface): MessageInterface, returns a masked clone) that MessageLogger itself consumes. MessageMasker is its canonical implementation, bound to one MaskingConfig; NullMasker is the no-op implementation. Build the masker with preserveUnknownBodies: true to keep a body whose media type has no built-in masker byte-for-byte instead of collapsing it to a size note - for consumers (e.g. traffic recorders) that must keep bodies faithful: tests/MaskerContractTest.php.

Local development

QA tooling runs in a PHP 8.5 Docker container (with Xdebug) via the dev wrapper - no host PHP needed. ./dev <script> is composer <script> in Docker; anything unrecognized is passed to composer.

Contributing

• TDD. Every new branch needs a covering test; the masking/serialization suite must stay green against both Guzzle and Nyholm PSR-7 impls.
• Conventional Commits (spec) drive semantic versioning (fix → patch, feat → minor, !/BREAKING CHANGE → major).
• Run ./dev check before opening a PR.

License

MIT - see LICENSE.