Minify Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require matthiasmullie/minify
   

2. Basic Usage (CSS):

   use MatthiasMullie\Minify\CSS;
   
   $minifier = new CSS(public_path('css/styles.css'));
   $minifier->minify(public_path('css/minified.css'));
   

3. Basic Usage (JS):

   use MatthiasMullie\Minify\JS;
   
   $minifier = new JS(public_path('js/app.js'));
   $minifier->minify(public_path('js/minified.js'));
   

Where to Look First

• Documentation: Focus on the Usage section in the README for core methods (add(), minify(), gzip()).
• Laravel Integration: Explore how to wrap this in an Artisan command or middleware (see Implementation Patterns).
• CSS-Specific Features: Review setMaxImportSize() and setImportExtensions() for asset embedding use cases.

First Use Case

Pre-Build Minification for Laravel Deployments:

// app/Console/Commands/MinifyAssets.php
use MatthiasMullie\Minify\CSS;
use MatthiasMullie\Minify\JS;

public function handle() {
    // Minify CSS
    $cssMinifier = new CSS(resource_path('assets/css/app.css'));
    $cssMinifier->add(resource_path('assets/css/vendor.css'));
    $cssMinifier->minify(public_path('css/minified.css'));

    // Minify JS
    $jsMinifier = new JS(resource_path('assets/js/app.js'));
    $jsMinifier->minify(public_path('js/minified.js'));
}

Run with:

php artisan minify:assets

Implementation Patterns

Core Workflows

1. Pre-Build Minification (Recommended for Static Assets)

• When: During deployments or build pipelines (e.g., Laravel Forge/Envoyer).
• How:
  • Create an Artisan command to process all assets.
  • Cache minified files in public/build/ to avoid reprocessing.
• Example:

  // app/Console/Commands/MinifyAllAssets.php
  public function handle() {
      $cssFiles = [
          resource_path('assets/css/main.css'),
          resource_path('assets/css/theme.css'),
      ];
      $jsFiles = [
          resource_path('assets/js/main.js'),
          resource_path('assets/js/utils.js'),
      ];
  
      $this->minifyFiles($cssFiles, 'css', 'minified');
      $this->minifyFiles($jsFiles, 'js', 'minified');
  }
  
  protected function minifyFiles(array $files, string $type, string $outputName) {
      $minifier = match ($type) {
          'css' => new CSS(...$files),
          'js' => new JS(...$files),
          default => throw new \InvalidArgumentException("Unsupported type: {$type}"),
      };
      $minifier->minify(public_path("build/{$outputName}.{$type}"));
  }
  

2. Runtime Minification (For Dynamic Assets)

• When: User-specific CSS/JS (e.g., dark mode toggles, A/B tests).
• How:
  • Use middleware to minify and cache results.
  • Leverage Laravel’s cache system to avoid reprocessing.
• Example:

  // app/Http/Middleware/MinifyDynamicAssets.php
  public function handle($request, Closure $next) {
      $cacheKey = 'minified_'.md5($request->user()->theme);
      $minified = Cache::get($cacheKey);
  
      if (!$minified) {
          $minifier = new CSS(resource_path("assets/css/{$request->user()->theme}.css"));
          $minified = $minifier->minify();
          Cache::put($cacheKey, $minified, now()->addHours(1));
      }
  
      return response($minified, 200, ['Content-Type' => 'text/css']);
  }
  

3. GZIP Compression for HTTP/2 Push

• When: Serving assets via HTTP/2 with server push.
• How:
  • Use gzip() to pre-compress assets.
  • Configure your web server (Nginx/Apache) to serve .gz files.
• Example:

  $minifier = new JS(resource_path('assets/js/app.js'));
  $minifier->gzip(public_path('js/minified.js.gz'));
  

4. Embedding Small Assets in CSS

• When: Reducing HTTP requests for small images/fonts.
• How:
  • Configure setMaxImportSize() and setImportExtensions().
• Example:

  $minifier = new CSS(resource_path('assets/css/styles.css'));
  $minifier->setMaxImportSize(10); // 10KB max for embedded assets
  $minifier->setImportExtensions([
      'svg' => 'data:image/svg+xml',
      'woff2' => 'data:application/font-woff2',
  ]);
  $minifier->minify(public_path('css/minified.css'));
  

Integration Tips

Laravel Service Provider

Register the minifier as a singleton for global access:

// app/Providers/AppServiceProvider.php
public function register() {
    $this->app->singleton('minifier.css', function () {
        return new CSS();
    });
    $this->app->singleton('minifier.js', function () {
        return new JS();
    });
}

Usage in controllers:

use Illuminate\Support\Facades\App;

$minifier = App::make('minifier.css');
$minifier->add($cssContent)->minify();

Blade Directives

Create a custom Blade directive for inline minification:

// app/Providers/BladeServiceProvider.php
Blade::directive('minify', function ($expression) {
    $minifier = new JS($expression);
    return "<?php echo {$minifier->minify()}; ?>";
});

Usage in Blade:

<script>
    @minify($jsCode)
</script>

Queue Jobs for Async Processing

Offload minification to a queue job for large assets:

// app/Jobs/MinifyAssetJob.php
public function handle() {
    $minifier = new JS(storage_path('app/assets/js/large.js'));
    $minifier->minify(public_path('js/minified/large.js'));
}

Dispatch during deployments:

MinifyAssetJob::dispatch()->onQueue('minification');

Dynamic File Addition

Add files dynamically based on user input or environment:

$minifier = new CSS(resource_path('assets/css/base.css'));
if (config('app.theme') === 'dark') {
    $minifier->add(resource_path('assets/css/dark-theme.css'));
}
$minifier->minify(public_path('css/theme.css'));

Gotchas and Tips

Pitfalls

1. Relative Path Handling in CSS

• Issue: If you minify CSS with @import or url() paths and don’t specify a target path, relative paths may break.
• Fix: Always pass a target path to minify():

  $minifier->minify(public_path('css/output.css')); // Correct
  // vs.
  $minifier->minify(); // Relative paths may fail
  

2. JS Optimizations Breaking Code

• Issue: The minifier converts true to !0 and false to !1, which may cause issues with:
  • Libraries expecting strict booleans (e.g., if (value === true)).
  • Source maps or debugging tools.
• Fix: Test thoroughly or disable optimizations by passing raw content:

  $minifier = new JS($jsContent);
  $minifier->minify(); // No optimizations if content is already minified
  

3. Large Asset Embedding

• Issue: Embedding large assets (e.g., >5KB images) increases CSS file size and load time.
• Fix: Use setMaxImportSize() to limit embedded asset sizes:

  $minifier->setMaxImportSize(5); // Default is 5KB
  

4. Caching Static Minified Files

• Issue: Re-minifying the same files repeatedly wastes CPU.
• Fix: Cache minified files in Laravel’s cache or filesystem:

  $cacheKey = 'minified_'.md5($cssContent);
  $minified = Cache::remember($cacheKey, now()->addDays(7), function () use ($minifier) {
      return $minifier->minify();
  });
  

5. CSS Custom Properties (Variables)

• Issue: The minifier may strip or alter CSS custom properties (--var-name).
• Fix: Avoid minifying CSS with custom properties unless tested, or pre-process with a tool like Post