Assetic Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require apelaez-link/assetic-bundle
   

   Ensure your composer.json includes the apelaez-link/assetic package (required dependency).

2. Enable the Bundle: Add to config/bundles.php:

   ApelaezLink\AsseticBundle\ApelaezLinkAsseticBundle::class => ['all' => true],
   

3. Basic Configuration: Create config/packages/assetic.yaml (Symfony 4+) or add to app/config/config.yml (Symfony 2/3):

   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: [jsqueeze]
   

4. First Use Case:

   • Dump assets once during development:

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

   • Reference in Twig:

     <link rel="stylesheet" href="{{ asset('build/css/app_css.css') }}">
     

Implementation Patterns

Workflows

1. Development vs. Production:

   • Use assetic:dump in dev for live-reload testing.
   • Disable dumping in prod and rely on web server caching (e.g., Nginx try_files or Symfony’s AssetMapper).

2. Dynamic Asset Management:

   • Input Patterns: Use globs for multiple files:

     inputs:
         - '%kernel.project_dir%/assets/css/**/*.css'
     

   • Environment-Specific Assets: Leverage Symfony’s %kernel.environment%:

     inputs:
         {% if app.environment == 'prod' %}
         - '%kernel.project_dir%/assets/css/prod.css'
         {% else %}
         - '%kernel.project_dir%/assets/css/dev.css'
         {% endif %}
     

3. Filter Chains:

   • Combine filters for multi-step processing:

     filters:
         - 'cssrewrite'
         - 'yui_css'
         - 'uglifyjs'
     

   • Custom Filters: Extend via AsseticBundle's assetic.filter service tag.

4. Versioning:

   • Append a hash to filenames for cache busting:

     <link rel="stylesheet" href="{{ asset('build/css/app_css.css')|replace({'~': ''}) }}">
     

     Configure in assetic.yaml:

     use_controller: true  # Auto-generates unique filenames
     

Integration Tips

• Symfony Flex: If using Symfony 4+, manually register the bundle in config/bundles.php (no autoloading).
• Webpack Encore: For modern workflows, prefer Encore for JS/CSS but use Assetic for legacy Symfony 2/3 projects.
• Twig Extensions: Access assets via {{ asset() }} or {{ asset_url() }} in templates.
• Debugging: Enable debug mode in assetic.yaml:

  debug: true  # Outputs unprocessed assets in dev
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony Versions:

   • The bundle supports Symfony 2.3–4.0 but lacks updates. Test thoroughly with your version.
   • Fix: Pin symfony/* dependencies explicitly in composer.json.

2. Missing apelaez-link/assetic:

   • The bundle depends on a forked Assetic library. Ensure it’s installed:

     composer require apelaez-link/assetic:^1.6
     

   • Debug: Check vendor/apelaez-link/assetic exists after composer install.

3. Asset Dumping in CI:

   • Avoid running assetic:dump in CI/CD pipelines (use build tools like Webpack instead).
   • Tip: Add to .gitignore:

     /var/cache/dev/
     /public/build/
     

4. Filter Conflicts:

   • Some filters (e.g., uglifyjs) may require PHP extensions (e.g., php-uglify).
   • Debug: Check php bin/console debug:config assetic for filter errors.

5. Twig Caching:

   • Clear Twig cache after changing asset configurations:

     php bin/console cache:clear
     

Debugging

• Verbose Output:

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

• Log Filters: Enable logging in config/packages/monolog.yaml:

  handlers:
      assetic:
          type: stream
          path: "%kernel.logs_dir%/assetic.log"
          level: debug
  

Extension Points

1. Custom Filters:

   • Create a service tagged as assetic.filter:

     # config/services.yaml
     services:
         App\Filter\CustomFilter:
             tags:
                 - { name: assetic.filter, alias: custom_filter }
     

   • Implement Assetic\Filter\FilterInterface.

2. Asset Loaders:

   • Extend AsseticBundle\Loader\LoaderInterface for dynamic asset discovery.

3. Configuration Overrides:

   • Use assetic.yaml parameters to override defaults:

     parameters:
         assetic.read_from: '@assetic.reader'
         assetic.write_to: '%kernel.project_dir%/public/build'
     

Performance Tips

• Exclude Node Modules: Configure inputs to avoid processing node_modules:

  inputs:
      - '%kernel.project_dir%/assets/css/src/**/*.css'
      - '!%kernel.project_dir%/assets/css/src/node_modules/**'
  

• Precompile in Dev: Use assetic:watch for real-time updates:

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