Assets Version Bundle Laravel Package

Getting Started

Compatibility reality check first. This is a Symfony 2/3 bundle, not a Laravel package. There is no composer require + service-provider path in a Laravel app, no extra.laravel autoload config, and no Artisan integration. If you are on Laravel, treat this repo as a pattern reference, not a dependency: Laravel already solves cache-busting via Mix/Vite manifest hashing. The only scenario where the bundle's query-string versioning is worth replicating is a legacy app that appends ?v= to asset URLs and cannot adopt hashed filenames.

For a Symfony 2/3 project where you actually want it running:

1. Pin the dependency. The repo is archived. Require an explicit constraint ("kachkaev/assets-version-bundle": "~1.0", or the last tagged release) and commit composer.lock. Do not rely on dev-master resolving in future CI.

2. Register the bundle in app/AppKernel.php. Bundles of this era are enabled per-environment — add it to every registerBundles() path you actually deploy, not just dev.

3. Point Symfony's asset version at a parameter in app/config/config.yml:

   framework:
       templating:
           assets_version: "%assets_version%"
   

   Ensure assets_version exists in app/config/parameters.yml and that the file is writable by the process running the command — the bundle rewrites the parameter in place.

4. Discover the update command with bin/console list | grep -i version. The README names it, but discovering locally protects you against doc drift on an archived project.

5. First use case: run the command, then render a page and confirm {{ asset('css/app.css') }} emits ?v=<new-value>. That round trip — command → parameter file → template helper → browser cache-bust — is the entire product. If that loop works, everything else is ceremony.

Implementation Patterns

Wire the bump into the deploy pipeline, not into humans. The bundle's only real value is that nobody forgets to increment a number. Day-to-day, that means the bump command belongs inside your release step (Capistrano/Deployer hook, CI script), positioned after new assets are uploaded and before the new release goes live.

Recommended ordering inside a deploy:

1. Upload new static assets (new files present, old files still present)
2. Run the bundle's version-bump command
3. Clear Symfony's cache (cache:clear / cache:warmup)
4. Switch the web symlink / enable the new release
5. Prune the previous asset generation only after cache TTLs expire

Global version-string pattern (the bundle's model) invalidates every asset on every deploy. That is fine for small sites and catastrophic on high-traffic ones — every client re-downloads the full set simultaneously, and cached HTML at the edge can pin a version whose files were already pruned. Reach for this only when per-file hashing is genuinely unavailable.

Laravel-native equivalents to reach for instead, in preference order:

If you must replicate the pattern in Laravel, the whole feature is roughly: a config('app.assets_version') value set from an env var at deploy time, and an asset_versioned() helper that appends ?v= to asset(). That is ~20 lines you own, versus carrying an archived zero-dependent Symfony bundle you cannot use on Laravel anyway.

Migration pattern (Symfony → native). In a legacy Symfony service that still uses this bundle: (1) grep templates for the bundle's Twig helper calls; (2) swap them for Symfony's native asset() + webpack-encore versioning (Symfony-maintained equivalent); (3) remove kachkaev/assets-version-bundle from composer.json; (4) confirm no kachkaev_assets_version config keys remain referenced. Do this on the Symfony side — it does not touch the Laravel codebase.

Gotchas and Tips

Deploy race — 404s on every asset. If the version string flips before the new assets land, every request in the gap asks for a version that does not exist. Always upload assets first, flip the version last. Add a smoke test that asserts the rendered asset URL actually changed between deploys.

Config cache drift. In Symfony, the version parameter can be baked into a compiled container and never re-read if you forget cache:clear. You get a silent no-op — the number in parameters.yml updated, but the served URLs did not. Mirror the same trap in Laravel: if you cache config (php artisan config:cache), the version env var must be re-cached as an explicit deploy step, or cache-busting silently stops working.

Stale HTML at the edge. Cached HTML pins an old version whose files were pruned in a later deploy. Fix: never delete the previous asset generation until cache TTLs expire, or invalidate HTML at the edge as part of the release.

Multi-instance skew during rolling deploys. Old and new instances serve different version strings. Usually benign for assets (both versions still resolve), but any client that hardcodes an asset URL breaks. Hashed filenames sidestep this entirely.

File-writability trap. The bump command mutates parameters.yml in place. In read-only or containerized deployments this fails silently or throws mid-deploy. Either mount the config writable, or — better — set the version from an environment variable in config.yml (assets_version: "%env(ASSETS_VERSION)%") so the command is not needed at all. That is the extension point worth taking from this bundle: version as an env var, not as a mutated file.

Archived + zero dependents = no safety net. No CVE triage, no maintainer, 57 stars, Symfony 2/3 long EOL (3.4 went EOL late 2021). Any break is yours to fix. On PHP 8.2/8.3 base images, expect platform-constraint failures — installing usually needs --ignore-platform-reqs, which is itself a red flag for a production dependency.

Debugging checklist when cache-busting "stops working":

1. Does bin/console debug:container --parameter=assets_version show the expected value? (Symfony) — or config('app.assets_version') in Laravel.
2. Is the rendered URL actually different, or did config cache pin the old value?
3. Did the deploy prune old files before edge TTLs expired?
4. Is a CDN serving cached HTML that references a dead version?

The takeaway for a Laravel developer: do not adopt. Log it as evaluated-and-rejected with the Vite/@vite recommendation attached. If real cache-busting work surfaces from this audit, redirect it to the deploy pipeline (content-hashed Vite manifest + a post-deploy CDN invalidation step) where it belongs — not to an archived Symfony bundle with no viable path into a Laravel estate.