Assetic Bundle Laravel Package

## Getting Started

### Minimal Setup
1. **Installation** (if still needed for legacy projects):
   ```bash
   composer require anaxago/assetic-bundle

(Note: This is deprecated; use Webpack Encore for new projects.)

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

   return [
       // ...
       Anaxago\AsseticBundle\AsseticBundle::class => ['all' => true],
   ];
   

3. Configure Assetic (in config/packages/assetic.yaml):

   assetic:
       assets:
           app_css:
               inputs:
                   - '%kernel.project_dir%/assets/css/style.css'
               filters: [cssrewrite, yui_css]
           app_js:
               inputs:
                   - '%kernel.project_dir%/assets/js/app.js'
               filters: [uglifyjs]
   

4. Dump Assets (via CLI):

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

First Use Case

• Legacy Project Migration: If maintaining an old Symfony 2/3/4.x app, use this to:
  • Minify/concat CSS/JS files.
  • Apply filters (e.g., uglifyjs, yui_css).
  • Generate versioned filenames (e.g., app_123abc.css).

Implementation Patterns

Core Workflows

1. Asset Definition:

   • Define assets in config/packages/assetic.yaml under assetic.assets.
   • Example: Group related files (e.g., admin_css, vendor_js).

2. Filter Chaining:

   • Apply filters sequentially (e.g., cssrewrite → yui_css).
   • Common filters:
     • CSS: cssrewrite, yui_css, lessphp.
     • JS: uglifyjs, closure.
     • Images: imagemin.

3. Environment-Specific Config:

   • Use %kernel.environment% to toggle filters (e.g., disable uglifyjs in dev):

     filters:
         uglifyjs:
             bin: '%env(UGLIFYJS_BIN)%'
             apply_to: '%kernel.environment% == "prod" ? "js" : null'
     

4. Twig Integration:

   • Embed assets in templates:

     {{ asset('bundles/assetic/app_css') }}
     

   • Use assetic_add_filter for dynamic filters.

5. CLI Automation:

   • Dump assets on deploy:

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

   • Clear cache before dumping:

     php bin/console cache:clear && php bin/console assetic:dump
     

Integration Tips

• Symfony Flex: If using Symfony 4+, ensure assetic.yaml is auto-loaded via Flex recipes.
• Custom Filters: Extend Assetic\Filter\FilterInterface and register in config:

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

• Debugging: Use --dump flag to inspect generated assets:

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

Gotchas and Tips

Pitfalls

1. Deprecation Warning:

   • This bundle is deprecated for new projects. Migrate to Webpack Encore.
   • Symptoms: Warnings in Symfony 4.4+ about AsseticBundle being obsolete.

2. Filter Compatibility:

   • Some filters (e.g., yui_css) may require external binaries (e.g., yui-compressor).
   • Fix: Install dependencies (e.g., npm install -g yui-compressor) or use PHP alternatives (e.g., league/league-yui-compressor).

3. Caching Issues:

   • Assets may not update if cache isn’t cleared:

     php bin/console cache:clear
     php bin/console assetic:dump --force
     

   • Tip: Use --watch in development to auto-rebuild on changes.

4. Twig Template Caching:

   • Twig’s cache may serve stale asset paths. Clear Twig cache separately:

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

5. Symfony 4.4+ Quirks:

   • Some configurations may break due to Symfony’s DI changes.
   • Workaround: Pin anaxago/assetic to ~4.4 and update symfony/dependency-injection to ~4.0.

Debugging Tips

1. Verbose Output:

   • Use --verbose to see filter execution:

     php bin/console assetic:dump --verbose
     

2. Dry Runs:

   • Test configurations without writing files:

     php bin/console assetic:dump --dry-run
     

3. Log Filter Errors:

   • Enable debug mode to log filter failures:

     assetic:
         debug: true
     

Extension Points

1. Custom Asset Loaders:

   • Implement Assetic\Asset\AssetLoaderInterface for dynamic asset resolution (e.g., from a database).

2. Event Listeners:

   • Subscribe to assetic.asset.dump events to modify assets pre-dump:

     // src/EventListener/AsseticListener.php
     public function onDump(AsseticEvent $event) {
         $asset = $event->getAsset();
         $asset->addFilter(new CustomFilter());
     }
     

3. Environment Variables:

   • Dynamically configure filters via .env:

     filters:
         uglifyjs:
             bin: '%env(UGLIFYJS_PATH)%'
     

4. Asset Versioning:

   • Override AsseticBundle\Twig\Extension\AsseticExtension to customize versioning logic (e.g., Git hash-based).

Pro Tips

• Legacy Migration:
  • Use symfony/asset as a stopgap for simple cases before full Webpack Encore migration.
• Performance:
  • Prefer uglifyjs over closure for JS minification (faster in most cases).
  • Use cssrewrite to optimize CSS asset loading.
• Testing:
  • Mock Assetic\Factory\AssetFactory in PHPUnit for isolated tests:

    $factory = $this->createMock(AssetFactory::class);
    $factory->method('createAsset')->willReturn(new Asset('test.css'));
    

*(Note: While this package is deprecated, the patterns below remain relevant for understanding Assetic’s core functionality, which may still be useful in legacy systems or as a reference for modern asset pipelines like Webpack Encore.)*