Asset Management Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation Add the bundle to your composer.json:

   composer require smoya/asset-management-bundle
   

   Enable it in config/bundles.php:

   return [
       // ...
       Smoya\AssetManagementBundle\SmoyaAssetManagementBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console smoya:asset-management:install
   

   Edit config/packages/smoya_asset_management.yaml to define your asset groups (e.g., vendor, app, admin).

3. First Use Case Define an asset group in Twig:

   {% asset_group 'app' %}
       <!-- Include CSS/JS here -->
       {{ asset('css/app.css') }}
       {{ asset('js/app.js') }}
   {% endasset_group %}
   

   The bundle auto-generates a unique hash for the group and bundles assets with Assetic.

Implementation Patterns

Asset Grouping Workflow

1. Define Groups Use asset_group in Twig to scope assets (e.g., frontend, backend, third-party):

   {% asset_group 'frontend' %}
       {{ asset('css/bootstrap.min.css') }}
       {{ asset('js/main.js') }}
   {% endasset_group %}
   

2. Dynamic Grouping Pass variables to Twig for conditional inclusion:

   {% if is_admin() %}
       {% asset_group 'admin' %}
           {{ asset('css/admin.css') }}
       {% endasset_group %}
   {% endif %}
   

3. Integration with Assetic Configure assetic.yaml to process grouped assets:

   assets:
       app_css:
           inputs:
               - '%kernel.project_dir%/assets/css/app.css'
           filters: [cssrewrite, yui_css]
   

   Reference the group in Twig:

   {{ asset_group('app_css')|assetic_filter }}
   

Performance Optimization

• Cache Busting: Leverage the bundle’s auto-hashing for cache invalidation.

  <link href="{{ path(asset_group('app'), {'hash': true}) }}" rel="stylesheet">
  

• Environment-Specific Groups: Use Symfony’s %kernel.environment% to toggle groups:

  # config/packages/smoya_asset_management.yaml
  groups:
      app:
          enabled: ['dev', 'prod']
  

Extending Functionality

• Custom Filters: Add Assetic filters to group-specific assets:

  {% asset_group 'app' %}
      {{ asset('js/vendor.js')|assetic_filter('uglifyjs') }}
  {% endasset_group %}
  

• Preload Assets: Use the asset_group_preload Twig function for critical resources:

  {% asset_group_preload 'app' %}
  

Gotchas and Tips

Common Pitfalls

1. Missing Config

   • Error: No asset groups defined.
   • Fix: Run php bin/console smoya:asset-management:install and verify config/packages/smoya_asset_management.yaml.

2. Assetic Not Processed

   • Error: Assets render as raw paths (e.g., /assets/css/app.css).
   • Fix: Ensure assetic:dump is run in dev environment:

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

3. Group Name Collisions

   • Error: Duplicate group names cause unexpected bundling.
   • Fix: Use unique, descriptive names (e.g., frontend_v2, admin_dashboard).

Debugging Tips

• Check Generated Output Dump the rendered group to debug:

  {{ dump(asset_group('app')) }}
  

• Clear Cache After config changes, clear Symfony’s cache:

  php bin/console cache:clear
  

Configuration Quirks

• Environment Overrides Disable groups per environment in smoya_asset_management.yaml:

  groups:
      analytics:
          enabled: ['prod']
  

• Asset Paths Use absolute paths in asset() calls to avoid resolution issues:

  {{ asset('@assets/css/app.css') }}  {# Webpack Encore style #}
  

Extension Points

1. Custom Asset Group Logic Override the bundle’s AssetGroupManager to add logic (e.g., dynamic group names):

   // src/SmoyaAssetManagement/AssetGroupManager.php
   class CustomAssetGroupManager extends \Smoya\AssetManagementBundle\AssetGroupManager
   {
       public function getGroupName($name) {
           return 'custom_' . $name;
       }
   }
   

   Register the service in services.yaml:

   Smoya\AssetManagementBundle\AssetGroupManager: '@custom_asset_group_manager'
   

2. Twig Extensions Extend the Twig environment to add custom functions:

   // src/Twig/AppExtension.php
   class AppExtension extends \Twig\Extension\AbstractExtension
   {
       public function getFunctions() {
           return [
               new \Twig\TwigFunction('custom_asset_group', [$this->manager, 'renderGroup']),
           ];
       }
   }