Assetic Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation

   composer require devlabs91/assetic
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Devlabs91\Assetic\AsseticServiceProvider::class,
   ],
   

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="Devlabs91\Assetic\AsseticServiceProvider" --tag="config"
   

   Edit config/assetic.php to define your asset paths, filters, and bundles.

3. First Use Case: Compiling a Bundle Define a bundle in a controller or service:

   use Devlabs91\Assetic\Bundle\BundleInterface;
   use Devlabs91\Assetic\Bundle\AssetCollection;
   
   $bundle = new AssetCollection('app');
   $bundle->add('css/style.css');
   $bundle->add('js/main.js');
   
   $output = $bundle->dump();
   file_put_contents(public_path('assets/compiled.css'), $output);
   

Implementation Patterns

Workflows

1. Asset Organization

   • Group assets by feature (e.g., admin, frontend) using named bundles.
   • Example:

     $adminBundle = new AssetCollection('admin');
     $adminBundle->add('/css/admin/dashboard.css');
     $adminBundle->add('/js/admin/utils.js');
     

2. Filter Chains

   • Apply filters sequentially (e.g., CSS minification + fingerprinting):

     $bundle = new AssetCollection('app');
     $bundle->add('css/app.css')
            ->setTarget('css/compiled.css')
            ->setFilters([
                'cssrewrite', // Rewrite URLs in CSS
                'cssmin',    // Minify CSS
                'timestamp', // Add fingerprint
            ]);
     

3. Dynamic Asset Loading

   • Use middleware to inject bundles into views:

     // In a middleware
     $view->share('appAssets', $this->assetic->getBundle('app')->getUrl());
     

4. Versioning & Cache Busting

   • Leverage the timestamp filter for automatic cache busting:

     $bundle->setFilters(['timestamp']);
     echo $bundle->getUrl(); // Outputs: /assets/compiled.css?v=123456789
     

Integration Tips

• Laravel Mix/Vite Compatibility: Use Assetic for PHP-based preprocessing (e.g., SASS via php-sass) before handing off to JS tools.
• Blade Directives: Create a custom Blade directive for bundles:

  Blade::directive('assets', function ($expression) {
      return "<?php echo app('assetic')->getBundle({$expression})->getUrl(); ?>";
  });
  

  Usage:

  <link rel="stylesheet" href="{{ assets('app') }}">
  

Gotchas and Tips

Pitfalls

1. Filter Order Matters

   • Filters like cssrewrite must run before cssmin to avoid broken paths in minified output.
   • Example of incorrect order:

     $bundle->setFilters(['cssmin', 'cssrewrite']); // ❌ Broken paths
     

2. File Permissions

   • Ensure the storage/app/assetic directory is writable:

     mkdir -p storage/app/assetic && chmod -R 775 storage/app/assetic
     

3. Circular Dependencies

   • Avoid circular references in @import (CSS) or require (JS) statements—Assetic may hang or fail silently.

4. Missing Filters

   • If a filter (e.g., uglifyjs) is missing, install it via Composer:

     composer require assetic/uglifyjs-filter
     

Debugging

• Enable Verbose Output Set debug: true in config/assetic.php to log filter execution:

  'debug' => env('APP_DEBUG', false),
  

• Check Compiled Output Inspect storage/app/assetic for intermediate files to debug filter failures.

Extension Points

1. Custom Filters Create a filter class and register it in config/assetic.php:

   'filters' => [
       'my_custom_filter' => \App\Filters\MyCustomFilter::class,
   ],
   

2. Bundle Events Listen for bundle compilation events:

   Assetic::getDispatcher()->addListener('bundle.compile', function ($event) {
       // Log or modify bundle before compilation
   });
   

3. Asset Fingerprinting Override the default timestamp format in config:

   'timestamp_format' => 'md5', // Use MD5 hashes instead of Unix timestamps