Download the PHP package illuma-law/laravel-edge-clear without Composer

Laravel Edge Clear

Standalone Cloudflare cache purging and cache bypass management for Laravel applications.

This package provides a fluent service, a Facade, and specialized middleware designed to help you manage your Cloudflare CDN cache directly from your Laravel application.

Features

• Purge Specific URLs: Invalidate only the pages that have changed.
• Purge by Tags: Quickly wipe out categories of content across your site using Cloudflare Cache Tags (requires Cloudflare Enterprise).
• Purge Everything: The "nuke from orbit" option.
• Generic Purge Job: A robust PurgeEdgeCacheJob that handles automatic fallback from tag-based purging to URL-based purging if Enterprise features are missing.
• Set Cache Headers Middleware: Easily manage Cache-Control and Cache-Tag headers for your routes.
• Cache Bypass Middleware: Attach middleware to specific routes or controllers to ensure Cloudflare never caches them.
• Lifecycle Events: Listen to EdgeCachePurged and EdgeCachePurgeFailed to keep your application state in sync with the CDN.
• Environment Awareness: Safely test your code locally without accidentally triggering real API calls.

Installation

You can install the package via composer:

You can publish the config file with:

Configuration

In your .env file, configure your Cloudflare credentials. You can use either an API Token (recommended) or an API Email + Key combo.

The published config/edge-clear.php config looks like this:

Usage & Integration

Triggering Purges

Use the CloudflarePurger facade to interact with the cache:

Real-world Example: Eloquent Observer

Invalidate your cache automatically when a model is saved or deleted:

Route Middleware

If you have specific routes that should never be cached by Cloudflare (like admin dashboards, carts, or user profiles), you can use the BypassEdgeCache middleware. It automatically appends headers (Cache-Control: no-store, no-cache...) that instruct Cloudflare to skip caching the response.

Set Cache Headers

Use the SetEdgeCacheHeaders middleware to manage your CDN headers fluently. It handles Cache-Control (including s-maxage) and Cache-Tag injection.

The middleware parameters are: ttl, tags (separated by ;), and profile (short or permanent).

Queued Purging (with Fallback)

For high-volume sites, you can use the PurgeEdgeCacheJob. It automatically detects if your Cloudflare plan supports Cache Tags and falls back to URL purging if needed.

Lifecycle Events

The package dispatches events that you can listen to for logging or updating your application state:

• IllumaLaw\EdgeClear\Events\EdgeCachePurged: Dispatched when a purge request is successful.
• IllumaLaw\EdgeClear\Events\EdgeCachePurgeFailed: Dispatched when a purge request fails after all retries.

Error Handling

If Cloudflare rejects your request (e.g., bad token, invalid URLs), the package will throw a typed CloudflarePurgeException.

Testing

The package includes a comprehensive test suite using Pest.

License

The MIT License (MIT). Please see License File for more information.