Terrific Composer Bundle Laravel Package

Getting Started

Minimal Setup

1. Prerequisite: Install TerrificCoreBundle first—this bundle depends on it.

   composer require brunschgi/terrific-core-bundle
   

   Follow its installation instructions.

2. Add the Bundle:

   composer require brunschgi/terrific-composer-bundle:1.0.*
   

   Register it in AppKernel.php:

   new Terrific\ComposerBundle\TerrificComposerBundle(),
   

3. First Use Case:

   • Asset Management: Use the bundle’s terrific_composer Twig extension to render frontend assets (JS/CSS) with versioning and fingerprinting.

     {{ terrific_composer('assets/app.js') }}
     

   • Dependency Resolution: Leverage the bundle’s ComposerLoader to resolve frontend dependencies (e.g., npm packages) in Laravel’s asset pipeline.

Implementation Patterns

1. Asset Pipeline Integration

• Workflow:

  • Place frontend assets (e.g., app.js, styles.css) in web/assets/ (or configure a custom path in config/terrific_composer.yml).
  • Use Twig to render assets with versioning:

    <script src="{{ terrific_composer('assets/app.js', { version: true }) }}"></script>
    

  • Versioning: Append a hash (e.g., app.js?v=abc123) to bust caches. Configure in config/terrific_composer.yml:

    terrific_composer:
        versioning: true
        fingerprint: true
    

• Integration with Laravel Mix:

  • If using Laravel Mix, ensure the bundle’s ComposerLoader is called after Mix processes assets. Override the TerrificComposerBundle’s build event in EventServiceProvider:

    protected $listen = [
        'terrific.composer.build' => [
            \Terrific\ComposerBundle\EventListener\BuildAssetsListener::class,
        ],
    ];
    

2. Dependency Management

• npm/Bower Integration:

  • The bundle assumes frontend dependencies (e.g., node_modules/) are managed externally. Use it to map these dependencies to Laravel’s public path:

    # config/terrific_composer.yml
    terrific_composer:
        dependencies:
            jquery: node_modules/jquery/dist/jquery.min.js
    

  • Render dependencies in Twig:

    {{ terrific_composer('jquery') }}
    

• Custom Loaders:

  • Extend the ComposerLoader to support custom asset sources (e.g., S3, CDNs). Override the load() method in a service:

    use Terrific\ComposerBundle\Loader\ComposerLoaderInterface;
    
    class CustomComposerLoader implements ComposerLoaderInterface {
        public function load($asset) {
            // Custom logic (e.g., fetch from S3)
            return asset("https://cdn.example.com/{$asset}");
        }
    }
    

  • Bind it in services.yml:

    services:
        terrific_composer.loader:
            class: AppBundle\Service\CustomComposerLoader
    

3. Twig Extensions

• Dynamic Asset Rendering:
  • Use the terrific_composer Twig function to render assets conditionally:

    {% if is_dev %}
        {{ terrific_composer('assets/app.js', { debug: true }) }}
    {% else %}
        {{ terrific_composer('assets/app.min.js') }}
    {% endif %}
    

  • Filters: Apply filters (e.g., minify) to assets:

    {{ terrific_composer('assets/app.js')|minify }}
    

Gotchas and Tips

Pitfalls

1. Outdated Dependencies:

   • The bundle was last updated in 2016 and depends on TerrificCoreBundle. Test thoroughly for compatibility with modern Laravel (8+/9+) and Symfony components.
   • Workaround: Fork the repository and update dependencies (e.g., symfony/twig-bridge, symfony/asset).

2. Asset Path Conflicts:

   • If assets are also managed by Laravel Mix or Vite, ensure paths in terrific_composer.yml do not overlap with Laravel’s public/ directory. Use absolute paths:

     terrific_composer:
         base_path: '%kernel.project_dir%/web/assets'
     

3. Caching Issues:

   • Versioned assets may not update if the bundle’s cache is stale. Clear Laravel’s cache and the bundle’s cache:

     php artisan cache:clear
     php artisan config:clear
     

Debugging Tips

• Enable Debug Mode:

  • Set debug: true in terrific_composer.yml to log asset resolution:

    terrific_composer:
        debug: true
    

  • Check Laravel logs (storage/logs/laravel.log) for TerrificComposerBundle entries.

• Asset Not Found:

  • Verify the asset exists at the configured base_path. Use the terrific_composer:debug command (if available) or dump the loader:

    $loader = $this->get('terrific_composer.loader');
    dump($loader->load('assets/app.js'));
    

Extension Points

1. Custom Asset Processors:

   • Extend the AssetProcessor interface to add pre/post-processing (e.g., UglifyJS, PostCSS):

     use Terrific\ComposerBundle\Processor\AssetProcessorInterface;
     
     class CustomAssetProcessor implements AssetProcessorInterface {
         public function process($asset) {
             // Custom logic (e.g., minify)
             return str_replace(' ', '', $asset);
         }
     }
     

   • Register it in services.yml:

     services:
         terrific_composer.processor:
             class: AppBundle\Processor\CustomAssetProcessor
             tags: ['terrific_composer.processor']
     

2. Event Listeners:

   • Hook into the bundle’s events (e.g., terrific.composer.build) to modify asset behavior:

     use Symfony\Component\EventDispatcher\EventSubscriberInterface;
     
     class CustomSubscriber implements EventSubscriberInterface {
         public static function getSubscribedEvents() {
             return [
                 'terrific.composer.build' => 'onBuild',
             ];
         }
     
         public function onBuild(BuildEvent $event) {
             $event->setAsset($event->getAsset() . '?custom=param');
         }
     }
     

3. Configuration Overrides:

   • Override the default config in config/packages/terrific_composer.yml:

     terrific_composer:
         versioning: false
         fingerprint_algorithm: 'md5' # Default is 'crc32'