Http Log Bundle Laravel Package

Getting Started

1. Install and register

   • composer require nowo-tech/http-log-bundle
   • Symfony Flex usually registers it automatically. If not, add the bundle class named in the README to config/bundles.php.
   • Confirm your app meets the bundle’s stated compatibility: PHP >= 8.2 and Symfony 7/8.

2. Read these first, in order

   • The README’s configuration reference — this is where body policies, redaction, storage, and admin UI routing are defined.
   • The routes shipped by the bundle, so you know the admin UI path before enabling it.
   • CHANGELOG.md and UPGRADING.md — important for a small bundle where config keys may move between releases.

3. Start in dev only

   • Enable the bundle in config/packages/dev/ first, with body capture enabled and the admin UI behind your existing firewall.
   • Do not enable body capture globally in production until you have verified redaction and retention behavior.

4. First useful use case: inspect one request end-to-end

   • Hit a known endpoint that sends an Authorization header and a JSON body containing a password/token field.
   • Open the admin UI, locate the record, and verify:
     • the request/response bodies are captured as expected;
     • sensitive headers and fields are redacted;
     • the record is searchable/exportable.
   • Then exercise export and purge on a throwaway record before trusting them in production.

Implementation Patterns

• Tier capture by environment. A common split:
  • dev: full bodies, short retention, admin UI open to local developers.
  • staging: bodies with redaction, medium retention.
  • prod: metadata and error responses only, or sampled bodies with strict size/content-type limits.
• Compose body policies rather than one global switch. Use the bundle’s policy options to combine:
  • content-type allowlists (e.g., JSON and form posts, not multipart/form-data);
  • maximum body size / truncation;
  • sampling or “only capture on 4xx/5xx”;
  • path exclusions for health checks, static assets, and large file transfers.
• Treat redaction as layered configuration. Configure header redaction (Authorization, Cookie, X-Api-Key), query-string redaction, and body-key redaction for JSON/form payloads. Validate with a canary request containing a fake token, then search the stored record to confirm it never appears.
• Use the admin UI as an incident tool, not a debugging log. Filter by time/route/status, export the relevant window for an incident review, and purge immediately after. Keep Monolog for application-level logging; use this bundle for the HTTP audit trail.
• Schedule purge. The UI purge is useful manually, but production retention should be automated (cron/console command documented by the bundle, or a scheduled call to the purge mechanism). Align retention with your GDPR/data-retention policy.
• Correlate with application logs. If the bundle stores or exposes a request identifier, include it in your Monolog context or response headers. That lets you jump from an app exception to the captured HTTP exchange.
• Exclude noisy or unsafe routes. Webhooks with large payloads, file upload/download endpoints, and streaming responses are poor candidates for body capture. Exclude them at the path level and keep metadata logging if needed.
• Plan storage growth. HTTP logs grow quickly. Decide early whether the bundle’s table lives in your primary database or a separate one, and add indexes/partitioning or aggressive retention before production traffic.

Gotchas and Tips

• Streamed and binary responses may not be fully capturable. StreamedResponse, BinaryFileResponse, and large downloads often bypass body capture or produce empty/truncated records. Verify behavior for each response type you rely on.
• Body buffering has a memory cost. Always set a maximum body size and a content-type allowlist. Logging uploads is the fastest way to exhaust memory or bloat the database.
• Redaction is pattern-based, not semantic. Nested JSON, case variations (Password vs password), and multipart bodies can slip through. Test with realistic payloads, including nested arrays, and prefer deny-by-default for sensitive routes.
• Admin UI security is your responsibility. Put it behind a firewall, require a role, and consider IP restriction. The purge action is destructive; restrict it more tightly than read/export.
• Config changes require a cache clear. As with any Symfony bundle, run bin/console cache:clear after changing configuration, and keep environment-specific config in the correct config/packages/{env}/ directory.
• Disable or isolate in tests. Capturing HTTP traffic in functional tests slows suites and pollutes the database. Disable the bundle in test, or point it at a disposable storage connection.
• Watch listener priority. If request/response data is missing, check whether another kernel listener or middleware terminates or replaces the response before this bundle sees it.
• Low adoption means you are the support channel. With 2 stars and 0 dependents, pin the version in composer.json, read the source for anything the README does not cover, and avoid relying on community answers. The MIT license at least allows forking/patching.
• Use the extension points deliberately. If the built-in body policies or redactors do not fit, implement the bundle’s documented interfaces (custom policy/redactor/storage) rather than forking the bundle. Keep custom implementations small and covered by a focused test.
• Read UPGRADING.md before every minor bump. For a young bundle, config keys and admin routes are the most likely things to shift.