Log Bundle Laravel Package

Getting Started

Before writing a line of code, confirm what you're actually installing — this is a Symfony bundle, not a Laravel package, and with 0 stars / 0 dependents there is no community documentation to fall back on. Plan to spend the first 15 minutes reading source.

1. Inspect the manifest first.

   composer show yipikai/log-bundle --all
   # or, from the repo root
   cat composer.json
   

   Look for "type": "symfony-bundle", a symfony/framework-bundle constraint (this tells you the supported Symfony versions, and by extension the PHP version), and any extra.symfony.flex recipe. If there's no type: symfony-bundle, the "bundle" name is aspirational and you should treat it as a plain library.

2. Map the bundle structure. In a standard bundle you'll find:

   • src/DependencyInjection/*Extension.php — reads config/packages/*.yaml and registers services
   • src/DependencyInjection/Configuration.php — the canonical list of config keys (this is your real documentation)
   • src/Resources/config/services.xml|yaml — the service IDs and aliases you'll inject
   • src/LogBundle.php — bundle class and compiler passes

   The Configuration.php tree is the single most valuable file in the repo. Read it before reading anything else.

3. Register it (Symfony app only):

   // config/bundles.php
   Yipikai\LogBundle\LogBundle::class => ['all' => true],
   

4. Confirm what got wired:

   bin/console debug:container --tag=monolog.logger
   bin/console debug:container | grep -i yipikai
   

   The output tells you the service alias/ID to type-hint against. If the bundle exposes no public alias, you'll be injecting Psr\Log\LoggerInterface (or a Monolog channel) rather than the bundle's own class — which is what you want anyway.

5. First real use case: replace a hand-rolled error_log() / file_put_contents() call in one service with the injected logger, then verify the output lands in var/log/ with the expected channel and level. Do this before touching config — it validates that the bundle boots and that your handler chain isn't swallowing records.

If you're in a Laravel codebase: don't composer require this expecting framework integration. Laravel has no bundle autodiscovery, no config/bundles.php, and no debug:container. You have three realistic options, in order of preference:

• Skip it. Laravel's Monolog stack (config/logging.php, custom channels, tap array) already covers what a single-purpose Symfony log bundle does.
• Bridge it. Install it as a plain dependency, instantiate the underlying client/handler in a service provider, and register it as a Monolog tap or a custom channel handler.
• Port the pattern. If the value is in how it formats/enriches records, copy the formatter into a Monolog\Formatter or a Processor and wire it via a channel tap. Twenty lines, zero coupling.

Implementation Patterns

Inject the interface, not the bundle class. Type-hint Psr\Log\LoggerInterface (or Monolog\Logger) and let the bundle's alias satisfy it. If you type-hint a concrete Yipikai\...\Logger, every call site becomes hostage to a 0-star dependency's next breaking change.

final class ThingDoer
{
    public function __construct(private LoggerInterface $logger) {}

    public function do(Thing $thing): void
    {
        $this->logger->info('thing.done', ['id' => $thing->id()]);
    }
}

Configure per environment, not per call site. Symfony's config/packages/yipikai_log.yaml with config/packages/dev/yipikai_log.yaml and config/packages/prod/… overrides is the idiomatic path. Keep the config file in VCS and drive the interesting values from env vars:

# config/packages/yipikai_log.yaml
yipikai_log:
    enabled: '%env(bool:LOG_BUNDLE_ENABLED)%'
    # remaining keys: copy verbatim from Configuration.php

Decide early: wrapper or handler? Two shapes show up in small log bundles:

• Standalone logger service — the bundle owns its own transport. Best used as a second, separate logger for a specific concern (audit trail, business events), injected explicitly alongside the default logger.
• Monolog handler/processor — the bundle plugs into the existing stack. Prefer this. It means one logging pipeline, one set of formatters, and dev/prod behave consistently.

If services.xml registers something tagged monolog.logger or kernel.event_subscriber, it's the second shape and you should configure it, not call it.

Bridge into Laravel via a channel tap. If you must reuse the package's formatting logic from Laravel:

// config/logging.php
'channels' => [
    'yipikai' => [
        'driver'  => 'monolog',
        'handler' => StreamHandler::class,
        'with'    => ['stream' => storage_path('logs/yipikai.log')],
        'tap'     => [App\Logging\YipikaiContextTap::class],
    ],
],

The tap resolves the package class out of the container and mutates the Monolog logger. This keeps Laravel's channel/level semantics intact — you get LOG_LEVEL, daily rotation, and Log::channel('yipikai') for free.

Use it for structured context, not string interpolation. The whole point of a dedicated log service is machine-readable fields. $logger->info('order.paid', ['order' => $id, 'cents' => $amount]) — never "Order $id paid $amount". This matters doubly for a package you can't easily patch: if the record shape is wrong, you can only fix it at the call sites.

Keep it out of the domain core. Wrap logging behind a tiny application-level port (AuditLogger, EventLogger) that adapts to whichever concrete logger you're using. Then swapping this bundle out — likely, given the adoption numbers — is a one-line change in a service definition instead of a repo-wide find-and-replace.

Gotchas and Tips

• Zero adoption is the headline risk. 0 stars, 0 dependents, no issue history means no one has hit the edge cases for you. Budget for reading src/ end-to-end and pin the version exactly ("yipikai/log-bundle": "1.2.3") rather than using a caret constraint. You are the maintainer now.
• The release date deserves scrutiny. A 2026-01-14 release on a repo with no traction can mean either active maintenance or an automated tag from a private monorepo. Check the tag history and commit log; if the versions are all same-day splits, treat stability claims skeptically.
• Verify the Symfony/PHP constraint against your platform. Small bundles often pin an outdated symfony/framework-bundle range. composer why-not yipikai/log-bundle and composer update --dry-run will surface this in seconds; discovering it after a composer update on a large app is much worse.
• Bundle alias ≠ package name. The YAML root key is set by Configuration::getRootNode()->setPath() in the extension — it's frequently yipikai_log, sometimes log, occasionally something surprising. bin/console config:dump-reference <alias> confirms it; guessing produces silent no-ops, because Symfony ignores config under an unknown root only if the extension isn't loaded at all.
• Silent failure is the default failure mode for logging. Nothing throws when a handler misroutes. Test with bin/console debug:container --env=prod (not just dev — services are often only registered conditionally), and assert on real output, not on "no exception was thrown."
• Watch for context loss across async boundaries. If the bundle captures request state (user, tenant, correlation ID) via a RequestStack-based processor, that context vanishes in console commands, queue workers, and Messenger handlers unless you re-seed it. Wrap your worker loop and re-push the context at the top of each job.
• Log level mapping is a classic off-by-one. A bundle's own levels: config often maps to Monolog levels with different names (warning vs warn, critical vs fatal). Check the extension's translation table rather than assuming.
• Extension points, ranked: (1) decorate the service — Yipikai\LogBundle\…: ~ with decorates: in services.yaml is the cleanest override and survives package upgrades; (2) a compiler pass to change tags; (3) a monolog.processor tag on your own class if it's Monolog-shaped underneath; (4) fork it. Prefer 1 or 3.
• Debugging checklist when records disappear: debug:container <service-id> --show-private to confirm instantiation, monolog.logger tag dump to confirm channel registration, then temporarily set the channel to debug with a test handler (type: test, level: debug) and assert in a functional test. The test handler is the single best tool for making logging behavior assertable instead of eyeballed.
• Do not let the bundle own your audit/compliance logs without a fallback. If it's the only writer for records you're contractually required to keep, add an independent sink. A 0-star dependency is not a system of record.