Assets Extra Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require checkdomain/assets-extra-bundle:dev-master
   

   Register the bundle in app/AppKernel.php:

   new Checkdomain\AssetsExtraBundle\CheckdomainAssetsExtraBundle(),
   

2. First Use Case: Enable logical file names in Twig templates by configuring the bundle to override the default bundles directory. Update config.yml:

   checkdomain_assets_extra:
       assets_dir: "%kernel.root_dir%/../web/assets"  # Custom assets directory
       encrypt_bundle_names: true                    # Optional: Encrypt bundle names in paths
   

   Now reference assets logically in Twig:

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

Implementation Patterns

Core Workflows

1. Asset Directory Customization:

   • Override the default bundles/ directory by setting assets_dir in config. Useful for shared assets across projects.
   • Example: Move all static assets to web/assets for easier deployment.

2. Bundle Name Encryption:

   • Enable encrypt_bundle_names to obfuscate bundle names in asset paths (security through obscurity).
   • Useful for hiding internal bundle structures from end-users.

3. Assetic Integration:

   • Extends Assetic’s CssRewriteFilter to fix path resolution for logical file names.
   • Configure in config.yml:

     assetic:
         filters:
             cssrewrite: ~  # Automatically fixed by the bundle
     

4. Twig asset() Function:

   • Supports logical file names out-of-the-box. No need for manual path adjustments in templates.

Integration Tips

• Symfony 2.x Compatibility: Tested only on Symfony 2.0–2.7. For newer versions, patch or fork the bundle.
• Assetic Pipelines: Ensure CssRewriteFilter is applied after asset() processing in Assetic configs to avoid path conflicts.
• Debug Mode: Disable encryption in dev environments for easier debugging:

  checkdomain_assets_extra:
      encrypt_bundle_names: "%kernel.debug% ? false : true"
  

Gotchas and Tips

Pitfalls

1. Deprecated Symfony 2:

   • The bundle is archived and may break with Symfony 3+ or newer Assetic versions. Expect manual fixes.
   • Workaround: Fork the repo and update dependencies (e.g., symfony/framework-bundle).

2. Assetic Path Resolution Bug:

   • If CssRewriteFilter fails, ensure:
     • The assets_dir config points to the root of your assets (not a subdirectory).
     • Assetic’s use_controller is set to false in config.yml:

       assetic:
           use_controller: false
       

3. Twig Caching:

   • Clear Twig cache after changing assets_dir or encryption settings:

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

4. Logical File Names Limitation:

   • Only works for assets inside the configured assets_dir. External assets (e.g., CDN) require manual paths.

Debugging Tips

• Verify Config: Check if the bundle is loaded by dumping kernel bundles:

  // app/AppKernel.php
  dump(array_keys($this->getBundles()));
  

  Look for CheckdomainAssetsExtraBundle.

• Asset Paths: Debug Twig’s asset() output with:

  {{ dump(asset('css/styles.css')) }}
  

  Ensure paths resolve correctly.

• Assetic Logs: Enable Assetic debug mode in config.yml:

  assetic:
      debug: "%kernel.debug%"
  

  Check logs for CssRewriteFilter errors.

Extension Points

1. Custom Filters: Extend the bundle by creating a custom Assetic filter that inherits from Checkdomain\AssetsExtraBundle\Twig\Extension\AssetExtension.

2. Dynamic Asset Directories: Override the getAssetsDir() method in a service to fetch assets_dir dynamically (e.g., from environment variables).

3. Encryption Logic: Modify the encryption algorithm by extending the Checkdomain\AssetsExtraBundle\DependencyInjection\Configuration class.