Assets Buster Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avholodnyak/assets-buster-bundle
   

   Register the bundle in config/bundles.php (Symfony 4+) or AppKernel.php (Symfony 3):

   AVHolodnyak\AssetsBusterBundle\AssetsBusterBundle::class => ['all' => true],
   

2. Configure: Add to config/packages/assets_buster.yaml (Symfony 4+) or config/config.yml (Symfony 3):

   assets_buster:
       busters_path: "%kernel.project_dir%/public/busters.json"
       version_format: "%s?v=%s"  # Optional: Customize version format
   

3. Generate Buster File: Use gulp-buster to generate busters.json:

   npm install --save-dev gulp-buster
   

   Example gulpfile.js:

   const gulp = require('gulp');
   const buster = require('gulp-buster');
   
   gulp.task('buster', () =>
       gulp.src(['public/css/*.css', 'public/js/*.js'])
           .pipe(buster())
           .pipe(gulp.dest('public'))
   );
   

4. First Use Case: Reference assets in Twig/PHP templates as usual:

   <link rel="stylesheet" href="{{ asset('css/app.css') }}">
   <script src="{{ asset('js/main.js') }}"></script>
   

   The bundle auto-appends versions (e.g., ?v=abc123) if entries exist in busters.json.

Implementation Patterns

Workflows

1. Asset Versioning Pipeline:

   • Development: Run gulp buster after asset changes to update busters.json.
   • Production: Rebuild assets and regenerate busters.json during deployment (e.g., via CI/CD).

2. Integration with Asset Pipelines:

   • Webpack/Vite: Use gulp-buster alongside your bundler to generate versioned hashes. Example: Post-build hook in package.json:

     "scripts": {
       "build": "webpack && gulp buster"
     }
     

   • Symfony AssetMapper: Combine with AssetMapper for dynamic asset paths:

     {{ asset('controller/action', 'css/app.css') }}  {# Auto-resolves to public/css/app.css #}
     

3. Conditional Versioning:

   • Omit entries from busters.json for assets that should not bust cache (e.g., third-party CDN assets).
   • Example busters.json:

     {
       "css/app.css": "abc123",
       "js/main.js": "def456"
       // "vendor/jquery.js": null  {# No version appended #}
     }
     

4. Environment-Specific Config: Override busters_path per environment (e.g., config/packages/dev/assets_buster.yaml):

   assets_buster:
       busters_path: "%kernel.project_dir%/public/busters-dev.json"
   

Tips for Daily Use

• Atomic Updates: Regenerate busters.json only for changed files to minimize rebuilds.
• Cache Invalidation: Clear Symfony’s asset cache after updating busters.json:

  php bin/console cache:clear --env=prod
  

• Debugging: Temporarily set version_format: "%s?debug=%s" to verify versions are being read.

Gotchas and Tips

Pitfalls

1. File Path Mismatches:

   • Issue: busters_path must point to the root-relative path of busters.json (e.g., public/busters.json). Using web/busters.json (Symfony 3 default) may fail if assets are served from public/.
   • Fix: Ensure paths in busters.json match the public URL of assets (e.g., "css/app.css" not "web/css/app.css").

2. Symfony 4+ Configuration:

   • Issue: The bundle expects config.yml in Symfony 3. In Symfony 4+, use config/packages/assets_buster.yaml.
   • Fix: Create the file and reference it in config/bundles.php.

3. Version Format Quirks:

   • Issue: Custom version_format (e.g., "%s#%s") may break asset linking if not URL-encoded.
   • Fix: Stick with default "%s?v=%s" or ensure the format is URL-safe.

4. Missing Buster Entries:

   • Issue: Assets without entries in busters.json render without versions, which can cause stale cache issues.
   • Fix: Either:
     • Include all assets in busters.json (even with placeholder versions).
     • Use a fallback strategy (e.g., timestamp-based versions).

5. Gulp-Buster Compatibility:

   • Issue: gulp-buster may not handle nested directories or symlinked assets correctly.
   • Fix: Configure gulp-buster explicitly:

     gulp.src(['public/**/*.{css,js}'], { base: 'public' })
         .pipe(buster())
         .pipe(gulp.dest('public'));
     

Debugging

• Verify Buster File: Check busters.json is readable and contains valid JSON:

  cat public/busters.json
  

• Symfony Debug Toolbar: Use the Assets panel to inspect versioned URLs and debug missing entries.
• Log Custom Version Strategy: Enable debug mode to see if the bundle is registered:

  framework:
      profiler: { only_exceptions: false }
  

Extension Points

1. Dynamic Buster Paths: Override the BustersPathResolver service to fetch busters.json from an API or database:

   services:
       AVHolodnyak\AssetsBusterBundle\Resolver\BustersPathResolver:
           arguments:
               - "@request_stack"  # Example: Fetch path from request
   

2. Custom Version Strategies: Extend the bundle’s BusterVersionStrategy to support additional version sources (e.g., Git commits):

   class GitVersionStrategy extends BusterVersionStrategy {
       public function getVersion(string $path): ?string {
           return shell_exec("git rev-parse HEAD");
       }
   }
   

   Register it in services.yaml:

   AVHolodnyak\AssetsBusterBundle\VersionStrategy\VersionStrategyInterface:
       class: App\Strategy\GitVersionStrategy
   

3. Asset Filtering: Exclude specific assets (e.g., vendor/) from versioning by creating a custom AssetFilter:

   class VendorAssetFilter implements AssetFilterInterface {
       public function shouldVersion(string $path): bool {
           return !str_starts_with($path, 'vendor/');
       }
   }
   

   Bind it in services.yaml:

   AVHolodnyak\AssetsBusterBundle\AssetsBusterBundle:
       arguments:
           $assetFilter: '@App\Filter\VendorAssetFilter'