Assetic Importer Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require apnet/assetic-importer-bundle
   

   Add the bundle to AppKernel.php:

   $bundles[] = new Apnet\AsseticImporterBundle\ApnetAsseticImporterBundle();
   

2. Basic Configuration (config.yml):

   apnet_assetic_importer:
       assets:
           my_css:
               source: %kernel.root_dir%/Resources/public/css
               target: my_assets
   

   Run asset dump:

   php bin/console assetic:dump
   

3. First Use Case: Access files via Twig:

   <link href="{{ imported_asset('my_assets/style.css') }}" rel="stylesheet">
   

Implementation Patterns

Workflows

1. Static Asset Integration:

   • Use source to point to a directory (e.g., app/Resources/public/css).
   • Reference files in Twig with imported_asset('target/filename').
   • Example: Serve a custom CSS file from a non-standard location.

2. Dynamic Asset Compilation (Compass/Sass):

   • Configure importer: compass and point source to config.rb.
   • Enable watcher in config_dev.yml for live reloading:

     apnet_assetic_watcher:
         enabled: true
         compiler_root: %kernel.root_dir%/Resources
     

   • Access generated files via imported_asset('target/generated.css').

3. Environment-Specific Routing:

   • Use target to namespace assets (e.g., vendor_assets).
   • Exclude cssrewrite filter for non-public bundles (e.g., @VendorBundle).

Integration Tips

• Symfony 3/4/5: Works with Assetic 2.x/3.x (check composer.json constraints).
• Twig Extensions: Override imported_asset in your Twig environment if needed:

  $twig->addFunction(new \Twig_SimpleFunction('imported_asset', [$this->get('apnet_assetic_importer.twig.asset_url_generator'), 'generate']));
  

• Asset Versioning: Append ?v=1.0 to URLs for cache busting (handled by Assetic).

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • Ensure Apache/Nginx user has write access to compass_dir/stylesheets for live reloading.
   • Debug with chmod -R 775 on the target directory.

2. Assetic Dump Required:

   • Forgetting php bin/console assetic:dump after config changes will break asset access.
   • Add a post-install script to composer.json:

     "scripts": {
         "post-install-cmd": ["assetic:dump"]
     }
     

3. CSS Rewrite Conflicts:

   • If using @Bundle syntax in CSS, disable cssrewrite filter in config.yml:

     assetic:
         filters:
             cssrewrite: ~
     

4. Watcher Bundle:

   • Only enable AsseticWatcherBundle in dev (it’s disabled by default).
   • Conflicts with other watchers (e.g., Laravel Mix) if not properly scoped.

Debugging

• Asset Not Found?:

  • Verify source paths are correct (use absolute paths with %kernel.root_dir%).
  • Check var/cache/dev for generated asset manifests.
  • Run php bin/console debug:assetic to list available assets.

• Compass Errors:

  • Ensure config.rb is valid and dependencies (e.g., compass) are installed globally.
  • Test Compass manually: compass compile path/to/config.rb.

Extension Points

1. Custom Importers:

   • Extend Apnet\AsseticImporterBundle\Importer\ImporterInterface for new build tools (e.g., PostCSS).
   • Register in services.yml:

     services:
         my_custom_importer:
             class: AppBundle\Importer\MyImporter
             tags:
                 - { name: apnet_assetic_importer.importer, alias: my_importer }
     

2. Asset URL Generation:

   • Override the Twig function or extend Apnet\AsseticImporterBundle\Twig\AssetUrlGenerator.

3. Cache Invalidation:

   • Clear cache after config changes:

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