Assetic Filter Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require catchamonkey/assetic-filter-bundle
   

   Register the bundle in app/AppKernel.php:

   new Catchamonkey\Bundle\AsseticFilterBundle\CatchamonkeyAsseticFilterBundle(),
   

2. First Use Case: Apply the filter directly in a Twig template:

   {% stylesheets filter='catchamonkey_cssmin' '@YourBundle/Resources/public/css/*.css' %}
       <link rel="stylesheet" href="{{ asset_url }}">
   {% endstylesheets %}
   

   Verify the output in browser dev tools (minified CSS).

Where to Look First

• Bundle Docs: Check the GitHub README for updates.
• Assetic Config: Review app/config/config.yml for global filter configurations (e.g., apply_to).
• Twig Usage: Focus on the {% stylesheets %} tag syntax for quick integration.

Implementation Patterns

Workflows

1. Template-Based Minification: Use the filter parameter in Twig’s {% stylesheets %} block for ad-hoc minification:

   {% stylesheets filter='catchamonkey_cssmin' '@Bundle/Resources/public/css/main.css' %}
       {{ asset_url }}
   {% endstylesheets %}
   

2. Global Configuration: Apply the filter to all CSS assets via assetic.yml:

   assetic:
       filters:
           catchamonkey_cssmin: ~
       assets:
           app_styles:
               inputs:
                   - '@Bundle/Resources/public/css/*.css'
               filters: [catchamonkey_cssmin]
   

   Reference in Twig:

   {{ asset('app_styles') }}
   

3. Conditional Minification: Toggle the filter based on environment (e.g., debug mode):

   {% if not app.debug %}
       {% stylesheets filter='catchamonkey_cssmin' '...' %}
   {% else %}
       {% stylesheets '...' %}
   {% endif %}
   

Integration Tips

• Combine with Other Filters: Chain filters in assetic.yml for multi-step processing (e.g., cssrewrite + catchamonkey_cssmin):

  filters:
      catchamonkey_cssmin: ~
      cssrewrite: ~
  assets:
      app_styles:
          filters: [cssrewrite, catchamonkey_cssmin]
  

• Custom Filter Naming: Rename the filter in assetic.yml for clarity:

  filters:
      my_cssmin: { filter: catchamonkey_cssmin }
  

  Use in Twig:

  {% stylesheets filter='my_cssmin' '...' %}
  

• Asset Versioning: Leverage Assetic’s built-in versioning to bust caches when CSS changes:

  {{ asset('app_styles', { version: '1.0' }) }}
  

Gotchas and Tips

Pitfalls

1. Bundle Registration: Forgetting to register the bundle in AppKernel.php will silently fail (no errors, but filter won’t work). Fix: Verify the bundle is listed in registerBundles().

2. Filter Name Sensitivity: The filter name in Twig (catchamonkey_cssmin) must match the config key exactly (case-sensitive). Fix: Double-check assetic.yml and Twig usage.

3. Debug Mode Conflicts: Assetic’s debug: true in config.yml disables filters entirely. Minification won’t work in dev. Fix: Use environment-specific configs or toggle filters conditionally in Twig.

4. Circular Dependencies: Minifying CSS with @import rules may fail if dependencies aren’t resolved first. Fix: Use cssrewrite before catchamonkey_cssmin in the filter chain.

Debugging

• Check Output: Inspect the generated HTML source to confirm the <link> tag includes the filter. Example:

  <link rel="stylesheet" href="/build/app_styles.css?123abc">
  

  Open the URL to verify minification.

• Log Filter Application: Enable Assetic’s debug mode temporarily to log filter execution:

  assetic:
      debug: true
  

  Check var/log/dev.log for filter-related entries.

Tips

1. Performance: Combine minification with asset concatenation to reduce HTTP requests:

   assets:
       app_styles:
           inputs: ['@Bundle/Resources/public/css/*.css']
           filters: [catchamonkey_cssmin]
   

2. Extending the Filter: Override the default minifier by extending the bundle’s service (advanced):

   services:
       catchamonkey_cssmin:
           class: Catchamonkey\Bundle\AsseticFilterBundle\Filter\CssMinFilter
           arguments: ['@some_custom_minifier']
   

3. Testing: Test minification in CI by comparing output hashes:

   php bin/console assetic:dump --env=test --no-debug
   git diff --no-index <(curl -s http://localhost/test.css) <(echo "unminified.css")
   

4. Fallback Strategy: Provide a fallback for unsupported CSS features (e.g., custom properties):

   {% if filter('catchamonkey_cssmin') %}
       {% stylesheets filter='catchamonkey_cssmin' '...' %}
   {% else %}
       {% stylesheets '...' %}
   {% endif %}