Laravel Cloudflare Setup

When to use this skill

Use this skill when:

• •Installing the laravel-cloudflare package
• •Configuring TrustProxies middleware for Cloudflare
• •Setting up automated IP refresh scheduling
• •Debugging proxy or IP detection issues

Installation Steps

1. Install the package

composer require usesorane/laravel-cloudflare

2. Publish configuration (optional)

php artisan vendor:publish --tag="laravel-cloudflare"

3. Fetch IPs initially

php artisan cloudflare:refresh

4. Configure TrustProxies middleware

In bootstrap/app.php, add the Cloudflare IPs to the trusted proxies configuration:

use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(/* ... */)
    ->withMiddleware(function (Middleware $middleware) {
        app()->booted(function () use ($middleware) {
            $cloudflareIps = app(\Sorane\LaravelCloudflare\LaravelCloudflare::class)->all();
            $middleware->trustProxies(at: $cloudflareIps);
        });
    })
    ->create();

Important: The app()->booted() callback is required because the IPs are loaded from cache, which may not be available during early bootstrap.

5. Schedule automatic refreshes

In routes/console.php, add:

use Illuminate\Support\Facades\Schedule;

Schedule::command('cloudflare:refresh')->twiceDaily();

This keeps the cached IP list up-to-date as Cloudflare occasionally updates their ranges.

Verification

After setup, verify the configuration:

# Check cache status
php artisan cloudflare:cache-info

# Should show cached IPv4 and IPv6 counts

Artisan Commands

Programmatic API

Access IPs via the facade or service:

use Sorane\LaravelCloudflare\Facades\LaravelCloudflare;

$allIps = LaravelCloudflare::all();      // Combined IPv4 + IPv6 array
$ipv4Only = LaravelCloudflare::ipv4();   // IPv4 ranges only
$ipv6Only = LaravelCloudflare::ipv6();   // IPv6 ranges only
$success = LaravelCloudflare::refresh(); // Fetch and cache immediately
$info = LaravelCloudflare::cacheInfo();  // Get cache status

Events

Listen to these events for monitoring or custom logic:

Example listener:

use Sorane\LaravelCloudflare\Events\CloudflareRefreshFailed;

Event::listen(function (CloudflareRefreshFailed $event) {
    if ($event->ipv4Empty && $event->ipv6Empty) {
        // Alert: complete refresh failure
    }
});

Configuration Options

Key settings in config/laravel-cloudflare.php:

Diagnostics (Optional)

For debugging proxy issues, enable the diagnostics endpoint:

In .env:

CLOUDFLARE_DIAGNOSTICS_ENABLED=true

Or in config/laravel-cloudflare.php:

'diagnostics' => [
    'enabled' => true,
    'path' => '/cloudflare-diagnose',
    'middleware' => ['web'],
],

Then visit /cloudflare-diagnose to see:

• •laravel_ip - The IP Laravel sees after proxy trust
• •remote_addr - Direct connection IP
• •x_forwarded_for - Forwarding chain
• •cf_connecting_ip - Cloudflare's client IP header

If laravel_ip matches cf_connecting_ip, proxy trust is configured correctly.

Troubleshooting

IPs not loading / empty array

1. •Run php artisan cloudflare:refresh to fetch IPs
2. •Check php artisan cloudflare:cache-info for cache status
3. •Verify cache driver is working: php artisan cache:clear && php artisan cloudflare:refresh

Client IP still shows Cloudflare IP

1. •Ensure the app()->booted() wrapper is used in bootstrap/app.php
2. •Check that X-Forwarded-For header is being sent (use diagnostics endpoint)
3. •Verify the request is actually coming through Cloudflare

First deployment with empty cache

Add static fallback IPs in config/laravel-cloudflare.php:

'fallback' => [
    'ipv4' => [
        '173.245.48.0/20',
        '103.21.244.0/22',
        // ... add current Cloudflare IPv4 ranges
    ],
    'ipv6' => [
        '2400:cb00::/32',
        '2606:4700::/32',
        // ... add current Cloudflare IPv6 ranges
    ],
],

These are used if the cache is empty (e.g., fresh deployment before first refresh).