README

Interceptor is a powerful route caching module for Laravel, designed to boost application performance by caching full HTTP responses. It handles cache management, automatic garbage collection, and supports device-specific caching.

Features

Full Response Caching: Caches the entire HTTP response for defined routes.
Device Awareness: Separately caches content for different devices (Desktop, Mobile, Tablet) or custom devices.
Redis & File Storage: tailored for Redis but supports file-based fallback.
Automatic Garbage Collection: Automatically cleans up old or least recently used cache entries when limits are reached.
Smart Refresh: Can refresh expired cache asynchronously.
Compression: Built-in Gzip compression to save storage space.
Flexible Bypassing: Configure rules to bypass cache based on Cookies, IPs, User Agents, Headers, or specific Routes.
Management Commands: Artisan commands to flush, refresh, and monitor cache.

Requirements

PHP >= 5.6.4
Laravel Framework
Redis (Recommended)

Installation

Install via Composer:

composer require megaads/interceptor

Registers Provider

Laravel > 5.5: The package should be auto-discovered.

Laravel < 5.5: Add the service provider to your config/app.php:

'providers' => [
    // ...
    Megaads\Interceptor\InterceptorServiceProvider::class,
],

Publish Configuration

Publish the configuration file to customize the settings:

php artisan vendor:publish --provider="Megaads\Interceptor\InterceptorServiceProvider"

Measurements generally will be available in config/interceptor.php.

Configuration

The configuration file config/interceptor.php allows you to tweak various aspects:

enable: Toggle caching globally.
maxCacheSize: Maximum number of items in cache buffer before garbage collection kicks in.
refreshRate: Time in seconds before a cache entry is considered "stale" (but still valid) and triggers a background refresh.
maxAge: Time in seconds before a cache entry is considered expired and hard removed.
devices: List of device types to categorize requests (e.g., 'desktop', 'mobile').
saveToFile: Set to true to use file storage instead of Redis.
compress: Enable Gzip compression.
bypasses: Define rules to skip caching:
- cookies: Skip if specific cookies are present.
- ips: Skip specific IP addresses or ranges (wildcards supported).
- userAgents: Skip specific User Agents (Regex supported).
- headers: Skip based on request headers.
- routes: Skip specific route patterns.

Usage

Middleware

Apply the interceptor middleware to the routes or groups you want to cache in your routes/web.php or routes/api.php:

Route::group(['middleware' => 'interceptor'], function () {
    Route::get('/', 'HomeController@index');
    Route::get('/category/{slug}', 'CategoryController@show');
});

Console Commands

The package provides several Artisan commands for managing the cache:

Flush all cache:
```
php artisan interceptor:flush
```

Monitor cache stats:

# Check total cache count
php artisan interceptor:monitor sum

# List cache keys (optional device filter)
php artisan interceptor:monitor list
php artisan interceptor:monitor list mobile

# Check specific URL keys
php artisan interceptor:monitor check "https://example.com/foo"

Remove specific cache:

# Remove cache for a specific URL (all devices)
php artisan interceptor:remove "https://example.com/foo"

Refesh specific cache:

# Refresh cache for a specific URL (all devices)
php artisan interceptor:refresh url "https://example.com/foo"

# Refresh out-of-date cache items (limit 10)
php artisan interceptor:refresh outofdate 10

Manually trigger garbage collection:
```
php artisan interceptor:garbage
```

Headers

Interceptor adds the following headers to cached responses to help you debug:

Served-From: interceptor (Indicates the response came from this package)
Interceptor-Cache-State: HIT or MISS
Interceptor-Cache-Time: Timestamp of when the cache was created.
Interceptor-Meta-Data: JSON encoded metadata about the cache request.

License

This project is licensed under the MIT License.

megaads / interceptor

Maintainers

Details