Assetcachebuster Laravel Package

Getting Started

• Treat this as a legacy Laravel 4.2/5.x-era package. v2.0.0 is the first release with explicit Laravel 5 compatibility, so pin spekkionu/assetcachebuster:^2.0 on any Laravel 5 project, and do not assume v1.x constraints carry over.
• Before installing, inspect its composer.json constraints against your exact Laravel minor version — "Laravel 5" in the release notes may mean 5.0–5.4 only, and the release notes say nothing about 5.5+ package discovery. On Laravel 8+, the practical answer is still "don't install it; use mix() or Vite."
• Install with composer require spekkionu/assetcachebuster:^2.0.
• Register Spekkionu\AssetCacheBuster\AssetCacheBusterServiceProvider manually in config/app.php, and add the AssetCacheBuster facade alias if the README requires it. Nothing in v2.0.0 indicates auto-discovery was added, so assume manual registration even on 5.5+.
• Publish and read the config: php artisan vendor:publish --provider="Spekkionu\AssetCacheBuster\AssetCacheBusterServiceProvider". Look for the manifest path, public path, hash/URL format, and environment switches.
• First places to look: the README, the published config/assetcachebuster.php, and the service provider to see the registered helper/facade and container bindings.
• First use case: replace asset('css/app.css') and asset('js/app.js') in resources/views/layouts/app.blade.php with the package's URL resolver, after your asset build has produced the hash map/manifest.
• Verify one path quickly via php artisan tinker or a temporary route before rolling it across layouts.

Implementation Patterns

• Centralize asset resolution in one Blade partial or app helper. Do not scatter package calls through every view; that makes later migration to mix()/Vite painful.
• Use the package as the read side of your build pipeline: the build emits a manifest or hash map (css/app.css → css/app-abc123.css), and the package resolves logical paths to public URLs.
• Keep one manifest for all compiled CSS/JS unless the package explicitly supports multiple manifests. Treat missing manifest entries as build failures, not runtime surprises.
• Use environment-specific behavior: plain asset() or disabled cache busting locally; required hashed entries in production. This reduces local friction while keeping production strict.
• In deployment, build assets before deploying, ship the manifest with the release, then clear/rebuild config cache. Add a CI check that every asset referenced in layouts exists in the manifest.
• For CDN setups, resolve the package URL first, then prepend the CDN host through config or a small wrapper. Keep path generation in one place.
• Wrap the package facade/helper in your own asset_url() helper. That gives you a single extension point and makes replacement with Laravel Mix/Vite a one-file change.
• Test rendered layouts: assert the hashed filename appears and that a missing manifest key fails loudly in production-like tests.
• When upgrading an existing legacy install to v2.0.0, diff the published config and the service provider against your checked-in copies — a major version bump on a package this old is the most likely place for a silently changed default.

Gotchas and Tips

• This package is unmaintained since 2015; v2.0.0 is a Laravel 5 compatibility bump, not renewed maintenance. Expect Composer conflicts and no Laravel 5.5+ auto-discovery. Do not force it into a modern Laravel app without a clear legacy reason.
• Verify what "Laravel 5" covers in practice: check the illuminate/support constraint and run one real install on your target minor before committing. Laravel 5.5+ discovery is a separate mechanism the release notes do not claim.
• Config caching is a common trap: after changing the manifest path, run php artisan config:clear; in production run config:cache only after the manifest exists.
• Manifest freshness matters more than the package itself. A stale manifest means stale hashes and stale browser caches. Missing keys may return the original path, throw, or return an empty URL depending on the installed version — verify the behavior on v2.0.0 specifically, since it may differ from what you observed on v1.x.
• Watch path resolution: paths are usually relative to public/, so leading slashes, Windows separators, and symlinked public directories (Envoyer/Deployer) can break lookups.
• Prefer filename hashes over query-string hashes where possible. CDNs and proxies sometimes ignore query strings. If the package emits query strings, remember Blade {{ }} escapes &; only use {!! !!} when the URL is trusted.
• Check case sensitivity. Manifest keys must match exactly; macOS may hide problems that Linux production exposes.
• If the package caches the manifest at boot, long-running workers or Octane may need a restart after deployment.
• Extension points are likely limited. Inspect the service provider for bindings (compare them against v1.x if you are upgrading), but assume your app-level wrapper is the real customization layer.