Logger Laravel Package

Getting Started

Install and confirm the version

composer require vendor/package:^1.1

v1.1.0 is the first release with official Lumen support, so anything below 1.1.0 on a Lumen app is unsupported — verify with composer show vendor/package before debugging odd bootstrapping errors.

Where to look first (in this order)

1. config/<package>.php after publishing — this is almost always the real API surface, more than the README.
2. The package's service provider — it tells you which bindings are singletons, which are factories, and which contracts you can swap.
3. Any Contracts/ or Concerns/ directory — those interfaces are your extension points.
4. CHANGELOG.md / upgrade notes — v1.1.0 is labelled "code cleanup", which sometimes hides renamed protected methods or tightened type hints.

Laravel: the minimal path

php artisan vendor:publish --tag=package-config

Auto-discovery registers the provider, so most installs need no manual wiring. Add the env keys the config file references, then exercise the package through one narrow entry point (a single controller action or Artisan command) rather than sprinkling calls across the app.

Lumen: the minimal path

Lumen has no package discovery and no vendor:publish, so v1.1.0 support means you do this by hand:

// bootstrap/app.php
$app->configure('package');                 // must come before config() is used
$app->register(Vendor\Package\PackageServiceProvider::class);

// only if you intend to use the facade
$app->withFacades();

Copy the package's config/package.php into your app's config/ directory manually and commit it — Lumen will silently return null for config keys that were never loaded via configure().

First real use case

Pick the smallest end-to-end slice: one call, one config value changed, one assertion that the output differs. That validates provider registration, config loading, and credentials in a single pass before you build on it.

Implementation Patterns

Inject the contract, not the facade. Resolve the package's interface through the container so tests can bind a fake:

public function __construct(private PackageClient $client) {}

Facades are fine in controllers and Blade, but they make the dependency invisible in jobs and service classes.

Wrap it in a thin adapter. Even a 30-line App\Services\PackageGateway that delegates to the package pays for itself the first time you need to swap drivers, add retries, or tag requests with a correlation ID. Keep the package's types out of your domain layer.

Drive behaviour from config, not code. Most packages of this shape expose timeouts, drivers, and endpoints in config. Prefer config('package.driver') plus an env var per environment over conditional logic in your classes — it also keeps config:cache working.

Push slow work onto the queue. If the package performs I/O, call it from a job with explicit $tries, $backoff, and $timeout. Make the job idempotent (dedupe keys, ShouldBeUnique) because retries will re-run it.

Decouple with events. Publish your own domain event after the package call succeeds, and let listeners handle notifications/audit logging. That keeps the package call site a single line and makes it easy to test.

Testing patterns

$this->mock(PackageClient::class, fn ($m) => $m->shouldReceive('send')->once());
Queue::fake();
Http::fake(['api.example.com/*' => Http::response(['ok' => true])]);

Use RefreshDatabase if the package ships migrations, and assert against the published config rather than hardcoded values so your tests survive a config change.

Lumen-specific patterns

• Register the provider in bootstrap/app.php; there is no discovery fallback.
• Call $app->configure('package') before the provider registers, or config reads come back empty.
• Facades require $app->withFacades(); aliases require $app->withEloquent() only if models are involved.
• Lumen's config caching and package bootstrapping are narrower than Laravel's — run the same smoke test in both if you ship to both.

Version hygiene during the upgrade

Pin ^1.1 (not ^1.0) and run your suite against the new minor before deploying. "Code cleanup" releases are the most common source of quiet breakage: renamed protected methods, removed @internal helpers, or stricter constructor signatures that only bite subclasses and mocks.

Gotchas and Tips

Config caching and env(). Never call env() outside config/ files. After php artisan config:cache, env() returns null and the package appears broken when it's actually just misconfigured.

Lumen has no vendor:publish. Copy config by hand and re-copy on upgrade — if v1.1.0 added or renamed config keys, your stale copy will silently keep defaults. Diff the package's config/package.php against yours after every minor.

Lumen config must be registered. Forgetting $app->configure('package') yields the classic "everything is null" symptom. If a value looks ignored, check this before anything else.

Provider registration order matters. If you bind your own implementation of the package's contract, do it before the package provider registers, or use $app->extend() to decorate the existing binding instead of overwriting it.

Singletons in long-running processes. Queue workers and Octane keep resolved instances alive across requests. If the package holds state (connections, caches, auth context), reset it in a job middleware or a Octane::tick/terminate hook rather than assuming a fresh container.

Facade vs. container mismatch. Mixing Package::method() and app(PackageClient::class) can hit two different instances if the binding is a factory, not a singleton. Pick one and stay consistent.

Debugging checklist when a call silently no-ops:

php artisan tinker
>>> config('package')            # is config actually loaded?
>>> app(PackageClient::class)    # which class is bound?
>>> get_class(app(PackageClient::class))

Log::debug('package', ['config' => config('package'), 'bound' => get_class(app(PackageClient::class))]);

"Code cleanup" ≠ "no behaviour change." grep your codebase for the package namespace before upgrading — anywhere you extend a package class, override a method, or mock a concrete class is a candidate for breakage. Prefer mocking interfaces.

Extension points to prefer. Contracts, config-driven drivers, published migrations, and package events age well. Subclassing concrete classes and reaching into protected properties do not — cleanup releases routinely change those.

Report Lumen issues with the version in the title. Now that Lumen is officially supported in v1.1.0, maintainers will triage Lumen bugs differently from "unsupported environment" reports — include lumen/framework version, PHP version, and whether the provider is registered manually.