Assetic Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require anaxago/assetic
   

   Add the service provider to config/app.php:

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

2. Basic Configuration Publish the config file:

   php artisan vendor:publish --provider="Anaxago\Assetic\AsseticServiceProvider"
   

   Edit config/assetic.php to define asset directories (e.g., css, js, images).

3. First Use Case: Compiling CSS Define a build task in app/Assetic/BuildTasks/CssBuildTask.php:

   namespace App\Assetic\BuildTasks;
   
   use Anaxago\Assetic\BuildTask;
   
   class CssBuildTask extends BuildTask
   {
       protected $input = 'public/css/source/*.css';
       protected $output = 'public/css/compiled';
       protected $filters = ['cssrewrite', 'yui_css'];
   }
   

   Register the task in config/assetic.php:

   'build_tasks' => [
       App\Assetic\BuildTasks\CssBuildTask::class,
   ],
   

   Run the build:

   php artisan assetic:build
   

Implementation Patterns

Workflows

1. Asset Organization

   • Group assets by type (e.g., resources/assets/css/, resources/assets/js/).
   • Use Laravel’s mix-manifest.json (if migrating from Laravel Mix) as a reference for input/output paths.

2. Filter Chains Combine filters for optimization:

   protected $filters = [
       'cssrewrite', // Rewrite URLs in CSS
       'yui_css',    // Compress CSS
       'uglifyjs',   // Minify JS (if applicable)
   ];
   

3. Dynamic Asset Loading Use Blade directives to inject compiled assets:

   @asset('css/compiled/style.css')
   

   Define the directive in app/Providers/AppServiceProvider.php:

   Blade::directive('asset', function ($path) {
       return "<?php echo asset('{$path}'); ?>";
   });
   

4. Environment-Specific Builds Override config per environment (e.g., config/assetic.local.php):

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

5. Watch Mode for Development Use Artisan to watch files and auto-rebuild:

   php artisan assetic:watch
   

Integration Tips

• Laravel Mix Migration: Replace mix-manifest.json logic with Assetic’s asset() helper.
• Vite/Webpack Alternatives: Use Assetic for static sites or legacy projects where JS bundlers are overkill.
• CDN Support: Configure asset() helper to point to CDN URLs in production.

Gotchas and Tips

Pitfalls

1. Caching Issues

   • Clear compiled assets after config changes:

     php artisan assetic:clear
     

   • Ensure debug: false in production to avoid recompiling on every request.

2. Filter Order Matters

   • Run cssrewrite before compression (yui_css) to avoid broken URLs in minified output.

3. File Permissions

   • Ensure the storage/ and public/ directories are writable by the web server.

4. Missing Dependencies

   • Install required PHP extensions (e.g., php-yaml for YAML-based configs) or Node.js tools (e.g., uglify-js) if using JS filters.

Debugging

• Verbose Output: Run builds with -v for details:

  php artisan assetic:build -v
  

• Dry Runs: Test filters without writing files:

  $this->dryRun = true; // In BuildTask
  

Extension Points

1. Custom Filters Extend Assetic’s filter system by creating a custom filter class:

   namespace App\Assetic\Filters;
   
   use Anaxago\Assetic\Filter\FilterInterface;
   
   class CustomFilter implements FilterInterface {
       public function filter($content) {
           return str_replace('foo', 'bar', $content);
       }
   }
   

   Register it in config/assetic.php:

   'filters' => [
       'custom' => App\Assetic\Filters\CustomFilter::class,
   ],
   

2. Pre/Post-Build Hooks Use Laravel’s events to trigger actions before/after builds:

   // In AppServiceProvider::boot()
   event(new AsseticBuilding());
   

3. Asset Versioning Manually append query strings for cache busting:

   @asset("css/compiled/style.css?v={$assetVersion}")