Monolog Tracy Bundle Laravel Package

Getting Started

• Install with composer require vendor/package:^2.0. The v2.0.0 release raises the floor to PHP 7.1+ and Symfony 4.0+, so confirm both before bumping — see the upgrade notes below.

• Look first at three files in the package: composer.json (the require block confirms the PHP/Symfony constraints and whether Laravel auto-discovery is wired via extra.laravel), the package's ServiceProvider, and any config/*.php file it ships for publishing.

• Publish the config and clear caches before first use:

  php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
  php artisan config:clear && php artisan cache:clear
  

• First use case: resolve the package's main class from the container (or its facade) inside a controller, then run the simplest possible call end-to-end — e.g. a single read/transform operation — to prove the provider boots and config is loaded. Don't wire it into business logic until that smoke test passes.

Implementation Patterns

• Upgrade gating: In composer.json, pin "php": "^7.1" and the Symfony constraints ("symfony/*": "^4.0") to match v2.0.0. If your app is on Laravel 5.5 or earlier, check that the framework itself doesn't pull Symfony 3 components — Composer will resolve a conflict rather than silently downgrade.
• Constructor injection over facades for anything testable. Bind the package's contract in a small app-level service provider and inject it; this makes swapping in a fake in tests trivial and keeps you off the facade's static surface.
• Config-driven setup: treat the published config file as the integration point. Override values per-environment (config/*.env-specific files or env vars) rather than editing the published file, so config:cache in production stays predictable.
• Queued work: if the package performs I/O (HTTP, filesystem, mail), wrap calls in jobs and let the queue handle retries. Resolve the package inside handle() rather than serializing it onto the job payload — many Symfony-backed services aren't safely serializable.
• Testing: use the package's fake/mock hooks where offered; otherwise bind a stub implementation in the container in setUp(). Add one integration test that boots the real provider so a future major bump fails loudly in CI.
• Multi-step workflows: keep the package at the edge of your domain. Adapt its return types into your own DTOs at the boundary so a v3 major doesn't ripple through controllers.

Gotchas and Tips

• The v1 → v2 jump is breaking, not incremental. Dropping PHP <7.1 and Symfony <4.0 means any environment or transitive dependency on Symfony 3 will fail composer update. Run composer why-not vendor/package 2.0.0 to surface exactly which package blocks the upgrade.
• PHP version drift in CI and prod: a 7.0 CI image will pass on v1 and fail on v2. Align Dockerfile, CI matrix, and platform.php in composer.json before tagging the upgrade.
• Symfony 4 removed/changed several components versus 2.x/3.x (e.g. bundle inheritance, Controller base class changes, Debug component moves). If you consume any Symfony class directly alongside this package, audit those call sites — the package bump can expose transitive breakage in your own code.
• Auto-discovery caching: after upgrading, php artisan package:discover and composer dump-autoload -o to refresh the manifest. Stale bootstrap/cache/packages.php is the usual cause of "class not found" after a version bump.
• config:cache masks config changes. If behavior doesn't match your edited config, clear the cache first — this bites hardest right after the upgrade when you're changing several settings at once.
• Extension points: register decorators or event listeners against the package's contract rather than subclassing its concrete classes. Subclassing ties you to internals that a Symfony major bump is likely to move.
• Debugging: enable the package's own logging channel or wrap calls in a DB::listen-style trace; with Symfony 4's stricter error handling, exceptions that were previously swallowed may now surface as hard failures — treat newly appearing exceptions as compatibility signals, not regressions.