Download the PHP package nexxai/laravel-cfcache without Composer

Laravel Cloudflare Cache

This package provides tools to manage Cloudflare integration with your Laravel application. It includes commands for generating Cloudflare security rules and purging cached content.

The WAF rule generation was inspired by Jason McCreary's tweet: https://x.com/gonedark/status/1978458884948775294

Requirements

A Laravel application running Laravel 12 or higher. Not running a stable version of Laravel? Upgrade with Shift.

Installation / Updating

You can install this package by running the following command:

To publish the configuration file (needed for WAF rule syncing):

Basic Usage

WAF Rule Generation

Generate the WAF rule expression for your Laravel routes:

Once generated, you can copy and paste the expression into your domain's security rules by going to Security -> Security Rules -> Create Rule -> Custom Rule -> Edit expression

Cache Purging

Purge all cached content or specific paths/routes:

Please see the Notes section below for additional information and examples, and potential gotchas.

Advanced Usage

Cloudflare API Configuration

To use the live Cloudflare features, you need to configure your Cloudflare API credentials. Add the following to your .env file:

Getting Your Cloudflare Credentials

1. API Token:

   • Go to Cloudflare Dashboard
   • Click "Create Token"
   • Use the "Custom token" template
   • Name the token "CFCache package token"
   • Based on the features you need, grant the following permissions:
     • WAF rules: Zone -> Firewall Services -> Edit
     • Cache purging: Zone -> Cache Purge -> Purge
   • Include your specific zone(s) in the Zone Resources
   • Create the token and copy it to your .env file as CFCACHE_API_TOKEN
2. Zone ID:
   • Go to your domain's overview page in Cloudflare
   • Find the Zone ID in the right sidebar under "API"
   • Copy it to your .env file as CFCACHE_ZONE_ID

[!NOTE]
You may create a single token that applies to multiple zones, but ensure that you use the correct zone ID as the CFCACHE_ZONE_ID in each respective app's .env file.

Sync to Cloudflare API

Automatically create or update the WAF rule in Cloudflare:

Configuration

After publishing the configuration file, you can customize additional settings in config/cfcache.php:

Available Rule Actions

• block - Block the request entirely
• challenge - Present a challenge to the visitor
• js_challenge - Present a JavaScript challenge
• managed_challenge - Use Cloudflare's managed challenge
• allow - Allow the request
• log - Log the request without taking action
• bypass - Bypass all security features

Ignorable Paths

You can configure paths that should be excluded from the WAF rule generation. This is useful for local development routes that shouldn't be included in production security rules:

The patterns support wildcards using Laravel's Str::is() syntax:

• /_dusk/* matches /dusk/login, /dusk/test, etc.
• /admin/* matches any path under /admin/
• Exact matches like /debug work too

By default, only /_dusk/* is ignored to prevent Dusk testing routes from being included in production rules.

Forced Allowed Paths

Paths that are not part of your Laravel routes but must be allowed by the WAF (e.g. Cloudflare-injected scripts like Zaraz) can be added so they are always included in the allowlist:

Wildcards are supported (e.g. /cdn-cgi/zaraz/*). Paths are normalized with a leading slash if omitted.

Hostnames

When using multiple hostnames or subdomains in the same zone, you can restrict the generated WAF rule so it only applies to specific hosts. If hostnames is empty (default), the rule applies to all hostnames.

Set hostnames in config or via .env:

Cache Purging

This package also provides commands to purge Cloudflare's cache for specific paths or routes in your Laravel application.

Basic Cache Purging

Purge all cached content from Cloudflare:

Add --force to skip the confirmation prompt when purging all cached content:

Purge Specific Paths

Purge specific paths (relative paths will be prefixed with your app URL):

Purge by Route Names

Purge cache for specific Laravel routes by name (route parameters are converted to wildcards):

Purge by Prefix or Host

Use --prefix when you want to purge every cached URL under a specific prefix without purging the whole zone. This is useful for deploys where one Cloudflare zone contains multiple sites or subdomains:

Use --host when you want to purge everything cached for a host:

--prefix and --host are exclusive purge modes. They cannot be used together, and neither option can be combined with paths, --route, or --all.

Scheduled Cache Purges

Add --schedule with any timestamp Carbon can parse to store a purge for later:

Scheduled purges are stored on disk at the path configured by cfcache.scheduled_purges.file, which defaults to storage/app/laravel-cfcache/scheduled-purges.json. The stored command parameters do not include --schedule, so due purges are re-run as normal cloudflare:purge commands.

[!NOTE] This package does NOT automatically register a Laravel scheduled task. You must opt in by adding one to your application. This is intentional because scheduled tasks can have a financial impact on hosting providers such as Laravel Cloud.

Add this to your routes/console.php:

Cloudflare API Configuration for Cache Purging

To use cache purging, you need to configure your Cloudflare API credentials with cache purge permissions. Add the following to your .env file:

Getting Cache Purge Permissions

For cache purging, your API token needs the following permission:

• Zone -> Cache Purge -> Edit

You can create a token with both WAF and Cache Purge permissions if you plan to use both features.

Notes

Multiple subdomains

If you use multiple subdomains (e.g., example.com and sub.example.com) in the same zone, set the hostnames option in config/cfcache.php (see Hostnames) so the generated WAF rule only applies to the hostnames you specify. Otherwise the rule would apply to every hostname on the zone.

Certbot / .well-known

If you're using Certbot and the .well-known directory to manage your SSL certificates (or for other purposes), you will need to manually add a .well-known/* rule to the wildcard section of your WAF rule.

Cache Purging Notes

• Route parameters (like {id}) are converted to wildcards (*) for Cloudflare compatibility
• Relative paths are automatically prefixed with your APP_URL
• Full URLs (starting with http:// or https://) are used as-is
• Unknown route names are silently skipped
• Add --force with --all to skip the confirmation prompt
• Use --prefix to purge every cached URL under a URL prefix
• Use --host to purge everything cached for a host
• --prefix and --host cannot be combined with each other, paths, routes, or --all
• Cache purging requires different API permissions than WAF rule management

Contributing

Contributions to this project are welcome. You may open a Pull Request against the main branch. Please ensure you write a clear description (ideally with code samples) and all workflows are passing. PRs without tests confirming the proposed behavior will not be accepted.