Assetic Minifier Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require davidjegat/assetic-minifier-bundle
   

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

   DavidJegat\AsseticMinifierBundle\DavidJegatAsseticMinifierBundle::class,
   

2. Configure Assetic: Ensure assetic/assetic-bundle is installed and configured in config/packages/assetic.yaml (Laravel) or app/config/config.yml (Symfony). Example:

   assetic:
       filters:
           minify_css: ~
           minify_js: ~
   

3. First Use Case: In a Twig template (or Blade via {{ asset() }} with Assetic integration), apply filters:

   {% stylesheets
       'css/style.css'
       filter='minify_css'
   %}
       <link rel="stylesheet" href="{{ asset_url }}">
   {% endstylesheets %}
   

   For JavaScript:

   {% javascripts
       'js/app.js'
       filter='minify_js'
   %}
       <script src="{{ asset_url }}"></script>
   {% endjavascripts %}
   

Implementation Patterns

Workflows

1. Development vs. Production:

   • Use filter="?minify_css" (optional) in dev to toggle minification dynamically.
   • In production, always apply filters to critical assets for performance.

2. Asset Grouping: Combine minification with Assetic’s grouping for efficiency:

   {% stylesheets
       ['css/vendor.css', 'css/main.css']
       filter='minify_css'
       output='css/all.min.css'
   %}
   

3. Laravel-Specific Integration:

   • Use asset() with Assetic’s dump() in app/Providers/AppServiceProvider@boot():

     $this->loadViewsFrom(__DIR__.'/../resources/views', 'app');
     $this->app->register(\Assetic\Bundle\AsseticBundle\AsseticBundle::class);
     AsseticAsset::setFacadeApplication($this->app);
     

   • Generate minified assets via Artisan:

     php artisan assetic:dump --env=production
     

4. Dynamic Filtering: Conditionally apply minification based on environment:

   {% set filter = app.environment === 'prod' ? 'minify_css' : '' %}
   {% stylesheets 'css/file.css' filter=filter %}
   

Integration Tips

• Cache Control: Set assetic.read_from and assetic.write_to in config to avoid rebuilding assets unnecessarily. Example:

  assetic:
      read_from: '%kernel.project_dir%/web/assets'
      write_to: '%kernel.project_dir%/web/build/assets'
  

• Versioning: Append a version query string to minified assets for cache busting:

  <link href="{{ asset_url }}?v={{ '1.0'|hash }}">
  

• Laravel Mix/Vite: Use this bundle for pre-processing before handing off to Laravel Mix/Vite for advanced optimizations (e.g., Webpack).

Gotchas and Tips

Pitfalls

1. Filter Naming Conflicts:

   • Ensure minify_css/minify_js filters are not overridden by other Assetic filters (e.g., yui_css or uglifyjs). Check config/packages/assetic.yaml for duplicates.

2. PHP Version Compatibility:

   • The underlying JSMin and CssMin libraries may have edge cases with PHP 8.x. Test with:

     composer require --dev phpunit/phpunit
     vendor/bin/phpunit
     

3. Twig vs. Blade:

   • Blade templates require manual Assetic integration. Use {{ asset('css/file.css', ['filter' => 'minify_css']) }} (if using a custom helper).

4. Debugging Minification:

   • Disable minification temporarily to isolate issues:

     filter=''  {# Disable filter #}
     

   • Check raw output with:

     php artisan assetic:dump --dump
     

Debugging

• Log Minified Output: Temporarily log minified content to storage/logs/assetic.log by extending the bundle’s service:

  // config/services.yaml
  DavidJegat\AsseticMinifierBundle\Minifier\CssMinifier:
      arguments:
          $logger: '@monolog.logger.assetic'
  

• Validate Input: The minifier may fail on malformed CSS/JS. Validate with:

  php artisan assetic:debug
  

Extension Points

1. Custom Minifiers: Override the default minifiers by binding custom services:

   # config/services.yaml
   DavidJegat\AsseticMinifierBundle\Minifier\CssMinifier:
       class: App\Minifier\CustomCssMinifier
   

2. Pre/Post-Processing: Chain additional filters (e.g., terser for JS) after minification:

   filter=['minify_js', 'terser']
   

3. Exclude Files: Skip minification for specific files using Assetic’s exclude option:

   assetic:
       filters:
           minify_css:
               exclude: ['css/print.css']
   

4. Performance Tuning:

   • For large projects, pre-compile assets during deployment:

     php artisan assetic:dump --env=production --no-debug
     

   • Use assetic.use_controller to serve minified assets via Symfony’s HTTP cache.

Quirks

• CSS Comments: CssMin aggressively removes comments. Use /*! preserve */ to retain critical comments.
• JS Minification: JSMin may break source maps. Disable with:

  assetic:
      filters:
          minify_js:
              preserve_comments: true
  

• Case Sensitivity: Filter names in Twig are case-sensitive. Use minify_css, not MinifyCss.

```markdown
## Configuration Reference
```yaml
# Example assetic.yaml (Laravel)
assetic:
    filters:
        minify_css:
            # Optional: Enable/disable
            enabled: true
            # Optional: Custom minifier class
            class: App\Minifier\CustomCssMinifier
        minify_js:
            enabled: true
            # Optional: Preserve comments (default: false)
            preserve_comments: false
    assets:
        app_css:
            inputs:
                - 'css/app.css'
            filters: [minify_css]
            output: 'css/app.min.css'