Advanced Logger Laravel Package

Getting Started

This is a request-logging package with a hashing/masking layer, so the fastest path to a first result is: install, publish config, and log one route.

1. composer require the package, then publish its config (php artisan vendor:publish --tag=... — check the README for the exact tag).
2. Open the published config first. It is the single place that controls what gets logged (channels, levels, included/excluded paths) and what gets hashed.
3. Register the request-logging entry point. In 2.x this is the RequestLoggerService / RequestLoggerListenerHandler pair driven by RequestLogger — depending on the version's wiring you either enable a middleware or let the listener subscribe to Laravel's request events. The README's "Docker-based dev commands" section is the quickest way to get a working environment if you want to see it run before wiring it into your app.
4. First use case: hit a single endpoint that receives a payload containing an email/password/token, and confirm in storage/logs that the request is recorded but the sensitive field is replaced by a hash rather than logged in the clear.

If you only need one thing from this package, it is HashLogCustomizer: it is the extension point for saying "these keys are sensitive, hash them" so your existing log pipeline stays compliant without you rewriting log calls.

Implementation Patterns

Scope logging per environment, not per call site. Keep the request logger enabled in staging and production, disabled (or downgraded to a null/array channel) in local and test. Doing this in config avoids if (app()->environment()) noise scattered through the codebase.

Treat hashing as a policy, not a one-off. Centralize the sensitive-key list (password, token, authorization, secret, card fields) in config and reuse the same customizer across request logs, job logs, and exception context. A single source of truth is what makes the masking auditable.

Wire the listener to the framework, not to your controllers. The RequestLoggerListenerHandler exists so that logging happens on the request lifecycle rather than inside your handlers. Keep controllers free of logging calls; the value of this package is that instrumentation is orthogonal to business logic.

Compose around the final classes. As of 2.0.1, HashLogCustomizer, RequestLogger, RequestLoggerListenerHandler, and RequestLoggerService are final readonly class. The intended extension pattern is decoration: wrap the service in your own class that implements the same contract, add behaviour (sampling, redaction of extra fields, correlation IDs, tenant tags), and bind your decorator in a service provider. Do not plan on subclassing.

Add correlation early. Generate or accept a request ID in middleware and push it into the log context before the request logger runs. Retrofitting correlation after you have months of logs is painful; adding it on day one costs a middleware.

Route to a dedicated channel. Point request logs at their own channel (and often their own retention) instead of the default stack. Request logs are high-volume and have different retention/PII rules than application errors, and mixing them makes both harder to search and to purge.

Use the package as a debugging aid during rollout. Before enabling globally, log a single route in staging and diff the output against what you expect — that catches both over-logging (whole payloads) and under-hashing (a nested key the customizer missed).

Gotchas and Tips

• 2.0.1 makes four classes final readonly. This is technically a patch release, but if you extended any of them you will now get a fatal error. readonly also means no post-construction mutation, so any code that reflected into these objects or set properties will break. Migrate to composition/decorator bindings.
• readonly forces constructor injection. Configuration must be resolved and passed in at construction (from config, via the container), not lazily read later. If you were relying on config changes taking effect mid-request, that assumption is gone.
• The dist archive no longer ships tests, Docker files, or QA config. vendor/ will not contain the package's test suite. If you want to read the tests to understand intended behaviour, clone the repository instead of inspecting vendor/. Likewise, don't expect to run the package's own Docker-based commands from an installed copy.
• Hashing is one-way — plan for it. You cannot grep logs for a raw email or user ID once hashed. If you need to trace a specific user, log a stable non-sensitive identifier (user ID, request ID) alongside, rather than expecting to reverse the hash. If the hash is unsalted, it is also correlatable across records; if salted, it is not — know which you have.
• Nested payloads are the usual masking gap. Customizers commonly match top-level keys only. Verify with a deeply nested payload (data.user.password) and extend the key list or the customizer accordingly.
• Log volume and PII retention are the real risks. Request logging is cheap to turn on and expensive to clean up. Set retention (e.g. daily log rotation with a short keep) before enabling in production, and confirm that headers (Authorization, Cookie) are covered by the hashing policy, not just the body.
• Debugging a "nothing is logged" situation: check, in order, that the listener/middleware is actually registered for the current HTTP kernel, that the log channel's level allows the package's level, and that the request isn't excluded by path filters in config. The package's CI now prints test coverage, which is a useful signal when reading the repo for which paths are actually exercised.
• Upgrading from 2.0.x is drop-in aside from the final readonly change — there are no migrations, config renames, or deprecations in this release. Pin to ^2.0.1 and run your test suite to surface any accidental inheritance.