Symfony Commons Bundle Laravel Package

Getting Started

1. Install (Symfony only): composer require spiechu/symfony-commons-bundle. This is a Symfony bundle, not a Laravel package — it does not ship a ServiceProvider, does not support package auto-discovery, and will not boot in a Laravel app. If your stack is Laravel-first, treat this as a reference implementation to copy patterns from rather than a dependency to require.
2. Where to look first: src/ for the value objects (the 0.3 release hardened them with assert()), then DependencyInjection/ for the Extension and Configuration classes — that is the only surface you would actually interact with day-to-day. After that, the functional tests (added in 0.3) are the best documentation of intended wiring.
3. Register the bundle (Symfony context): add it to config/bundles.php, then run bin/console debug:container --tag=data_collector to confirm the collector was registered before assuming anything is broken. Most "bundle does nothing" reports are just missing registration or a disabled profiler.
4. First useful use case for a Laravel developer: lift the value-object + assert() idiom into app/ValueObjects or a shared packages/ directory. That is the highest-value, lowest-risk thing here — the 0.3 release explicitly hardened it, and it has zero Symfony coupling.

Implementation Patterns

• Value objects with invariant guards: 0.3 adds assert() usage inside value objects. The useful pattern is assert($this->id !== '')-style guards at construction. In Laravel, mirror this but wrap the checks in InvalidArgumentException (or a domain Exception) so they always fire regardless of zend.assertions. Reserve raw assert() for genuinely internal sanity checks.
• Separate collection from presentation: the "data collector works without Twig" fix is the headline change of 0.3 and a pattern worth copying for Laravel Telescope. The collector should return arrays/DTOs; the template (Twig, or Blade in Telescope) only decides how to render. If you are building a debugging surface, keep the render layer optional and the data layer framework-free.
• Framework-agnostic shared domain code: if you maintain both a Symfony app and a Laravel app, put value objects in a package with no Symfony or Illuminate imports, and let each framework adapter provide its own wiring. 0.3's Twig decoupling is a small step in this direction; use it as the template for your own shared libraries.
• Override behaviour via compiler passes: when you need to customise a service the bundle registers, do not edit vendor code. Add a src/DependencyInjection/Compiler/ pass in your app that re-tags or decorates the service. This is the supported extension point and keeps upgrades clean.
• CI shape to mirror: the 0.3 changes — PHPStan level 4 plus functional tests — are a sensible gate for your own utility packages. Static analysis on the public API and functional tests around container wiring catch more real bugs than unit-testing every leaf class.
• Profiler wiring: if you do use it under Symfony, register the collector in config/packages/dev/ only and confirm the panel appears. Do not wire it in prod — it is debug tooling and adds nothing there.

Gotchas and Tips

• Pre-1.0, and the last release was January 2018. Every 0.x bump can break you. Pin the exact version (0.3.* or the exact tag) rather than ^0.3, and budget for a review on each upgrade.
• No Laravel service provider, no auto-discovery. composer require in a Laravel app installs classes that never boot. Do not add it to config/app.php providers — it will fail. If you only want individual classes, verify they have no Symfony runtime dependencies before pulling them in.
• Twig is optional for the collector only. 0.3 fixes the no-Twig case for the data collector; it does not make the rest of the bundle Twig-free. If your Symfony app has no Twig and a profiler panel renders blank, confirm you are on 0.3 or later — anything ≤0.2.1 assumes Twig.
• assert() is disabled in production by default (zend.assertions=-1). If the value objects rely solely on assert() for validation, invalid state can slip through in prod without error. Before reusing any guard, decide whether it is a hard invariant (use exceptions) or a dev-only sanity check.
• PHPStan level 4 is not strict. It mostly catches dead code and return-type mismatches. Do not read the 0.3 bump as a type-safety guarantee; the public API likely still accepts mixed in places. Read the actual signatures before relying on them.
• Debugging the collector: start with the functional tests added in 0.3 — they encode the expected container wiring. Diff your config/bundles.php and config/packages/ against them before suspecting the bundle.
• Upgrade from 0.2.1 → 0.3 is small: the only user-visible change is the Twig-less collector; the rest (Scrutinizer, PHPStan level, functional tests, assert()) is internal quality work. If you had a Twig stub workaround, remove it — it is now redundant and may mask the real setup.
• Maintenance reality: five stars and a 2018 release means you are effectively vendoring. If you depend on it, be prepared to fork the value objects you actually use and own them, rather than waiting on upstream.