monicahq/laravel-cloudflare

You can publish the package's configuration file to config/laravelcloudflare.php using the following command. While you may not need to modify it for standard use cases, it is available for customization.

php artisan vendor:publish --provider="Monicahq\Cloudflare\TrustedProxyServiceProvider"

Install the package using Composer to add Cloudflare IP addresses to your Laravel trusted proxies.

composer require monicahq/laravel-cloudflare

To automate the cache refresh, add the cloudflare:reload command to your task scheduler in routes/console.php.

use Illuminate\Support\Facades\Schedule;

Schedule::command('cloudflare:reload')->daily();

After installation, you must replace the default Laravel TrustProxies middleware with the package's middleware in your bootstrap/app.php file to ensure Cloudflare IPs are correctly handled.

->withMiddleware(function (Middleware $middleware) {
    $middleware->replace(
        \Illuminate\Http\Middleware\TrustProxies::class,
        \Monicahq\Cloudflare\Http\Middleware\TrustProxies::class
    );
})

You can override the default behavior of LaravelCloudflare::getProxies() by defining a custom callback using LaravelCloudflare::getProxiesUsing(). This is typically done in the boot method of your AppServiceProvider class.

use Illuminate\Support\ServiceProvider;
use Monicahq\Cloudflare\LaravelCloudflare;
use Monicahq\Cloudflare\Facades\CloudflareProxies;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Bootstrap any application services.
     */
    public function boot(): void
    {
        LaravelCloudflare::getProxiesUsing(fn() => CloudflareProxies::load());
    }
}

The Monicahq\Cloudflare\Http\Middleware\TrustProxies middleware extends Laravel's default TrustProxies middleware to automatically handle Cloudflare's IP ranges and headers.

To use this middleware effectively, you must configure the following keys in your config/laravelcloudflare.php file:

• enabled: (boolean) When true, the middleware will attempt to set trusted proxies using the Cloudflare IP list fetched via LaravelCloudflare::getProxies().
• replace_ip: (boolean) When true, the middleware will overwrite the REMOTE_ADDR server variable with the value from the Cf-Connecting-Ip header. This ensures that $request->ip() returns the actual visitor IP instead of the Cloudflare proxy IP.
• cache: (string) The cache key used to store the Cloudflare IP list. This prevents repeated API calls to fetch the IP ranges.

When running automated tests, you can prevent the package from attempting to fetch Cloudflare proxy addresses by setting the LARAVEL_CLOUDFLARE_ENABLED environment variable to false in your .env or phpunit.xml file.

LARAVEL_CLOUDFLARE_ENABLED=false

Check the following compatibility table to ensure your Laravel version is supported by the corresponding version of monicahq/laravel-cloudflare.

| Laravel  | monicahq/laravel-cloudflare |
|----------|-----------------------------|
| 5.x-6.x  | <= 1.8                      |
| 7.x-8.53 | 2.x                         |
| 8.54-12.0| 3.x                         |
| >= 11.0  | >= 4.x                      |

The package retrieves Cloudflare's IP blocks and stores them in your application's cache. To ensure you always have up-to-date proxy information, you should refresh this cache regularly using the cloudflare:reload Artisan command.

php artisan cloudflare:reload

Use the cloudflare:view Artisan command to inspect the current IP blocks stored in your cache.

php artisan cloudflare:view

The load() method retrieves the list of Cloudflare proxy IP addresses based on the configuration and the requested IP version type. It uses the paths defined in your Laravel configuration under laravelcloudflare.ipv4-path and laravelcloudflare.ipv6-path.

use Monicahq\Cloudflare\CloudflareProxies;

// Assuming $cloudFlareProxies is an instance of CloudflareProxies
// Load both IPv4 and IPv6 addresses
$proxies = $cloudFlareProxies->load(CloudflareProxies::IP_VERSION_ANY);

// Load only IPv4 addresses
$proxies = $cloudFlareProxies->load(CloudflareProxies::IP_VERSION_4);

When interacting with the CloudflareProxies class, you can specify which IP versions to load using bitwise constants. This allows you to filter for IPv4, IPv6, or both.

// Available IP version constants
Monica\Cloudflare\CloudflareProxies::IP_VERSION_4; // Use IPv4 addresses
Monica\Cloudflare\CloudflareProxies::IP_VERSION_6; // Use IPv6 addresses
Monica\Cloudflare\CloudflareProxies::IP_VERSION_ANY; // Use any IP addresses (IPv4 | IPv6)