Laravel Page Speed Laravel Package

Getting Started

The Laravel Page Speed package (codeat3/laravel-page-speed) optimizes frontend assets (CSS/JS) and implements performance best practices like lazy loading, critical CSS, and asset minification. To start:

1. Installation: Requires Laravel 8+ and PHP 8.0+. Install via Composer:

   composer require codeat3/laravel-page-speed
   

2. Publish Config: Run php artisan vendor:publish --provider="Codeat3\PageSpeed\PageSpeedServiceProvider" to generate config/page-speed.php.
3. First Use Case: Enable core features in config/page-speed.php:

   'enabled' => env('PAGE_SPEED_ENABLED', true),
   'lazy_load' => true,
   'critical_css' => true,
   

4. Blade Integration: Use @pageSpeed directive in views to auto-optimize assets:

   @pageSpeed
   

Implementation Patterns

Core Workflows

• Asset Optimization: Automatically minifies and combines CSS/JS files. Configure exclusions in config/page-speed.php:

  'excludes' => [
      'admin/**',
      'vendor/**',
  ],
  

• Lazy Loading: Enable for images/videos via:

  'lazy_load' => [
      'images' => true,
      'videos' => true,
      'iframes' => false,
  ],
  

• Critical CSS: Extract above-the-fold CSS dynamically. Use PageSpeed::criticalCss() in controllers or Blade:

  <style>{{ PageSpeed::criticalCss() }}</style>
  

Advanced Patterns

• Custom Directives: Extend with custom directives (e.g., @pageSpeedPreload):

  // In a service provider:
  PageSpeed::extend('preload', function ($view, $expr) {
      return '<link rel="preload" href="' . $expr . '">';
  });
  

• Middleware: Apply optimizations globally via middleware:

  PageSpeed::middleware();
  

• Queue Processing: Offload heavy tasks (e.g., critical CSS generation) to queues:

  'critical_css' => [
      'queue' => true,
  ],
  

Integration Tips

• Vite/Laravel Mix: Works alongside asset pipelines. Disable package optimizations if using Vite’s built-in minification.
• Caching: Leverage Laravel’s cache for critical CSS:

  'critical_css' => [
      'cache' => true,
      'cache_key' => 'pagespeed_critical_css',
  ],
  

• Testing: Use PageSpeed::flush() in tests to reset cached optimizations.

Gotchas and Tips

Common Pitfalls

• Critical CSS Conflicts: If critical CSS breaks layouts, increase the buffer size in config or exclude problematic assets.
• Lazy Loading Issues: Ensure loading="lazy" is not duplicated (e.g., by other packages). Use PageSpeed::shouldLazyLoad() to check.
• Queue Stuck Jobs: Monitor page_speed:generate-critical-css jobs in Laravel queues. Retry failed jobs manually if needed.

Debugging

• Log Output: Enable debug mode to log optimizations:

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

• Asset Exclusions: Verify exclusions in config/page-speed.php aren’t blocking critical assets.
• Browser DevTools: Check the "Network" tab for optimized asset tags (e.g., ?page-speed=1 query strings).

Extension Points

• Custom Optimizers: Implement Codeat3\PageSpeed\Contracts\Optimizer to add new optimizations (e.g., font preloading).
• Event Listeners: Listen to page-speed.optimized events for post-optimization logic:

  Event::listen(PageSpeedOptimized::class, function ($event) {
      // Log or process optimized assets
  });
  

• Configuration Overrides: Use environment variables to override config values dynamically:

  'lazy_load' => env('PAGE_SPEED_LAZY_LOAD', true),
  

Breaking Changes (v2.5)

• Critical CSS Generation: The generateCriticalCss() method now returns a CriticalCss object instead of a raw string. Use $criticalCss->html() to get the output.
• Middleware Signature: The middleware constructor now accepts a PageSpeed instance. Update custom middleware:

  public function __construct(PageSpeed $pageSpeed) { ... }
  

• Deprecated: The PageSpeed::optimize() method is deprecated. Use PageSpeed::process() instead.