Assetversionbundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require alpixel/assetversionbundle
   

   Ensure your composer.json has PHP ≥5.3.0 and Symfony <3.3 (due to bundle compatibility).

2. Register the Bundle Add to app/AppKernel.php:

   new Alpixel\Bundle\AssetVersionBundle\AlpixelAssetVersionBundle(),
   

3. First Use Case

   • Pre-process assets (e.g., with gulp-rev) to generate versioned filenames (e.g., vendor.min.css → vendor.min.abc123.css).
   • Use the Twig extension in templates:

     <link rel="stylesheet" href="{{ asset('css/vendor.min.css'|asset_version) }}">
     

   • The |asset_version filter appends the version hash (e.g., vendor.min.abc123.css).

Implementation Patterns

Workflow Integration

1. Asset Pipeline

   • Use tools like gulp-rev, webpack, or grunt to generate versioned assets (e.g., assets/css/style.css → assets/css/style.abc123.css).
   • Store versioned filenames in a manifest file (e.g., assets.json) for reference.

2. Twig Template Usage

   • Leverage the asset_version filter to dynamically append version hashes:

     {% for file in ['style.css', 'script.js'] %}
       <link href="{{ asset('css/' ~ file)|asset_version }}">
     {% endfor %}
     

   • Cache-busting is automatic; no manual version tags needed.

3. Symfony Asset Integration

   • Combine with Symfony’s asset() function for full path resolution:

     <script src="{{ asset('js/app.min.js'|asset_version) }}"></script>
     

4. Dynamic Versioning

   • For dynamic assets (e.g., uploaded files), use a custom Twig function or extension to fetch versions from a database or file.

Configuration Tips

• No Bundle Config: The bundle requires zero configuration—just register it and use the Twig filter.
• Fallback Behavior: If the versioned file doesn’t exist, the filter falls back to the original filename (e.g., vendor.min.css).

Gotchas and Tips

Pitfalls

1. Symfony 3.3+ Incompatibility

   • The bundle only works with Symfony <3.3. For newer versions, use Symfony’s built-in manifest-based versioning.
   • Workaround: Fork the bundle or use a polyfill like stfalcon/tinymce-bundle for asset management.

2. Version Hash Mismatch

   • If the versioned file (e.g., vendor.min.abc123.css) doesn’t exist, the filter silently falls back to the original. Debug tip: Verify your asset pipeline generates correct hashes.
   • Fix: Ensure your build tool (e.g., gulp-rev) updates the manifest file (assets.json) with accurate mappings.

3. Caching Headaches

   • The bundle doesn’t invalidate browser caches. Use HTTP cache headers (e.g., Cache-Control: max-age=31536000) or a CDN to manage caching.
   • Tip: Pair with symfony/webpack-encore for modern asset pipelines with cache-busting.

4. Twig Filter Scope

   • The asset_version filter only works in Twig templates. For PHP logic, use the underlying service:

     $versionedPath = $this->get('alpixel_asset_version.twig_extension')->getVersionedPath('css/vendor.min.css');
     

Debugging

• Check Generated Paths:

  {{ dump(asset('css/vendor.min.css'|asset_version)) }}
  

  Verify the output matches your expected versioned filename.

• Manifest Validation: If using gulp-rev, ensure assets.json is in your web/ directory and includes all versioned files:

  {
    "css/vendor.min.css": "css/vendor.min.abc123.css"
  }
  

Extension Points

1. Custom Version Sources Override the default behavior by extending the bundle’s AssetVersionExtension:

   // src/Alpixel/Bundle/AssetVersionBundle/DependencyInjection/Compiler/OverrideExtensionPass.php
   public function process(ContainerBuilder $container) {
       $extension = $container->getDefinition('alpixel_asset_version.twig_extension');
       $extension->addMethodCall('setCustomVersionResolver', [new Callback('app.custom_version_resolver')]);
   }
   

2. Dynamic Versioning For database-driven assets, create a custom Twig function:

   // src/App/Twig/AppExtension.php
   public function getFunctions() {
       return [
           new \Twig_SimpleFunction('dynamic_asset_version', [$this, 'getDynamicVersionedPath']),
       ];
   }
   

3. Fallback Logic Modify the Twig extension to handle missing files differently (e.g., throw an exception):

   // Override Alpixel\Bundle\AssetVersionBundle\Twig\AssetVersionExtension
   public function getVersionedPath($path) {
       if (!file_exists($this->getVersionedAssetPath($path))) {
           throw new \RuntimeException("Versioned asset not found: {$path}");
       }
       return parent::getVersionedPath($path);
   }