Assetic Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation (if still needed for legacy projects):

   composer require devlabs91/assetic-bundle
   

   (Note: Only relevant for Symfony ≤3.4. New projects should use Webpack Encore.)

2. Enable the Bundle (in config/bundles.php):

   Devlabs91\AsseticBundle\Devlabs91AsseticBundle::class => ['all' => true],
   

3. Basic Configuration (in config/packages/devlabs91_assetic.yaml):

   assetic:
       assets:
           app_css:
               inputs:
                   - '%kernel.project_dir%/assets/css/style.css'
               filters: [cssrewrite]
   

4. First Use Case:

   • Dump assets via CLI:

     php bin/console assetic:dump --env=prod
     

   • Reference in Twig:

     {{ asset('bundles/devlabs91assetic/app_css.css') }}
     

Implementation Patterns

Core Workflows

1. Asset Organization:

   • Group inputs by type (e.g., app_css, vendor_js) in config/packages/devlabs91_assetic.yaml.
   • Use inputs for files/directories and outputs for compiled paths (default: web/build/).

2. Filter Chains:

   • Apply filters sequentially (e.g., cssrewrite, uglifyjs, yui_css).
   • Example:

     filters:
         cssrewrite: ~
         uglifyjs:
             bin: /usr/local/bin/uglifyjs
     

3. Environment-Specific Assets:

   • Override configurations per environment (e.g., dev, prod) using when: @assetic.environment_matches.
   • Example:

     when: '%kernel.debug%'
     assetic:
         assets:
             debug_js:
                 inputs: ['%kernel.project_dir%/assets/js/debug.js']
     

4. Twig Integration:

   • Use {% stylesheets %}/{% javascripts %} for dynamic asset management:

     {% stylesheets
         'css/main.css' filter='cssrewrite'
         output='css/app.css'
     %}
         <link rel="stylesheet" href="{{ asset('css/app.css') }}">
     {% endstylesheets %}
     

5. Asset Versioning:

   • Enable versioning in config/packages/devlabs91_assetic.yaml:

     versioning: true
     

Advanced Patterns

• Custom Filters: Extend Assetic\Filter\FilterInterface and register via:

  assetic:
      filters:
          custom_filter:
              class: App\Filter\CustomFilter
  

• Asset Dependencies: Define dependencies between assets to ensure correct load order:

  assets:
      main_js:
          inputs: ['js/main.js']
          dependencies: [app_css]
  

• Symfony Cache Integration: Leverage Symfony’s cache system for asset compilation:

  assetic:
      use_controller: true  # Cache assets in controller responses
  

Gotchas and Tips

Common Pitfalls

1. Deprecation Warning:

   • This bundle is deprecated for Symfony ≥4.0. Migrate to Webpack Encore or Vite.

2. Filter Binaries:

   • Ensure required binaries (e.g., uglifyjs, yui-compressor) are installed and paths are correct in config.
   • Debug with:

     php bin/console assetic:debug
     

3. Debug Mode Issues:

   • Assets may not update in dev mode. Clear cache:

     php bin/console cache:clear
     

4. Output Path Conflicts:

   • Default output (web/build/) may clash with other tools (e.g., Webpack). Customize:

     outputs:
         app_css: '%kernel.project_dir%/public/assets/css/'
     

5. Twig Autoloading:

   • Ensure Twig extensions are registered in config/packages/twig.yaml:

     twig:
         extra:
             assetic: true
     

Debugging Tips

• Check Asset Dumping:

  php bin/console assetic:dump --watch --env=dev  # Watch for changes
  

• Validate Config:

  php bin/console debug:config assetic
  

• Log Filter Errors: Enable debug mode in config/packages/devlabs91_assetic.yaml:

  debug: true
  

Extension Points

1. Event Listeners:

   • Subscribe to assetic assets:load or assetic assets:dump events for custom logic.
   • Example:

     // src/EventListener/AsseticListener.php
     public function onAssetsLoad(AssetsEvent $event) {
         $event->getAssets()->add('custom_asset', new Asset(...));
     }
     

2. Custom Asset Classes:

   • Extend Assetic\Asset\Asset for specialized assets (e.g., remote files).

3. Asset Loader Integration:

   • Override Devlabs91\AsseticBundle\Loader\AssetLoader to modify asset resolution.

Performance Notes

• Disable in Dev: Set assetic.use_controller: false in dev environments to avoid recompilation on every request.
• Precompile Assets: Use assetic:dump in CI/CD pipelines for production builds.