Onelog Bundle Laravel Package

Getting Started

• Treat this as a Symfony bundle, not a Laravel package. Start in the repo with composer.json, README.md, the bundle class, and DependencyInjection/ to find the config key and service IDs. Do not assume Laravel package discovery will register it.
• In a Symfony app, the minimal path is:

  composer require koderhut/onelog-bundle
  

  Register the bundle in config/bundles.php, add the documented config under config/packages/, then clear cache:

  php bin/console cache:clear
  

• New in 1.2.0: the logger now supports middleware for message and context pre-processing, so the logger can accept objects and extract data from them before handing the message to the base logger. If that is the behavior you need, look first at the middleware interface/base class and how middleware is registered (tag, config list, or service decoration) in DependencyInjection/. That is the release’s headline feature.
• In a Laravel app, first confirm whether the bundle exposes a framework-agnostic Monolog handler/service. If it is Symfony-only, evaluate it in a scratch Symfony app rather than forcing it into Laravel. The new middleware layer is another thing to check for framework coupling — it may only be wired through the bundle’s own logger service.
• First use case: consolidate multiple application log channels into one destination/file, then add a processor for request ID or environment context. In Laravel terms, this is closest to a custom Monolog channel or a stack channel with a shared handler.
• Second use case (1.2.0): log rich domain objects without hand-serializing them at every call site — register middleware that normalizes them once.
• Look first at the README usage example, the bundle extension/config tree, any middleware examples, and the tests. With a 2018-era release, the tests are often the most reliable documentation.

Implementation Patterns

• Symfony-native usage: enable the bundle, configure its channels/handlers, inject the provided logger service, and rely on the bundle’s service definitions. Use bin/console debug:container and debug:config to confirm what is actually registered.
• Middleware pattern (1.2.0): write small, single-purpose middleware that transforms the message or context before the base logger sees it:
  • Normalize DTOs/entities to arrays or scalars (avoid passing live objects downstream).
  • Redact secrets (tokens, passwords, PII) in context before it is written.
  • Enrich context with environment, request ID, tenant, or job name. Keep one concern per middleware and keep them order-independent where possible.
• Middleware ordering matters: pre-processing runs in registration order. Put redaction last among enrichment middleware so it catches anything earlier middleware added, but before any middleware that serializes the payload. Document the intended order next to the config.
• Laravel integration pattern: avoid bootstrapping the Symfony bundle. Instead, use the underlying handler class directly in config/logging.php:

  'channels' => [
      'onelog' => [
          'driver' => 'monolog',
          'handler' => \Vendor\OneLog\Handler::class,
          'handler_with' => [
              // constructor args from the bundle docs
          ],
          'formatter' => \Monolog\Formatter\LineFormatter::class,
          'formatter_with' => [
              'format' => "[%datetime%] %channel%.%level_name%: %message% %context%\n",
          ],
      ],
      'stack' => [
          'driver' => 'stack',
          'channels' => ['single', 'onelog'],
      ],
  ],
  

  Only use this if the handler is genuinely framework-agnostic and compatible with your Monolog version. Note: middleware from 1.2.0 likely will not apply on this path — if you bypass the bundle’s logger service, you lose the pipeline. In Laravel, model the same behavior with a Monolog processor or a custom handler instead.
• Day-to-day workflow: development uses stack to write to stderr and the one-log channel; production uses a single file or a rotating handler. Add Log::withContext(['request_id' => ...]) or a Monolog processor rather than manually prefixing every message.
• Channel-per-domain: keep domain-specific channels (payments, auth, jobs) but route them to the same destination via the package’s handler or Laravel’s stack channel. This preserves Log::channel('payments') ergonomics while producing one operational log.
• Service provider binding: if you use the package in Laravel, register any required handler/formatter as singletons and read options from config('logging.channels.onelog'). Keep constructor configuration out of application code.
• Testing pattern: use Log::spy() / Log::shouldReceive() in Laravel, or inject a test logger in Symfony. For middleware, unit-test each one in isolation (input message/context → expected output) rather than asserting on real log file contents.

Gotchas and Tips

• Framework mismatch is the main risk. A Symfony bundle will not be auto-discovered by Laravel. There is likely no extra.laravel provider entry, and adding it to config/app.php will not make Symfony DI work. The new middleware layer increases the surface that is Symfony-wired, not decreases it — do not assume the middleware pipeline is reachable from a bare Monolog handler.
• Objects in context are a footgun. 1.2.0 lets you pass objects in, but anything that reaches a formatter must still be serializable. If your middleware does not fully normalize an object, JsonFormatter/LineFormatter can throw, emit {}, or leak properties. Always return scalars/arrays from middleware.
• Middleware exceptions are logging-path exceptions. A bug in pre-processing can take down the logging call and, in the worst case, the request. Wrap risky extraction in try/catch and fall back to a safe, minimal context. Never let logging throw inside a job or queue worker.
• Ordering and idempotency. Pre-processing runs once per call; avoid middleware that mutates global state or assumes it runs alone. If you register the same middleware twice, expect duplicated context keys — decide whether later values overwrite or merge arrays explicitly.
• Old release and low adoption. Prior releases were 2018-era, with 1 star and 0 dependents. Expect Monolog 1/2-era constraints, possible PHP 7.x assumptions, and no Monolog 3 support. The 1.2.0 middleware feature may not have modernized the dependency floor — pin versions and run a dependency audit before adopting.
• Single-file logging has operational costs. Multiple PHP-FPM workers and queue workers writing to one file can interleave, complicate rotation, and create permission issues. Prefer RotatingFileHandler, logrotate, or an external shipper.
• Config cache quirks. In Symfony, run cache:clear after changing bundle config — including after adding middleware. In Laravel, run php artisan config:clear or config:cache after editing config/logging.php.
• Debugging registration. Use bin/console debug:container --tag=monolog.logger and debug:config in Symfony to confirm middleware and handler wiring; use php artisan about / config('logging') in Laravel. Check the actual namespace and class names in the repo; old bundles often differ from the package name.
• Extension points. Prefer a custom Monolog formatter, processor, handler decorator, or (now) preprocessing middleware over modifying vendor code. If the bundle exposes compiler passes or event subscribers, treat those as Symfony-specific and port the concept, not the code.
• Log hygiene. A single log mixes contexts from many channels. Add processors for request ID, user ID, and environment, and redact secrets before widening what gets written — middleware is a good place to enforce redaction centrally.
• Pragmatic verdict for Laravel: if you only need one consolidated log, Laravel’s built-in single or stack channel already does this. Adopt this package only if it provides a specific handler/formatter/middleware behavior you cannot reproduce in a short custom channel or processor.