Dev Bundle Laravel Package

Getting Started

Confirm the stack before anything else. steevanb/dev-bundle is a Symfony bundle, not a Laravel package — it hooks into the kernel, the DI container, symfony/translation, and Doctrine. If the target app is Laravel, close the tab: there is nothing to install, only a pattern to borrow (see the Laravel equivalents below). Everything that follows assumes a Symfony app with Doctrine ORM.

Install and gate it to dev/test.

composer require --dev steevanb/dev-bundle:'^x.y'   # pin explicitly, never float

// config/bundles.php
return [
    // ...
    Steevanb\DevBundle\SteevanbDevBundle::class => ['dev' => true, 'test' => true],
];

Copy the FQCN verbatim from the README rather than guessing it; the autoloader will not help you diagnose a typo'd namespace beyond a generic class-not-found.

Where to look first, in order:

1. vendor/steevanb/dev-bundle/README.md and CHANGELOG.md — the support matrix (PHP / Symfony major / doctrine/orm) lives here, and it is the single thing most likely to bite you.
2. src/ for the bundle class, any compiler passes, and the Command/ directory — that tells you what runs at kernel boot versus on demand.
3. bin/console list filtered by the vendor prefix — the bundle ships debug commands, but do not assume names; enumerate them.
4. The Profiler toolbar in dev — new panels for services, routes, and Twig templates appear after a cache clear.

First use case, end to end (about 30 minutes):

1. In dev, open any page and click into the bundle's Profiler panels to confirm registration worked.
2. Deliberately introduce an untranslated key in a template ({{ 'foo.bar.baz'|trans }}) and reload. If the bundle is doing its job, you get a loud failure instead of the raw key rendering. If you get the raw key, the translation guard is not wired — check that symfony/translation is installed and the locale you're testing is not silently falling back.
3. Break an entity mapping (add a non-nullable property with no default and no migration) and run the Doctrine schema check. Confirm it fails.
4. Revert both, then run your existing test suite. This is the real first use case — the exceptions you get on that first green-to-red run are the deliverable.

Before you commit, prove it cannot reach production:

APP_ENV=prod bin/console cache:clear
APP_ENV=prod bin/console debug:container | grep -i steevanb   # expect nothing

Wire that grep (or an equivalent container assertion) into CI. It is the most important line of setup in this whole assessment.

Implementation Patterns

Environment gating, three layers. require-dev in composer, ['dev' => true, 'test' => true] in config/bundles.php, and a CI assertion that the production container does not contain the bundle. Any one of these alone is insufficient: require-dev doesn't stop a stray composer install --no-dev misconfiguration from being mirrored, and bundles.php gating doesn't stop someone adding 'all' => true during a debugging session.

Fail-fast in the test suite, triage as backlog. Enable in test, run the suite, and treat the exception list as a work item rather than an obstacle. Split it into two streams — untranslated keys and schema drift — and hand them to the i18n and data-model owners respectively. Do not "temporarily" disable the bundle to get CI green; that is how the check dies.

Profiler-driven debugging loop. The panels replace the usual guesswork:

• Services — answer "what class is actually behind this service ID, and what are its arguments?" without reading three YAML files.
• Routes — "which route matched, and why did _controller resolve to that?" beats debug:router when you also need to see the current request's match.
• Twig — "which template actually rendered this block?" beats grepping for a class name that appears in four partials.

The workflow: reproduce in dev, open the panel, and only then drop into code. It is faster than the dump()/dd() cycle for anything involving wiring.

Console-first for repeatable checks. The Profiler needs a browser request; the debug commands do not. Use the console commands for anything you want to run in a script, a pre-commit hook, or a CI job — container inspection in particular is much cheaper than booting a web request.

Schema validation on demand, not at boot. The Doctrine half is best invoked as an explicit step (a composer script, a Make target, or a CI stage) rather than implicitly, so you control how often it runs. If it turns out to fire at kernel boot, keep it out of the test environment for large suites and run it as a separate CI job — otherwise you pay the validation cost on every test invocation.

Twig helpers: dev templates only. The extensions are for development output. Never let them into a template that renders in production, and never leave a debugging helper in a layout that is shared with prod templates — the rendering cost is small but the "why is this dumping into a customer's page" ticket is not.

Laravel equivalents (borrow the idea, not the package). If you are on Laravel — which, as a Laravel developer, is the expected case — reimplement rather than shim:

• Translation guard: decorate Illuminate\Contracts\Translation\Translator and bind it in AppServiceProvider only when app()->environment(['local', 'testing']). Throw when the resolved string equals the key that was passed in.
• Schema guard: Laravel has no Doctrine-style schema validation pass. Substitute a CI step: run php artisan schema:dump and diff against a committed baseline, failing the build on drift.
• Container/service inspection: php artisan about, tinker, and the Debugbar/Telescope panels cover most of the same ground natively. The bundle's services panel has no direct gap to fill.

Both Laravel items are 1–2 days of work total and produce zero ongoing dependency.

Pilot, measure, then commit. Run the bundle on one Symfony service with an active localization roadmap for a sprint. Record the false-positive rate on the translation guard before rolling it out broadly — if developers are routinely fighting keys that are legitimately dynamic, tune first and expand second.

Gotchas and Tips

Production leakage is the top-severity failure. The bundle's whole value is turning a cosmetic defect into an exception. In production that inversion is catastrophic: a missing translation becomes a 500 for a real user. Enforce with the composer/kernel/CI triple gate above, and re-verify after any config/bundles.php change — this is exactly the kind of edit that gets made casually in a hotfix branch.

False positives will define your experience with the translation guard. The usual suspects:

• Keys built at runtime ('errors.' . $code) — the guard sees a string that was never in a catalogue.
• Pluralization and ICU message formats — the resolved value may legitimately not equal the key.
• Fallback locales — a key missing in fr but present in en may resolve via fallback, depending on how the guard is implemented. Test this explicitly with your fallback config.
• Parameter placeholders (:attribute, {name}) — the comparison needs to happen on the raw catalogue entry, not the substituted output.

Tune before you widen rollout. A check that cries wolf gets disabled by precisely the developer who most needs it.

Pin the version and check the lock before every framework upgrade. Run composer why-not symfony/framework-bundle ^7.0 (or your target) before scheduling the bump. A dev-only bundle with tight constraints on symfony/*, doctrine/orm, and php is a classic upgrade blocker, and because it's require-dev you will only find out on the branch that touches composer.json. Mitigation is a pinned constraint plus a pre-agreed willingness to fork or drop.

Determine boot-time vs on-demand behaviour early. If schema validation runs at kernel boot, it lands on every console command and every test in a large suite. Check the bundle's compiler passes before rolling out to a monorepo; the CI-duration creep is real and shows up as a slow, diffuse tax nobody attributes to the right cause.

Zero stars and zero dependents is a maintenance signal, not a verdict. Expect bus factor ~1, no third-party validation, and possible silence on a new Symfony major. Keep the fork-or-drop decision cheap: environment-gated, isolated, and pinned. Budget a half-day to reimplement if it breaks — the logic (translator decorator plus a schema validator) is plausibly 50–150 lines, which is the whole reason the fork option is viable.

Debugging checklist when a panel or check misbehaves:

1. bin/console cache:clear — new bundles and new compiler passes are invisible until the container is rebuilt.
2. bin/console debug:container <service-id> — confirm the service exists and see the concrete class.
3. bin/console list filtered by vendor prefix — confirm the command names you're scripting against actually exist in this version.
4. Check whether you're in dev versus test — the gating in config/bundles.php is per-environment, and "it doesn't throw in tests" is usually a test array entry that was never added.
5. For the Profiler specifically, confirm the web debug toolbar is enabled and that you're looking at the current request's profile, not a cached earlier one.

Extension points worth knowing. The two useful seams are the translator decorator (to customise the message, add an allowlist for known-dynamic keys, or downgrade to a log entry for specific namespaces) and the Doctrine validation path (to scope which entity managers are checked, if the bundle allows it). Both are where you'd fork if upstream goes quiet — keep any local customisation in your own bundle or a small patch layer so a version bump doesn't mean re-resolving conflicts.

Alert fatigue is a live risk on small teams. A strict check that fires on every dynamic translation key during a refactor will be turned off within a week. Give yourself one configuration knob — an allowlist of namespaces or a severity switch — before you need it, and document that it exists so nobody reaches for the bundles.php nuclear option instead.

Don't sequence this ahead of anything. It's a quality-of-life tripwire, not a blocker. Adopt it in the quiet week, not the release week.