Version Bundle Laravel Package

Getting Started

zenstruck/version-bundle is a Symfony2-era bundle whose single job is to surface your application's version string as a service (and, typically, a Twig helper and/or console output). It is archived and unmaintained, so treat "getting started" as "how to evaluate whether to pull this into an existing legacy app" rather than a greenfield recommendation.

Minimal steps in a legacy Symfony 2.x/3.x app:

1. Require it (last tagged release, no active support):

   composer require zenstruck/version-bundle
   

2. Register the bundle in app/AppKernel.php:

   new Zenstruck\VersionBundle\ZenstruckVersionBundle(),
   

3. Point it at a version source. The practical pattern is a plain VERSION file at the project root (or a %app.version% parameter) that your deploy pipeline rewrites. Check the bundle's DependencyInjection/Configuration.php for the exact config key names — the README is thin and the bundle predates modern Symfony config conventions.
4. First use case: render the version in a footer or an internal /version route so QA and on-call can confirm which build is actually deployed. That single use case justifies the bundle more than anything else.

Where to look first: the bundle's DependencyInjection/ (to see the config tree and service aliases) and its Resources/config/ XML/YAML, because the service id and Twig function name are what you'll actually call. If the README doesn't state them, app/console container:debug | grep version tells you faster than reading code.

Implementation Patterns

Deploy-stamped version file. The highest-leverage pattern: have CI write git describe --tags --always (or a build number) into VERSION as the final deploy step, and let the bundle read that file. Version then reflects the artifact, not a hand-edited constant. Keep the file path relative to %kernel.root_dir% in config so it works from CLI and web alike.

Twig footer / debug badge. Expose the version as a Twig global or via the bundle's Twig extension and render it in a layout footer, gated by environment:

{% if app.debug %}v{{ version }}{% endif %}

This is where 90% of consumers of a bundle like this actually use it.

Health/version endpoint. A small controller returning {"version": "..."} (JSON) is what load balancers, smoke tests, and deploy verification scripts consume. Do not expose it publicly without auth if the string embeds framework/PHP version details — keep it internal-facing.

Release tagging into error reporting. Inject the version service into your exception listener or Sentry/Raven client config as the release/environment tag. This is the pattern that turns a version string from cosmetic into operationally useful: errors group by deploy.

Asset cache-busting. Append the version to asset URLs (?v={{ version }}) so a deploy invalidates browser caches without a full asset-hashing pipeline. Cheap and effective in Symfony2-era stacks.

Console surfacing. A version:show-style command (or wiring the service into an existing --version output) lets ops confirm the build from the box without hitting HTTP.

Integration tip: if you're on a newer Symfony, skip the bundle entirely — define parameters: app.version: '%env(APP_VERSION)%' and a one-line Twig global. The bundle's value is only in not touching an app you don't want to refactor.

Gotchas and Tips

• Archived ≠ abandoned silently. There are zero dependents and 3 stars; you are the only person who will ever debug this. Pin the exact version in composer.json and be prepared to vendor a fork.
• Container caching bites file-based versions. If the bundle reads the version file at container-compile time, changing VERSION on a running box won't be reflected until cache:clear/warmup. Confirm whether the service reads lazily in the constructor; if not, prefer a parameter injected from the file at deploy time so cache semantics are explicit.
• Path resolution. Version file paths configured relative to the kernel root behave differently under app/console vs. web requests and inside PHPUnit. Use %kernel.root_dir%/../VERSION explicitly rather than guessing.
• Deploy excludes. Very common failure: .gitignore or your rsync/Deployer exclude list drops VERSION, so production reports unknown. Assert the file exists in your post-deploy smoke test.
• Exact config keys are undocumented. The bundle predates Symfony's TreeBuilder conventions in places; run container:debug and read Configuration.php rather than trusting blog snippets.
• Don't leak the version. A public /version that reveals Symfony 2.8.x is a small but real fingerprinting aid. Gate behind internal network or auth.
• Extension points. If behavior is close-but-not-right, the cheapest fix is usually to override the Twig extension or wrap the version service in your own AppVersion service that delegates to the bundle — don't patch vendor/.
• Migration path. For anything still alive, the end state is: one APP_VERSION env var or a generated version.php, a Twig global, and a health route. That's ~15 lines and removes an archived dependency — worth doing the next time you touch the deploy pipeline.