Gulp Buster Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require ajaxray/gulp-buster-bundle
   

   Enable in AppKernel.php:

   new Ajaxray\GulpBusterBundle\GulpBusterBundle(),
   

2. Generate busters.json Ensure your Gulp workflow uses gulp-buster to generate a busters.json file (default location: %kernel.root_dir%/../busters.json).

3. First Use Case In a Twig template, append cache-busting hashes to asset URLs:

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

   Output (if hash exists):

   <link rel="stylesheet" href="/css/app.min.css?v=abc123xyz">
   

Implementation Patterns

Workflow Integration

1. Gulp Pipeline Configure gulp-buster in your gulpfile.js to generate hashes for all static assets (JS, CSS, images):

   const buster = require('gulp-buster');
   gulp.task('build', () => {
       return gulp.src('src/**/*.{js,css}')
           .pipe(buster())
           .pipe(gulp.dest('web/build'));
   });
   

   This creates busters.json with file hashes.

2. Symfony Asset Pipeline Use the Twig filter |with_buster_hash in layouts (e.g., base.html.twig):

   {% block stylesheets %}
       {{ asset('bundles/app/css/style.css')|with_buster_hash }}
   {% endblock %}
   

3. Dynamic Asset Loading For dynamic assets (e.g., loaded via JavaScript), expose the busters.json path in Symfony:

   <script>
       const busters = {{ dump(app.request.get('busters'))|json_encode|raw }};
   </script>
   

   (Requires a custom controller to fetch busters.json and pass it to Twig.)

4. Environment-Specific Config Override paths in config.yml for different environments (e.g., dev/staging/prod):

   # config_dev.yml
   gulp_buster:
       busters_file: "%kernel.root_dir%/../var/cache/dev/busters.json"
   

Gotchas and Tips

Pitfalls

1. Missing busters.json

   • If the file is missing or misconfigured, the filter defaults to ?v=no-buster-hash-found.
   • Fix: Verify gulp-buster runs during your build process and the file path in config.yml is correct.

2. Case Sensitivity

   • The bundle compares filenames case-sensitively. Ensure paths in busters.json match those in Twig (e.g., css/App.css vs. css/app.css).
   • Fix: Normalize paths in Gulp or Twig (e.g., use lowercase filter in Twig).

3. Caching Headaches

   • Browsers cache query strings aggressively. If hashes don’t update, clear your cache:

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

   • Tip: Use ?v={{ hash }} instead of ?v=hash to avoid caching issues with short hashes.

4. Symfony Asset Versioning Conflict

   • If using Symfony’s built-in asset versioning (%kernel.debug%), the bundle’s hashes may conflict.
   • Fix: Disable Symfony’s versioning or configure the bundle to ignore debug mode:

     gulp_buster:
         debug_mode: false  # Disable in debug environments
     

Debugging Tips

1. Inspect busters.json Validate the file structure:

   {
       "css/app.min.css": "abc123xyz",
       "js/main.js": "def456uvw"
   }
   

   • Ensure keys match the filenames in asset() calls.

2. Log Filter Output Debug the Twig filter by adding a custom Twig extension:

   // src/Ajaxray/GulpBusterBundle/Twig/AppExtension.php
   public function getBusterHash(string $path): string {
       $hash = $this->container->get('ajaxray_gulp_buster.buster')->getHash($path);
       return $hash ?: 'DEBUG: No hash for ' . $path;
   }
   

   Register it in services.yml and use in Twig:

   {{ app.buster_hash('css/app.min.css') }}
   

3. Custom Hash Logic Extend the bundle to modify hash behavior (e.g., exclude certain files):

   // src/Ajaxray/GulpBusterBundle/DependencyInjection/Configuration.php
   $builder->appendNode(new ConfigurationNode('excluded_paths', 'array'))
       ->info('List of paths to exclude from cache busting');
   

   Then filter hashes in the Buster service.

Extension Points

1. Custom busters.json Parser Override the default JSON parser to support alternative formats (e.g., YAML):

   // src/Ajaxray/GulpBusterBundle/Service/Buster.php
   public function loadBustersFile(string $path): array {
       if (pathinfo($path, PATHINFO_EXTENSION) === 'yml') {
           return yaml_parse_file($path);
       }
       return json_decode(file_get_contents($path), true);
   }
   

2. Fallback for Missing Hashes Customize the fallback behavior (e.g., use a timestamp):

   {{ asset('css/app.css')|with_buster_hash('fallback=timestamp') }}
   

   (Requires extending the Twig filter.)

3. Integration with Webpack If migrating from Gulp to Webpack, use webpack-bundle-tracker and adapt the bundle to parse its output instead of busters.json.