README

Using this in a Laravel project? Come talk to us — Join the Discord → Performance wins, edge cases, and what you're shipping. The maintainer is in there.

Laravel Page Speed

Laravel Page Speed delivers an end-to-end optimization pipeline for Blade-rendered pages and REST APIs with measurable gains in latency, bandwidth, and resiliency.

Table of Contents

• Overview
• Optimization Pipelines
• Quick Integration
• Measured Impact
• Observability and Resilience
• Documentation Suite
• Contributing and Support

Overview

• Dual scope: optimizes rendered HTML and JSON/XML payloads without modifying your business payloads.
• Composable stack: enable only the middleware you need through config/laravel-page-speed.php.
• Store-agnostic: works with Redis, Memcached, DynamoDB (via cache tags), file, or array drivers across Laravel 10–13.
• Built for observability: exposes latency, memory usage, cache hits, and circuit status via standard HTTP headers.

Optimization Pipelines

Web (HTML/Blade)

• Structured HTML minification and comment stripping that stay compatible with Bootstrap, Tailwind, and Livewire.
• Targeted critical CSS inlining to reduce render-blocking round trips.
• Script deferral and DNS prefetching that maintain execution order through data-ps-* guards.

APIs (REST/JSON)

• Adaptive compression (Brotli first, Gzip fallback) with configurable size thresholds to avoid overhead on small payloads.
• Response caching with method-aware invalidation, dynamic tag derivation per path segment, and hit-rate metrics.
• Pre-hardened security headers (HSTS, CSP, Permissions-Policy) and an automatic circuit breaker with customizable fallbacks.
• Lightweight health check middleware designed for Kubernetes probes and service orchestrators.

Quick Integration

Web Middleware

Choose the registration pattern that matches your Laravel install:

Laravel 10.x (app/Http/Kernel.php)

Append the middleware inside the web group so the order stays deterministic:

protected $middlewareGroups = [
    'web' => [
        // ... existing middleware
        \VinkiusLabs\LaravelPageSpeed\Middleware\InlineCss::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\ElideAttributes::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\InsertDNSPrefetch::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\CollapseWhitespace::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\DeferJavascript::class,
    ],
];

Laravel 11.x, 12.x and 13.x (bootstrap/app.php)

Use the middleware configurator introduced in Laravel 11. Extend the existing ->withMiddleware closure:

use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: __DIR__.'/../')
    // ... existing configuration
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->appendToGroup('web', [
            \VinkiusLabs\LaravelPageSpeed\Middleware\InlineCss::class,
            \VinkiusLabs\LaravelPageSpeed\Middleware\ElideAttributes::class,
            \VinkiusLabs\LaravelPageSpeed\Middleware\InsertDNSPrefetch::class,
            \VinkiusLabs\LaravelPageSpeed\Middleware\CollapseWhitespace::class,
            \VinkiusLabs\LaravelPageSpeed\Middleware\DeferJavascript::class,
        ]);

        // keep other group definitions (api, broadcast, etc.) here
    })
    ->create();

API Middleware

Attach only the middleware that fits your API architecture.

Laravel 10.x (app/Http/Kernel.php)

protected $middlewareGroups = [
    'api' => [
        // ... existing middleware
        \VinkiusLabs\LaravelPageSpeed\Middleware\ApiSecurityHeaders::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\ApiResponseCache::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\ApiETag::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\ApiResponseCompression::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\ApiPerformanceHeaders::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\ApiCircuitBreaker::class,
        \VinkiusLabs\LaravelPageSpeed\Middleware\ApiHealthCheck::class,
    ],
];

Laravel 11.x, 12.x and 13.x (bootstrap/app.php)

Inside the same ->withMiddleware closure from the Web section, append the API stack:

$middleware->appendToGroup('api', [
    \VinkiusLabs\LaravelPageSpeed\Middleware\ApiSecurityHeaders::class,
    \VinkiusLabs\LaravelPageSpeed\Middleware\ApiResponseCache::class,
    \VinkiusLabs\LaravelPageSpeed\Middleware\ApiETag::class,
    \VinkiusLabs\LaravelPageSpeed\Middleware\ApiResponseCompression::class,
    \VinkiusLabs\LaravelPageSpeed\Middleware\ApiPerformanceHeaders::class,
    \VinkiusLabs\LaravelPageSpeed\Middleware\ApiCircuitBreaker::class,
    \VinkiusLabs\LaravelPageSpeed\Middleware\ApiHealthCheck::class,
]);

Publish assets and baseline environment variables

composer require vinkius-labs/laravel-page-speed
php artisan vendor:publish --provider="VinkiusLabs\\LaravelPageSpeed\\ServiceProvider"

Recommended baseline for cached APIs:

LARAVEL_PAGE_SPEED_ENABLE=true
API_CACHE_ENABLED=true
API_CACHE_DRIVER=redis
API_CACHE_TTL=300
API_CACHE_DYNAMIC_TAGS=true

Measured Impact

Reference scenario: 1M requests/day with a 65% cache hit rate.

Observability and Resilience

• Performance headers: X-Response-Time, X-Memory-Usage, X-Cache-Status, X-Circuit-Breaker-State ready for ingestion by Datadog, New Relic, or Prometheus scrapers.
• Configurable circuit breaker: customize failure thresholds, timeout, and scope (route, endpoint, or path) via configuration.
• Adaptive health check: aggregates database, cache, disk, and queue probes with optional 10-second result caching.
• Debug-aware skipping: curated skip patterns avoid instrumenting Debugbar, Telescope, Horizon, or custom diagnostic routes.

Documentation Suite

• Documentation Hub
• Web Optimization
• API Optimization
• Cache Architecture
• Configuration Reference
• Scenario Playbooks
• Executive Summary

Contributing and Support

• Review CONTRIBUTING.md before opening pull requests.
• Run composer test (or docker compose exec app vendor/bin/phpunit) prior to submitting changes.
• File issues and start discussions via GitHub Issues and Discussions.
• Distributed under the MIT license.