Crescendo Var Bundle Laravel Package

Getting Started

• composer require phillarmonic/crescendo-var-bundle.
• First, understand what you're installing. Despite the generic description, the -bundle suffix means this is a Symfony bundle, not a Laravel package. There is no ServiceProvider and Composer auto-discovery will not pick it up in a Laravel app.
• In a Symfony host, register it in config/bundles.php and add a config/packages/crescendo_var.yaml block. In Laravel, you'll either (a) run it inside a Symfony sidecar service, or (b) if the core classes are framework-agnostic, instantiate them manually from your own service provider — verify by inspecting src/ before committing.
• Read these files first, in order:
  1. DependencyInjection/Configuration.php — the config schema tells you what a "variable" actually is here (config value, env var, runtime token, template var).
  2. DependencyInjection/*Extension.php — what services get registered and under which IDs.
  3. The bundle class itself — tags, compiler passes, and any Twig/console wiring.
• First use case: declare one trivial variable in config and resolve it through the injected service. Then run bin/console debug:container | grep -i crescendo (or debug:container <id> --show-arguments) to confirm it registered and to discover the concrete service ID. That one command will tell you more than the README.

Implementation Patterns

• Config-first definition. Treat the bundle as a registry: declare variables in config/packages/crescendo_var.yaml, then consume them via constructor injection of the exposed service rather than reaching for the container. This keeps your code testable and lets config be environment-switched (when@dev, when@prod).
• Constructor injection, not $container->get(). Add the variable service as a dependency on the consumers (controllers, services, Twig extensions). If the bundle exposes a locator/registry, inject that and resolve by name at the point of use.
• Laravel bridge pattern. If the core is PSR-friendly, write a thin CrescendoVarServiceProvider that binds the underlying class as a singleton and publishes a config stub. Do not attempt to register the Symfony bundle class in a Laravel app — it expects a Kernel/ContainerBuilder lifecycle.
• View layer. If a Twig extension is registered, mirror the same data into Laravel Blade by resolving the service in a view composer so both stacks see identical values. This avoids drift when the same team maintains a Symfony and a Laravel app.
• Testing. Mock the variable service in unit tests; use a real container in integration tests. Snapshot the resolved values in a small test so a config change that silently renames a variable fails loudly.
• Workflow: define → resolve in a service → consume in controller/view → assert in test. Keep the "define" step in version-controlled config, never in code, so ops can override without a deploy.

Gotchas and Tips

• Bundle ≠ package. The single biggest pitfall for a Laravel developer: auto-discovery, php artisan vendor:publish, and config/app.php provider registration all do nothing here. Budget time to read the DI extension.
• Adoption risk is real. Zero stars and zero dependents means no community safety net. Pin an exact version in composer.json, read composer.lock after install, and skim the source for env()/getenv() calls and any eval/dynamic class loading before it touches production.
• Ambiguous "var". The name doesn't say whether this handles config values, environment variables, or template variables. Confirm from the Configuration tree — the behavior you assume is the bug you'll ship.
• Cache invalidation. After changing bundle config, clear the container cache (bin/console cache:clear / rm -rf var/cache). Stale compiled containers are the most common "it's not picking up my variable" cause.
• Debugging: debug:container to find service IDs, debug:config crescendo_var to see the merged config, and debug:event-dispatcher if the bundle hooks kernel events. In Laravel, php artisan about won't help — inspect the bound instance directly.
• Extension points to look for: compiler passes (for compile-time variable injection), tagged services (for registering variable providers), and any events dispatched on resolve. These are your clean hooks; avoid subclassing internals that may churn between releases.
• Prefer a plain config value or config() call if all you need is static configuration — reserve this bundle for cases where its resolution logic (ordering, typing, lazy evaluation) genuinely earns its keep.