Assetic Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require kriswallsmith/assetic:^1.4.0

Add to composer.json under autoload-dev:

"autoload-dev": {
    "files": ["vendor/kriswallsmith/assetic/src/Assetic/Extension.php"]
}

2. Basic Configuration: Create config/assetic.php (or publish with):

   php artisan config:publish --provider="Assetic\Bundle\AsseticBundle\AsseticBundle"
   

   Define a simple asset dump command:

   'commands' => [
       'app:assets' => [
           'dump' => true,
           'watch' => false,
           'verbose' => true,
       ],
   ],
   

3. First Use Case: Define a basic asset with Sass support:

   'assets' => [
       'app_css' => [
           'inputs' => [
               'resources/scss/app.scss',
               'public/css/vendor.css',
           ],
           'output' => 'public/build/css/app.css',
           'filters' => ['sassphp', 'cssrewrite'],
       ],
   ],
   

   Run the dump command:

   php artisan assetic:dump --env=production
   

Implementation Patterns

Workflows

1. Sass Integration: Use the new sassphp filter for Libsass-based Sass compilation:

   'assets' => [
       'admin_scss' => [
           'inputs' => ['resources/scss/admin.scss'],
           'output' => 'public/build/admin.css',
           'filters' => ['sassphp' => ['style' => 'compressed']],
       ],
   ],
   

   Note: Requires league/sass-php (composer require league/sass-php).

2. Asset Grouping: Organize assets by feature with environment-specific filters:

   'assets' => [
       'frontend' => [
           'inputs' => ['public/js/*.js', 'public/css/*.css'],
           'output' => 'public/build/all.js',
           'filters' => config('app.env') === 'production' ? ['uglifyjs', 'cssmin'] : [],
       ],
   ],
   

3. Dynamic Asset Loading: Load assets conditionally in Blade:

   @foreach (Config::get('assetic.assets') as $name => $asset)
       @if ($asset['enabled'] ?? true)
           @if (str_contains($asset['output'], '.css'))
               <link rel="stylesheet" href="{{ $asset['output'] }}">
           @endif
       @endif
   @endforeach
   

4. Filter Chaining: Chain filters for complex pipelines (e.g., Sass → CSS minification):

   'filters' => [
       'sassphp' => ['style' => 'expanded'],
       'cssrewrite',
       'cssmin',
   ],
   

Integration Tips

• Legacy Sass Support: The sassphp filter replaces deprecated Twig-based Sass filters.
• Hybrid Workflows: Combine with Laravel Mix for modern JS/TS while using Assetic for Sass/CSS.
• Custom Filter Options: Pass options to filters (e.g., sassphp):

  'filters' => [
      'sassphp' => [
          'style' => 'compressed',
          'precision' => 10,
      ],
  ],
  

Gotchas and Tips

Pitfalls

1. Twig Deprecation:

   • Breaking: APIs deprecated in Twig 1.27 may cause issues if using custom Twig-based filters.
   • Fix: Migrate to native Assetic filters (e.g., sassphp instead of Twig-based Sass).

2. Sassphp Dependency:

   • The sassphp filter requires league/sass-php (≥v1.0.0).
   • Debug: Install missing dependencies:

     composer require league/sass-php
     

3. Cache Invalidation:

   • Clear cache explicitly after Sass filter changes:

     php artisan assetic:dump --clear
     

4. Path Resolution:

   • Ensure inputs paths are correct (e.g., resources/scss/ vs. public/css/).
   • Tip: Use Laravel’s helpers:

     'inputs' => [resource_path('scss/app.scss')],
     

Debugging

• Dry Run: Test Sass compilation without writing files:

  php artisan assetic:dump --dry-run
  

• Verbose Output: Inspect filter execution:

  php artisan assetic:dump --verbose
  

• Filter-Specific Errors: Check Sassphp logs if sassphp fails:

  php artisan assetic:dump --verbose | grep -i sass
  

Extension Points

1. Custom Sass Options: Extend sassphp filter options:

   'filters' => [
       'sassphp' => [
           'style' => 'compressed',
           'include_paths' => [resource_path('scss')],
       ],
   ],
   

2. Asset Loaders: Override default asset loading (e.g., for remote files):

   $loader = new \Assetic\Asset\AssetLoader();
   $loader->set('https://cdn.example.com/', new \Assetic\Asset\FtpAssetReader());
   

3. Event Listeners: Hook into Assetic’s lifecycle (if using AsseticBundle):

   // Example: Log asset dump events
   $dispatcher->addListener(AsseticEvents::ON_DUMP, function ($event) {
       \Log::info('Asset dumped: ' . $event->getAsset()->getTargetPath());
   });
   

Performance Tips

• Disable in Dev: Set 'enabled': false in assetic.php for local environments.
• Parallel Dumping: Use --jobs=N for multi-core compilation (if supported):

  php artisan assetic:dump --jobs=4
  

• Exclude Files: Skip minified files in glob patterns:

  'inputs' => [
      'public/css/*.css',
      '!public/css/*.min.css',
  ],
  

NO_UPDATE_NEEDED would not apply here due to the new `sassphp` filter and Twig deprecation handling.