### Install laravel-cloudflare Package

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Install the package using Composer. This is the first step to integrate Cloudflare proxies.

```bash
composer require monicahq/laravel-cloudflare
```

--------------------------------

### Simulating TrustProxies Middleware

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

This example demonstrates how the `TrustProxies` middleware handles requests. When `replace_ip` is enabled, `$request->ip()` will return the true visitor IP from the `Cf-Connecting-Ip` header after the middleware processes the request.

```php
// The middleware runs automatically once registered in bootstrap/app.php.
// The following illustrates what happens internally on each request:

use Monicahq\Cloudflare\Http\Middleware\TrustProxies;
use Illuminate\Http\Request;

// Simulating middleware dispatch in a test or custom kernel:
$request = Request::create('https://example.com/api/user', 'GET');
$request->headers->set('Cf-Connecting-Ip', '203.0.113.45');
$request->headers->set('X-Forwarded-For', '203.0.113.45');

$middleware = app(TrustProxies::class);
$response   = $middleware->handle($request, function (Request $req) {
    // After middleware runs, $req->ip() returns the real visitor IP
    // because Cloudflare's ranges are now trusted proxies.
    return response()->json(['ip' => $req->ip()]);
    // {"ip":"203.0.113.45"}
});
```

--------------------------------

### Publish Package Configuration

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Publish the package's configuration file to `config/laravelcloudflare.php` using the `vendor:publish` Artisan command. This allows for customization, though often not required.

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

--------------------------------

### Load Cloudflare IP Blocks

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Fetches Cloudflare's IPv4 and/or IPv6 address ranges. Use the facade for general use or direct instantiation for testing with mocked HTTP requests. Throws an exception if the request fails.

```php
use Monicahq\Cloudflare\CloudflareProxies;
use Monicahq\Cloudflare\Facades\CloudflareProxies as CloudflareProxiesFacade;

// Via facade — load all IP blocks (IPv4 + IPv6, the default)
$allProxies = CloudflareProxiesFacade::load();
// e.g. ['173.245.48.0/20', '103.21.244.0/22', ..., '2400:cb00::/32', ...]

// Load only IPv4 blocks
$ipv4Proxies = CloudflareProxiesFacade::load(CloudflareProxies::IP_VERSION_4);
// e.g. ['173.245.48.0/20', '103.21.244.0/22', '103.22.200.0/22', ...]

// Load only IPv6 blocks
$ipv6Proxies = CloudflareProxiesFacade::load(CloudflareProxies::IP_VERSION_6);
// e.g. ['2400:cb00::/32', '2606:4700::/32', '2803:f800::/32', ...]

// Via direct instantiation (useful in tests with Http::fake())
$loader = app(CloudflareProxies::class);
try {
    $proxies = $loader->load(CloudflareProxies::IP_VERSION_ANY);
} catch (\UnexpectedValueException $e) {
    // Cloudflare endpoint unreachable
    logger()->error('Could not refresh Cloudflare proxies: ' . $e->getMessage());
    $proxies = [];
}
```

--------------------------------

### Register Custom Proxy Callback

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Replaces the default IP block loading with a custom closure. Typically used in `AppServiceProvider::boot()` to customize proxy sources, such as loading only IPv4 or merging internal IPs.

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

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Example 1: Load only IPv4 proxies instead of both versions
        LaravelCloudflare::getProxiesUsing(
            fn () => CloudflareProxies::load(\Monicahq\Cloudflare\CloudflareProxies::IP_VERSION_4)
        );

        // Example 2: Merge Cloudflare ranges with your own internal proxy IPs
        LaravelCloudflare::getProxiesUsing(function () {
            $cloudflare = CloudflareProxies::load();
            $internal   = ['10.0.0.0/8', '192.168.1.0/24'];
            return array_merge($cloudflare, $internal);
        });

        // Example 3: Use a static list (e.g., in CI/testing environments)
        if (app()->environment('testing')) {
            LaravelCloudflare::getProxiesUsing(fn () => ['127.0.0.1']);
        }
    }
}

// Reset to default behavior at any point:
LaravelCloudflare::getProxiesUsing(null);
```

--------------------------------

### Artisan Command: View Cached IPs

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Displays the currently cached Cloudflare IP address blocks in a formatted table. This is useful for verifying that the cache has been populated and for inspecting the active proxy ranges.

```bash
php artisan cloudflare:view

# Example output:
# +-----------------------+
# | Address               |
# +-----------------------+
# | 173.245.48.0/20       |
# | 103.21.244.0/22       |
# | 103.22.200.0/22       |
# | 103.31.4.0/22         |
# | 141.101.64.0/18       |
# | 108.162.192.0/18      |
# | 190.93.240.0/20       |
# | 188.114.96.0/20       |
# | 197.234.240.0/22      |
# | 198.41.128.0/17       |
# | 162.158.0.0/15        |
# | 104.16.0.0/13         |
# | 104.24.0.0/14         |
# | 172.64.0.0/13         |
# | 131.0.72.0/22         |
# | 2400:cb00::/32        |
# | 2606:4700::/32        |
# | ...                   |
# +-----------------------+
```

--------------------------------

### Artisan Command — `cloudflare:view`

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Displays the Cloudflare IP address blocks currently stored in the application cache as a formatted table. Useful for verifying that the cache has been populated and inspecting active proxy ranges.

```APIDOC
## Artisan Command — `cloudflare:view`

Displays the Cloudflare IP address blocks currently stored in the application cache as a formatted table. Useful for verifying that the cache has been populated and inspecting active proxy ranges.

### Usage

```bash
php artisan cloudflare:view

# Example output:
# +-----------------------+
# | Address               |
# +-----------------------+
# | 173.245.48.0/20       |
# | 103.21.244.0/22       |
# | 103.22.200.0/22       |
# | 103.31.4.0/22         |
# | 141.101.64.0/18       |
# | 108.162.192.0/18      |
# | 190.93.240.0/20       |
# | 188.114.96.0/20       |
# | 197.234.240.0/22      |
# | 198.41.128.0/17       |
# | 162.158.0.0/15        |
# | 104.16.0.0/13         |
# | 104.24.0.0/14         |
# | 172.64.0.0/13         |
# | 131.0.72.0/22         |
# | 2400:cb00::/32        |
# | 2606:4700::/32        |
# | ...                   |
# +-----------------------+
```
```

--------------------------------

### Artisan Command — `cloudflare:reload`

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Fetches fresh IP blocks from Cloudflare and stores them in the application cache indefinitely. Respects the `laravelcloudflare.enabled` config flag and does nothing if the package is disabled. Schedule this daily to keep proxy addresses current.

```APIDOC
## Artisan Command — `cloudflare:reload`

Fetches fresh IP blocks from Cloudflare and stores them in the application cache indefinitely. Respects the `laravelcloudflare.enabled` config flag and does nothing if the package is disabled. Schedule this daily to keep proxy addresses current.

### Usage

```bash
# Manually refresh cached IP blocks
php artisan cloudflare:reload
# Output: Cloudflare's IP blocks have been reloaded.
```

### Scheduling

```php
// routes/console.php — schedule automatic daily refresh
use Illuminate\Support\Facades\Schedule;

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

// Or run at a specific time to avoid peak traffic periods
Schedule::command('cloudflare:reload')->dailyAt('03:00');
```
```

--------------------------------

### Register TrustProxies Middleware

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Replace Laravel's default `TrustProxies` middleware with the `Monicahq\Cloudflare\Http\Middleware\TrustProxies` class in `bootstrap/app.php`.

```php
use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->replace(
            \Illuminate\Http\Middleware\TrustProxies::class,
            \Monicahq\Cloudflare\Http\Middleware\TrustProxies::class
        );
    })
    ->create();
```

--------------------------------

### View Cached Cloudflare IP Blocks

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Use the `cloudflare:view` Artisan command to inspect the currently cached Cloudflare IP blocks.

```bash
php artisan cloudflare:view
```

--------------------------------

### Default Configuration (`config/laravelcloudflare.php`)

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Customize Cloudflare integration settings like enabling/disabling the middleware, replacing the IP address, cache key, and Cloudflare API endpoint paths.

```php
return [
    // Enable or disable the middleware and reload command entirely
    'enabled'      => (bool) env('LARAVEL_CLOUDFLARE_ENABLED', true),

    // Replace REMOTE_ADDR with Cloudflare's Cf-Connecting-Ip header value
    'replace_ip'   => (bool) env('LARAVEL_CLOUDFLARE_REPLACE_IP', false),

    // Cache key used to store the IP block list
    'cache'        => 'cloudflare.proxies',

    // Base URL for Cloudflare's IP list endpoints
    'url'          => 'https://www.cloudflare.com',

    // Paths appended to 'url' to retrieve IPv4 and IPv6 blocks
    'ipv4-path'    => 'ips-v4',
    'ipv6-path'    => 'ips-v6',
];
```

--------------------------------

### Define Custom Proxies Callback

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Customize how Cloudflare proxies are loaded by defining a custom callback using `LaravelCloudflare::getProxiesUsing()`. This method should be called in the `boot` method of your `AppServiceProvider`.

```php
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());
    }
}
```

--------------------------------

### Environment Variable Configuration

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Control the package's behavior using environment variables. Set `LARAVEL_CLOUDFLARE_ENABLED` to `false` to disable, and `LARAVEL_CLOUDFLARE_REPLACE_IP` to `true` to use the `Cf-Connecting-Ip` header.

```ini
# .env — disable in testing environments
LARAVEL_CLOUDFLARE_ENABLED=false
LARAVEL_CLOUDFLARE_REPLACE_IP=true
```

--------------------------------

### Replace TrustProxies Middleware

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Configure your Laravel application to use the package's TrustProxies middleware by replacing the default one in `bootstrap/app.php`. This ensures Cloudflare IPs are recognized.

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

--------------------------------

### CloudflareProxies::load() — Fetch IP Blocks

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Fetches Cloudflare's IPv4 and/or IPv6 address ranges from their public endpoints. Accepts a bitmask flag to select which IP versions to retrieve. Throws `UnexpectedValueException` if the HTTP request to Cloudflare fails.

```APIDOC
## `CloudflareProxies::load()` — Fetch IP Blocks

Fetches Cloudflare's IPv4 and/or IPv6 address ranges from their public endpoints. Accepts a bitmask flag to select which IP versions to retrieve. Throws `UnexpectedValueException` if the HTTP request to Cloudflare fails.

### Usage

```php
use Monicahq\Cloudflare\CloudflareProxies;
use Monicahq\Cloudflare\Facades\CloudflareProxies as CloudflareProxiesFacade;

// Via facade — load all IP blocks (IPv4 + IPv6, the default)
$allProxies = CloudflareProxiesFacade::load();
// e.g. ['173.245.48.0/20', '103.21.244.0/22', ..., '2400:cb00::/32', ...]

// Load only IPv4 blocks
$ipv4Proxies = CloudflareProxiesFacade::load(CloudflareProxies::IP_VERSION_4);
// e.g. ['173.245.48.0/20', '103.21.244.0/22', '103.22.200.0/22', ...]

// Load only IPv6 blocks
$ipv6Proxies = CloudflareProxiesFacade::load(CloudflareProxies::IP_VERSION_6);
// e.g. ['2400:cb00::/32', '2606:4700::/32', '2803:f800::/32', ...]

// Via direct instantiation (useful in tests with Http::fake())
$loader = app(CloudflareProxies::class);
try {
    $proxies = $loader->load(CloudflareProxies::IP_VERSION_ANY);
} catch (\UnexpectedValueException $e) {
    // Cloudflare endpoint unreachable
    logger()->error('Could not refresh Cloudflare proxies: ' . $e->getMessage());
    $proxies = [];
}
```

### Parameters

- **$ipVersion** (int) - Optional - A bitmask flag to select which IP versions to retrieve. Defaults to `CloudflareProxies::IP_VERSION_ANY` (both IPv4 and IPv6).

### Returns

- `array` - An array of IP address ranges in CIDR notation.
```

--------------------------------

### Mock Cloudflare IP Endpoints for Testing

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Mock Cloudflare endpoints to simulate responses for IP address ranges. This is useful for testing how your application handles Cloudflare IPs without making actual network calls. Ensure the `Http` facade is imported.

```php
use Illuminate\Support\Facades\Http;
use Monicahq\Cloudflare\CloudflareProxies;

Http::fake([
    'https://www.cloudflare.com/ips-v4' => Http::response("173.245.48.0/20\n103.21.244.0/22", 200),
    'https://www.cloudflare.com/ips-v6' => Http::response("2400:cb00::/32\n2606:4700::/32", 200),
]);

$loader  = app(CloudflareProxies::class);
$proxies = $loader->load();
// ['173.245.48.0/20', '103.21.244.0/22', '2400:cb00::/32', '2606:4700::/32']
```

```php
// Test that a 500 from Cloudflare throws correctly:
Http::fake(['https://www.cloudflare.com/ips-v4' => Http::response('', 500)]);
$this->expectException("UnexpectedValueException");
$loader->load(CloudflareProxies::IP_VERSION_4);
```

--------------------------------

### Artisan Command: Reload Cloudflare IPs

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Manually refreshes the cached Cloudflare IP blocks. This command respects the `laravelcloudflare.enabled` configuration and should be scheduled daily to ensure proxy addresses are up-to-date.

```bash
# Manually refresh cached IP blocks
php artisan cloudflare:reload
# Output: Cloudflare's IP blocks have been reloaded.
```

```php
// routes/console.php — schedule automatic daily refresh
use Illuminate\Support\Facades\Schedule;

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

// Or run at a specific time to avoid peak traffic periods
Schedule::command('cloudflare:reload')->dailyAt('03:00');
```

--------------------------------

### Schedule Daily Cache Refresh

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Automate the cache refresh by adding the `cloudflare:reload` command to your Laravel application's scheduler in `routes/console.php`.

```php
use Illuminate\Support\Facades\Schedule;

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

--------------------------------

### Disable Package for Testing

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Temporarily disable the `laravel-cloudflare` middleware during package testing by setting the `LARAVEL_CLOUDFLARE_ENABLED` environment variable to `false` in your `.env` or `phpunit.xml` file.

```bash
LARAVEL_CLOUDFLARE_ENABLED=false
```

--------------------------------

### Retrieve Current Proxy List

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Returns the current list of trusted proxy IPs. This method is used internally by the middleware and can be called to inspect the active proxy list.

```php
use Monicahq\Cloudflare\LaravelCloudflare;

// Returns proxy list from the registered callback, or falls back to CloudflareProxies::load()
$proxies = LaravelCloudflare::getProxies();
// e.g. ['173.245.48.0/20', '103.21.244.0/22', ..., '2400:cb00::/32', ...]

// Useful for debugging which proxies are currently active:
foreach (LaravelCloudflare::getProxies() as $cidr) {
    echo $cidr . PHP_EOL;
}
```

--------------------------------

### LaravelCloudflare::getProxiesUsing() — Custom Proxy Callback

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Registers a custom `Closure` that replaces the default `CloudflareProxies::load()` call when the middleware needs to resolve the list of trusted IPs. Pass `null` to reset to the default behavior. Typically called in `AppServiceProvider::boot()`.

```APIDOC
## `LaravelCloudflare::getProxiesUsing()` — Custom Proxy Callback

Registers a custom `Closure` that replaces the default `CloudflareProxies::load()` call when the middleware needs to resolve the list of trusted IPs. Pass `null` to reset to the default behavior. Typically called in `AppServiceProvider::boot()`.

### Usage

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

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Example 1: Load only IPv4 proxies instead of both versions
        LaravelCloudflare::getProxiesUsing(
            fn () => CloudflareProxies::load(\Monicahq\Cloudflare\CloudflareProxies::IP_VERSION_4)
        );

        // Example 2: Merge Cloudflare ranges with your own internal proxy IPs
        LaravelCloudflare::getProxiesUsing(function () {
            $cloudflare = CloudflareProxies::load();
            $internal   = ['10.0.0.0/8', '192.168.1.0/24'];
            return array_merge($cloudflare, $internal);
        });

        // Example 3: Use a static list (e.g., in CI/testing environments)
        if (app()->environment('testing')) {
            LaravelCloudflare::getProxiesUsing(fn () => ['127.0.0.1']);
        }
    }
}

// Reset to default behavior at any point:
LaravelCloudflare::getProxiesUsing(null);
```

### Parameters

- **$callback** (callable|null) - A `Closure` that returns an array of proxy IP ranges, or `null` to reset to the default behavior.
```

--------------------------------

### Refresh Cloudflare IP Cache

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/README.md

Use the `cloudflare:reload` Artisan command to refresh the cached Cloudflare IP blocks. This is recommended to ensure you always have up-to-date proxy information.

```bash
php artisan cloudflare:reload
```

--------------------------------

### LaravelCloudflare::getProxies() — Retrieve Current Proxy List

Source: https://context7.com/monicahq/laravel-cloudflare/llms.txt

Returns the current trusted proxy IP list, either from the registered custom callback or the default `CloudflareProxies::load()` call. This is the method called internally by the middleware.

```APIDOC
## `LaravelCloudflare::getProxies()` — Retrieve Current Proxy List

Returns the current trusted proxy IP list, either from the registered custom callback or the default `CloudflareProxies::load()` call. This is the method called internally by the middleware.

### Usage

```php
use Monicahq\Cloudflare\LaravelCloudflare;

// Returns proxy list from the registered callback, or falls back to CloudflareProxies::load()
$proxies = LaravelCloudflare::getProxies();
// e.g. ['173.245.48.0/20', '103.21.244.0/22', ..., '2400:cb00::/32', ...]

// Useful for debugging which proxies are currently active:
foreach (LaravelCloudflare::getProxies() as $cidr) {
    echo $cidr . PHP_EOL;
}
```

### Returns

- `array` - An array of IP address ranges in CIDR notation.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.