Laravel Cloudflare

https://github.com/monicahq/laravel-cloudflare
Admin
A Laravel package that automatically adds Cloudflare IP addresses to trusted proxies for proper...
Tokens:17,545
Snippets:134
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Basic load example

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/CloudflareProxies.md

Resolves CloudflareProxies from the container and loads all IP blocks. Iterates over the returned array and echoes each CIDR block.

```php
use Monicahq\Cloudflare\CloudflareProxies;

$loader = $this->app->make(CloudflareProxies::class);
$ips = $loader->load();

foreach ($ip in $ips) {
    echo $ip; // e.g. "173.245.48.0/20"
}
```

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

### Install callback in AppServiceProvider boot method

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Installs a callback in the boot() method of an AppServiceProvider to keep the default proxy loader while making the indirection explicit. This is the typical usage shown in the package README.

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

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // Keep the default loader, but make the indirection explicit:
        LaravelCloudflare::getProxiesUsing(fn () => CloudflareProxies::load());
    }
}
```

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

### Install laravel-cloudflare via Composer

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

Install the package using Composer.

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

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

### Basic usage with warm cache

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Comment-only example showing the standard path when the cache is warm from `php artisan cloudflare:reload`.

```php
// With the middleware installed and a cache warm from `php artisan cloudflare:reload`:
// Request handling automatically merges:
//   parent::$alwaysTrustProxies + cached Cloudflare blocks (unique) -> request trusted proxies
```

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

### Basic facade load example

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Facades-CloudflareProxies.md

Basic usage of the facade to load all Cloudflare proxy IP blocks without manually resolving the container.

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

$proxies = CloudflareProxies::load();

```

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

### getProxies() with getProxiesUsing() callback

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Shows installing a custom callback with getProxiesUsing() to return static CIDR blocks, then clearing it with null to restore the default CloudflareProxies::load() behavior.

```php
use Monicahq\Cloudflare\LaravelCloudflare;

// Install a custom strategy returning static blocks:
LaravelCloudflare::getProxiesUsing(fn () => [
    '173.245.48.0/20',
    '::1/32',
]);

$proxies = LaravelCloudflare::getProxies(); // => the static list above

// Restore the default behavior:
LaravelCloudflare::getProxiesUsing(null);
$proxies = LaravelCloudflare::getProxies(); // => CloudflareProxies::load()
```

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

### Error handling for cloudflare:reload

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Example of wrapping the reload logic in a custom command to handle UnexpectedValueException and keep previous blocks.

```php
use Illuminate\Console\Command;
use Illuminate\Contracts\Cache\Factory as Cache;
use Illuminate\Contracts\Config\Repository as Config;
use Monicahq\Cloudflare\LaravelCloudflare;
use UnexpectedValueException;

class ReloadCloudflare extends Command
{
    protected $signature = 'cloudflare:reload-safe';

    public function handle(Cache $cache, Config $config): void
    {
        try {
            $proxies = LaravelCloudflare::getProxies();
        } catch (UnexpectedValueException $e) {
            $this->error('Cloudflare unreachable, keeping previous blocks.');
            return;
        }
        $cache->store()->forever($config->get('laravelcloudflare.cache'), $proxies);
    }
}
```

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

### Direct getProxies() usage

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Direct use of getProxies() without installing a callback. Returns the default CloudflareProxies::load() result with IP_VERSION_ANY.

```php
use Monicahq\Cloudflare\LaravelCloudflare;

$proxies = LaravelCloudflare::getProxies();
// With no callback installed: equivalent to CloudflareProxies::load(IP_VERSION_ANY)
```

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

### getProxies()

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Returns the list of Cloudflare CIDR blocks. If a custom callback has been installed via `getProxiesUsing()`, its return value is used; otherwise, the default `CloudflareProxies::load()` strategy is used.

```APIDOC
## getProxies()

### Description
Returns the list of Cloudflare CIDR blocks. If a custom callback has been installed via `getProxiesUsing()`, its return value is used; otherwise, the default `CloudflareProxies::load()` strategy is used.

### Method
`getProxies` (static method)

### Endpoint
`LaravelCloudflare::getProxies()`

### Parameters
None.

### Return Type
`array` — the list of Cloudflare CIDR blocks.

### Throws
- `UnexpectedValueException` — Only when the default strategy is in effect and the underlying HTTP load fails; propagated from `CloudflareProxies::retrieve()`.

### Example
```php
use Monicahq\Cloudflare\LaravelCloudflare;

$proxies = LaravelCloudflare::getProxies();
// With no callback installed: equivalent to CloudflareProxies::load(IP_VERSION_ANY)
```
```

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

### Expected table output

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Expected table output shape of the cloudflare:view command, showing the Address column with example IP blocks.

```text
┌───────────────────┐
│ Address           │
├───────────────────┤
│ 173.245.48.0/20   │
│ ::1/32            │
└───────────────────┘
```

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

### Example usage of setRemoteAddr

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Shows how setRemoteAddr overwrites REMOTE_ADDR with the Cf-Connecting-Ip header value. Requires config('laravelcloudflare.replace_ip') to be true.

```php
// With config('laravelcloudflare.replace_ip' => true):

$request = new Request;
$request->server->set('REMOTE_ADDR', '127.0.0.1');
$request->headers->set('Cf-Connecting-Ip', '127.0.1.1');

$this->app->make(TrustProxies::class)->handle($request, fn () => null);

assert $request->ip() == '127.0.1.1'; // REMOTE_ADDR was overwritten
```

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

### getProxiesUsing()

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Installs or clears a custom callback that overrides the default proxy retrieval strategy. When set, `getProxies()` will return the callback's result instead of calling `CloudflareProxies::load()`.

```APIDOC
## getProxiesUsing()

### Description
Installs or clears a custom callback that overrides the default proxy retrieval strategy. When set, `getProxies()` will return the callback's result instead of calling `CloudflareProxies::load()`.

### Method
`getProxiesUsing` (static method)

### Endpoint
`LaravelCloudflare::getProxiesUsing($callback)`

### Parameters
- `$callback` (Closure|null) - Required - The callback to invoke when `getProxies()` is called. Pass `null` to clear the callback and restore the default behavior.

### Return Type
`void`

### Example
```php
use Monicahq\Cloudflare\LaravelCloudflare;

// Install a custom strategy returning static blocks:
LaravelCloudflare::getProxiesUsing(fn () => [
    '173.245.48.0/20',
    '::1/32',
]);

$proxies = LaravelCloudflare::getProxies(); // => the static list above

// Restore the default behavior:
LaravelCloudflare::getProxiesUsing(null);
$proxies = LaravelCloudflare::getProxies(); // => CloudflareProxies::load()
```
```

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

### getProxies method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Method signature for the static getProxies() method. Returns an array of Cloudflare CIDR blocks, either from the callback installed by getProxiesUsing() or from CloudflareProxies::load() when no callback is set.

```php
public static function getProxies(): array
```

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

### Testing the registration outcome

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/TrustedProxyServiceProvider.md

Assert that config, singleton binding, and commands are set up correctly.

```php
use Monicahq\Cloudflare\CloudflareProxies;
use Monicahq\Cloudflare\Facades\CloudflareProxies as Facade;
use Monicahq\Cloudflare\TrustedProxyServiceProvider;

// After an app built with TrustedProxyServiceProvider in getPackageProviders():
assert $this->app['config']['laravelcloudflare.url'] == 'https://www.cloudflare.com';
assert $this->app->bound(Facade::class);        // facade key is bound
assert $this->app->make(CloudflareProxies::class) === $this->app->make(CloudflareProxies::class); // singleton
```

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

### register method implementation

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/TrustedProxyServiceProvider.md

The register method merges the package config file, registers a singleton CloudflareProxies, and registers console commands when running in console.

```php
#[\Override]
public function register(): void
{
    $this->mergeConfigFrom(
        __DIR__.'/../config/laravelcloudflare.php', 'laravelcloudflare'
    );
    $this->app->singleton(Facades\CloudflareProxies::class, CloudflareProxies::class);

    if ($this->app->runningInConsole()) {
        $this->commands([
            Commands\Reload::class,
            Commands\View::class,
        ]);
    }
}
```

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

### boot method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/TrustedProxyServiceProvider.md

Bootstrap hook that delegates to registerPublishing(). Runs after register() during package bootstrapping.

```php
public function boot(): void
```

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

### Run cloudflare:view command

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Command to run the cloudflare:view artisan command.

```sh
php artisan cloudflare:view
```

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

### Facade docblock for load method

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Facades-CloudflareProxies.md

Docblock for the facade that documents the static load method for IDE support. The method is forwarded to the underlying CloudflareProxies instance.

```php
/**
 * @method static array load(int $type = \Monicahq\Cloudflare\CloudflareProxies::IP_VERSION_ANY)
 *
 * @see \Monicahq\Cloudflare\CloudflareProxies
 */

```

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

### getFacadeAccessor method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Facades-CloudflareProxies.md

Defines the container binding key for the facade. Returns the FQCN string 'Monicahq\Cloudflare\CloudflareProxies' so the facade resolves to the singleton registered by TrustedProxyServiceProvider.

```php
#[\Override]
protected static function getFacadeAccessor(): string

```

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

### handle(Request $request, Closure $next)

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Processes the incoming request, optionally overwriting REMOTE_ADDR with the Cf-Connecting-Ip header, then delegates to the parent middleware to continue the request lifecycle.

```APIDOC
## handle(Request $request, Closure $next)

### Description
Processes the incoming request, optionally overwriting REMOTE_ADDR with the Cf-Connecting-Ip header, then delegates to the parent middleware to continue the request lifecycle.

### Method
handle

### Endpoint
N/A (Middleware method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
use Illuminate\Http\Request;
use Monicahq\Cloudflare\Http\Middleware\TrustProxies;

$middleware = $this->app->make(TrustProxies::class);
$request = new Request;

$response = $middleware->handle($request, fn () => null);
```

### Response
#### Success Response (200)
- **response** (mixed) - The response from the next middleware/controller, returned by the parent handle method.

#### Response Example
```php
// After the call, the request knows its trusted proxies:
$proxies = $request->getTrustedProxies(); // => ['173.245.48.0/20', ...]
```

### Error Handling
- **HttpException** - May be raised by the parent middleware when the request's client address cannot be trusted/resolved.
- **UnexpectedValueException** - May propagate if setTrustedProxyCloudflare() triggers a first-time load that fails.

### Behavior
1. If `Config::get('laravelcloudflare.replace_ip') === true`, calls `setRemoteAddr($request)` to overwrite `REMOTE_ADDR` with the `Cf-Connecting-Ip` header value.
2. Delegates to `parent::handle($request, $next)`; the parent internally invokes the overridden `setTrustedProxyIpAddresses()` hook.
```

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

### CloudflareProxies::__construct

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/CloudflareProxies.md

Constructor for the CloudflareProxies class. Injects the configuration repository and HTTP client factory.

```APIDOC
## CloudflareProxies::__construct

### Description
Constructor for the CloudflareProxies class. Injects the configuration repository and HTTP client factory.

### Method
__construct

### Parameters
- `$config` (Illuminate\Contracts\Config\Repository) - Required - The application config repository; read from the `laravelcloudflare.*` keys.
- `$http` (Illuminate\Http\Client\Factory) - Required - HTTP client factory, declared for container injection.

### Notes
- The parameters use PHP promoted-property syntax (`protected Repository $config`), which stores them as instance properties.
- The `$http` property is injected but never referenced inside the class body: `retrieve()` performs the network call through the `Illuminate\Support\Facades\Http` facade (`Http::get($url)->throw()`). This is a behavior of the source as written; do not assume `$http` is used.
- Prefer resolving through the container (`$this->app->make(CloudflareProxies::class)`) rather than `new`. The container provides both `Repository` and `Http\Client\Factory`.
```

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

### View command signature and description

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Defines the console command signature and description for the cloudflare:view command.

```php
protected $signature = 'cloudflare:view';
protected $description = 'View list of trust proxies IPs stored in cache.';
```

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

### Constructor with promoted properties

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/CloudflareProxies.md

Defines the constructor for CloudflareProxies, injecting the config repository and HTTP client factory. The $http property is injected but not used; the class uses the Http facade instead.

```php
public function __construct(
    protected Repository $config,
    protected HttpClient $http
) {}
```

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

### load method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/CloudflareProxies.md

Declares the load method that accepts an optional bitmask for IP version filtering. The default is IP_VERSION_ANY, and the method returns an array of CIDR blocks.

```php
public function load(int $type = self::IP_VERSION_ANY): array
```

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

### Publish laravel-cloudflare config file

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

Publish the package config file to config/laravelcloudflare.php.

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

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

### Error handling with fallback in callback

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Wraps the proxy loading in a try-catch to degrade gracefully on failure, falling back to a static block list. The callback must return an array; here it returns the result of a custom loader or a fallback list.

```php
use Monicahq\Cloudflare\LaravelCloudflare;
use UnexpectedValueException;

LaravelCloudflare::getProxiesUsing(fn () {
    try {
        return require('app/cloudflare/loaders')->load('production');
    } catch (UnexpectedValueException $e) {
        // Fall back to a static, known-good block list.
        return ['173.245.48.0/20'];
    }
});
```

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

### IPv6-only load with error handling

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/CloudflareProxies.md

Loads only IPv6 blocks and catches UnexpectedValueException if the endpoint is unreachable. Logs the error message.

```php
use Monicahq\Cloudflare\CloudflareProxies;
use UnexpectedValueException;

$loader = $this->app->make(CloudflareProxies::class);

try {
    $ipv6 = $loader->load(CloudflareProxies::IP_VERSION_6);
} catch (UnexpectedValueException $e) {
    // Cloudflare's endpoint was unreachable or returned an error status.
    // Log the message and the wrapped previous exception:
    Log::error('cloudflare proxies unavailable: '.$e->getMessage());
}
```

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

### Replace TrustProxies middleware in bootstrap/app.php

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

Replace the default TrustProxies middleware with the Cloudflare version in bootstrap/app.php.

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

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

### getProxiesUsing method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Declares the static method that stores a callback to override the default proxy loading strategy. The callback must return an array and receives no arguments. Passing null clears the callback and reverts to the default CloudflareProxies::load() behavior.

```php
public static function getProxiesUsing(?Closure $callback): void
```

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

### Run cloudflare:reload via artisan

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Shell command to execute the cloudflare:reload artisan command.

```sh
php artisan cloudflare:reload
```

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

### Basic usage of TrustProxies handle method

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Direct invocation of the handle method to illustrate the signature. After the call, the request knows its trusted proxies, e.g., getTrustedProxies() returns ['173.245.48.0/20', ...].

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

$middleware = $this->app->make(TrustProxies::class);
$request = new Request;

$response = $middleware->handle($request, fn () => null);

// After the call, the request knows its trusted proxies:
$proxies = $request->getTrustedProxies(); // => ['173.245.48.0/20', ...]
```

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

### registerPublishing method

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/TrustedProxyServiceProvider.md

Publishes the package config file to the application's config directory under the tag 'laravelcloudflare-config' when running in console mode. Enables php artisan vendor:publish --provider="Monicahq\Cloudflare\TrustedProxyServiceProvider".

```php
private function registerPublishing(): void
{
    if ($this->app->runningInConsole()) {
        $this->publishes([
            __DIR__.'/../config/laravelcloudflare.php' => config_path('laravelcloudflare.php'),
        ], 'laravelcloudflare-config');
    }
}
```

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

### Manual registration in AppServiceProvider

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/TrustedProxyServiceProvider.md

Explicitly registers the package provider manually, useful if composer auto-registration is not used.

```php
use Illuminate\Support\ServiceProvider;
use Monicahq\Cloudflare\TrustedProxyServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Merge the package's own provider into the app.
        (new TrustedProxyServiceProvider($this->app))->register();
    }
}
```

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

### Custom strategy and cache behavior

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Shows using a custom proxy callback with LaravelCloudflare::getProxiesUsing, then handling a request and verifying the trusted proxies and cache.

```php
use Illuminate\Http\Request;
use Monicahq\Cloudflare\Http\Middleware\TrustProxies;
use Monicahq\Cloudflare\LaravelCloudflare;

LaravelCloudflare::getProxiesUsing(fn () => ['198.41.215.0/24']);

try {
    $request = new Request;
    $this->app->make(TrustProxies::class)->handle($request, fn () => null);
    // The request's trusted proxies now contain '198.41.215.0/24'.
    // Cache::has('cloudflare.proxies') === true, value === ['198.41.215.0/24'].
} finally {
    LaravelCloudflare::getProxiesUsing(null);
}
```

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

### Static property $getProxiesCallback

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Static property holding the callback used by getProxies() when set. Defaults to null, in which case the default CloudflareProxies::load() strategy is used.

```php
protected static $getProxiesCallback;
```

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

### cloudflare:view

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Prints the cached IP blocks as a CLI table. The command is affected by the laravelcloudflare.enabled config flag only through its own code as documented below.

```APIDOC
## cloudflare:view

### Description
Prints the cached IP blocks as a CLI table. The command is affected by the `laravelcloudflare.enabled` config flag only through its own code as documented below.

### Method
Console command

### Command
`php artisan cloudflare:view`

### Signature
`cloudflare:view`

### Description Property
(Not explicitly provided in the source text)

### Parameters
#### Injected Parameters (via handle method)
- **$cache** (Illuminate\Contracts\Cache\Factory) - Required - Cache factory; `$cache->store()` gives the cache repository.
- **$config** (Illuminate\Contracts\Config\Repository) - Required - Application config repository; read for `laravelcloudflare.enabled` and `laravelcloudflare.cache`.

### Behavior
(Not explicitly detailed in the source text, but the command prints the cached IP blocks as a CLI table.)

### Examples
Shell usage:
```sh
php artisan cloudflare:view
```
```

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

### IPv4 load with error handling

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Facades-CloudflareProxies.md

Loads only IPv4 proxies through the facade and catches UnexpectedValueException when the Cloudflare endpoint fails. The exception message is 'Failed to load trust proxies from Cloudflare server.'

```php
use Monicahq\Cloudflare\Facades\CloudflareProxies;
use UnexpectedValueException;

try {
    $ipv4 = CloudflareProxies::load(CloudflareProxies::IP_VERSION_4);
} catch (UnexpectedValueException $e) {
    // Cloudflare endpoint unreachable or returned a non-2xx status:
    // $e->getMessage() == 'Failed to load trust proxies from Cloudflare server.'
}

```

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

### Error handling for TrustProxies handle method

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Wraps the handle call in a try-catch to degrade gracefully when a Cloudflare outage causes an UnexpectedValueException on a cache miss. Logs the failure and falls back to the stock trust-proxy configuration.

```php
use Illuminate\Http\Request;
use Monicahq\Cloudflare\Http\Middleware\TrustProxies;
use UnexpectedValueException;

$middleware = $this->app->make(TrustProxies::class);

try {
    $middleware->handle($request, $next);
} catch (UnexpectedValueException $e) {
    // First request after a cache miss while Cloudflare's endpoint is down:
    // continue with the stock trust-proxy configuration, log the failure.
    log($e->getMessage());
    return parentClassHandle($request, $next);
}
```

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

### load method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Facades-CloudflareProxies.md

Signature of the load method as documented in the facade. Accepts an optional integer bitmask and returns an array of CIDR blocks.

```php
static array load(int $type = \Monicahq\Cloudflare\CloudflareProxies::IP_VERSION_ANY)

```

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

### LaravelCloudflare::getProxiesUsing

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/LaravelCloudflare.md

Static method to set a custom callback for loading Cloudflare proxies. The callback must return an array of proxy IPs. Pass null to clear the callback and revert to the default loader.

```APIDOC
## LaravelCloudflare::getProxiesUsing

### Description
Sets a custom callback for loading Cloudflare proxies. The callback is stored statically and affects all subsequent getProxies() calls. Pass null to clear the callback and revert to the default CloudflareProxies::load().

### Method
static

### Signature
`public static function getProxiesUsing(?Closure $callback): void`

### Parameters
- `$callback` (?Closure) - Required - The callback to store. Must return array. Pass null to clear the callback.

### Return Type
void

### Behavior
Assigns the callback to static state. The change is process-global and persists until cleared.

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

class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        LaravelCloudflare::getProxiesUsing(fn () => CloudflareProxies::load());
    }
}
```

### Error Handling Example
```php
use Monicahq\Cloudflare\LaravelCloudflare;
use UnexpectedValueException;

LaravelCloudflare::getProxiesUsing(fn () {
    try {
        return require('app/cloudflare/loaders')->load('production');
    } catch (UnexpectedValueException $e) {
        return ['173.245.48.0/20'];
    }
});
```

### Notes
- The callback state is static global state; tests and long-running processes must clear it with `getProxiesUsing(null)` when done.
```

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

### Custom proxies callback in AppServiceProvider

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

Define a custom proxies callback by calling LaravelCloudflare::getProxiesUsing() in the boot method of 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());
    }
}
```

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

### CloudflareProxies::load

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/CloudflareProxies.md

Loads Cloudflare IP address ranges based on the provided bitmask. Returns an array of CIDR blocks.

```APIDOC
## CloudflareProxies::load

### Description
Loads Cloudflare IP address ranges based on the provided bitmask. Returns an array of CIDR blocks.

### Method
load

### Parameters
- `$type` (int) - Optional - Default: `self::IP_VERSION_ANY` - Bitmask built from `IP_VERSION_4` and `IP_VERSION_6`. Each set bit triggers one HTTP request for the matching path.

### Return Type
`array` — a list of CIDR blocks (`string` values, e.g. `'173.245.48.0/20'` or `'::1/32'`), each being one non-empty line of the Cloudflare response body. Order: if both bits are set, all IPv4 blocks first, then all IPv6 blocks (`array_merge($proxies, $proxies6)`).

### Behavior
1. If the `IP_VERSION_4` bit is set, calls `retrieve($this->config->get('laravelcloudflare.ipv4-path'))`.
2. If the `IP_VERSION_6` bit is set, calls `retrieve($this->config->get('laravelcloudflare.ipv6-path'))` and merges the result.
3. Returns the merged arrays. With `$type = 0` no request is made and `[]` is returned.

### Throws
- `UnexpectedValueException` - Propagated from `retrieve()` when the HTTP GET fails or returns a non-success status.

### Examples
Basic call — resolve from the application container and load all blocks:

php
use Monicahq\Cloudflare\CloudflareProxies;

$loader = $this->app->make(CloudflareProxies::class);
$ips = $loader->load();

foreach ($ip in $ips) {
    echo $ip; // e.g. "173.245.48.0/20"
}


IPv6-only load with error handling:

php
use Monicahq\Cloudflare\CloudflareProxies;
use UnexpectedValueException;

$loader = $this->app->make(CloudflareProxies::class);

try {
    $ipv6 = $loader->load(CloudflareProxies::IP_VERSION_6);
} catch (UnexpectedValueException $e) {
    // Cloudflare's endpoint was unreachable or returned an error status.
    // Log the message and the wrapped previous exception:
    Log::error('cloudflare proxies unavailable: '.$e->getMessage());
}

```

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

### IP version bitmask constants

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/CloudflareProxies.md

Defines the bitmask constants for IP version selection. IP_VERSION_4 is 1, IP_VERSION_6 is 2, and IP_VERSION_ANY is 3 (the default). Passing 0 yields an empty array without an HTTP call.

```php
public const IP_VERSION_4 = 1 << 0;
public const IP_VERSION_6 = 1 << 1;
public const IP_VERSION_ANY = self::IP_VERSION_4 | self::IP_VERSION_6;
```

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

### Reload command signature and description

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Defines the artisan command signature and description for cloudflare:reload.

```php
protected $signature = 'cloudflare:reload';
protected $description = 'Reload trust proxies IPs and store in cache.';
```

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

### Reload command handle method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Method signature for the handle method of the Reload command, with injected Cache and Config dependencies.

```php
public function handle(Cache $cache, Config $config): void
```

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

### Default laravelcloudflare.php configuration

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

Default configuration file for the Laravel Cloudflare package. It defines the enabled flag, replace_ip option, cache key, base URL, and IPv4/IPv6 paths. The enabled and replace_ip options read from environment variables with defaults.

```php
return [

    'enabled' => (bool) env('LARAVEL_CLOUDFLARE_ENABLED', true),

    'replace_ip' => (bool) env('LARAVEL_CLOUDFLARE_REPLACE_IP', false),

    'cache' => 'cloudflare.proxies',

    'url' => 'https://www.cloudflare.com',

    'ipv4-path' => 'ips-v4',

    'ipv6-path' => 'ips-v6',

];
```

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

### setTrustedProxyIpAddresses method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Protected override method that is called by the parent handle() while computing the trusted-proxy set. It conditionally calls setTrustedProxyCloudflare and then delegates to the parent.

```php
#[\Override]
protected function setTrustedProxyIpAddresses(Request $request): void
```

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

### Catch UnexpectedValueException from CloudflareProxies::load()

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

Catch the UnexpectedValueException thrown by CloudflareProxies::load() when the Cloudflare server cannot be reached or returns a non-success status. The exception message is 'Failed to load trust proxies from Cloudflare server.' and the original HTTP failure is available via getPrevious().

```php
use Monicahq\Cloudflare\CloudflareProxies;
use UnexpectedValueException;

try {
    $proxies = $this->app->make(CloudflareProxies::class)->load();
} catch (UnexpectedValueException $e) {
    // $e->getMessage() === 'Failed to load trust proxies from Cloudflare server.'
    // The original HTTP failure is the previous exception (getPrevious()).
}
```

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

### Schedule cloudflare:reload daily

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Schedules the cloudflare:reload command to run daily using Laravel's console scheduler.

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

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

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

### cloudflare:reload

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Console-Commands.md

Fetches the current Cloudflare IP blocks and stores them forever in the application cache. If the laravelcloudflare.enabled config is false, the command does nothing.

```APIDOC
## cloudflare:reload

### Description
Fetches the current Cloudflare IP blocks and stores them forever in the application cache. If the `laravelcloudflare.enabled` config is false, the command does nothing.

### Method
Console command

### Command
`php artisan cloudflare:reload`

### Signature
`cloudflare:reload`

### Description Property
`Reload trust proxies IPs and store in cache.`

### Parameters
#### Injected Parameters (via handle method)
- **$cache** (Illuminate\Contracts\Cache\Factory) - Required - Cache factory; `$cache->store()` gives the cache repository.
- **$config** (Illuminate\Contracts\Config\Repository) - Required - Application config repository; read for `laravelcloudflare.enabled` and `laravelcloudflare.cache`.

### Behavior
1. If `(bool) $config->get('laravelcloudflare.enabled')` is falsy, returns immediately — nothing is fetched, nothing cached, no output.
2. Otherwise:
   - `$proxies = LaravelCloudflare::getProxies();` — uses the strategy installed via `LaravelCloudflare::getProxiesUsing()`, defaulting to `CloudflareProxies::load()`.
   - `$cache->store()->forever($config->get('laravelcloudflare.cache'), $proxies);` — writes the block list to the cache key from `laravelcloudflare.cache` with no expiry.
   - Prints `Cloudflare's IP blocks have been reloaded.` via `$this->info(...)`.

### Throws
- **UnexpectedValueException** - When the default strategy performs the HTTP fetch and Cloudflare's endpoint fails. Propagated through `LaravelCloudflare::getProxies()` → `CloudflareProxies::retrieve()`. Nothing is cached in that case because the exception unwinds before `forever()` runs.

### Examples
Shell usage:
```sh
php artisan cloudflare:reload
```

Scheduled refresh via the console scheduler:
```php
use Illuminate\Support\Facades\Schedule;

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

Error handling — wrap in your own command/console task to be resumable:
```php
use Illuminate\Console\Command;
use Illuminate\Contracts\Cache\Factory as Cache;
use Illuminate\Contracts\Config\Repository as Config;
use Monicahq\Cloudflare\LaravelCloudflare;
use UnexpectedValueException;

class ReloadCloudflare extends Command
{
    protected $signature = 'cloudflare:reload-safe';

    public function handle(Cache $cache, Config $config): void
    {
        try {
            $proxies = LaravelCloudflare::getProxies();
        } catch (UnexpectedValueException $e) {
            $this->error('Cloudflare unreachable, keeping previous blocks.');
            return;
        }
        $cache->store()->forever($config->get('laravelcloudflare.cache'), $proxies);
    }
}
```
```

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

### Merge Cloudflare proxies into trusted set

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Merges the cached Cloudflare proxy blocks with the parent's always-trusted proxies, deduplicates, and sets the result as the trusted proxies.

```php
parent::at(collect((array) parent::$alwaysTrustProxies)
    ->merge($cachedProxies)
    ->unique()
    ->toArray()
);
```

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

### setTrustedProxyCloudflare method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

The protected method signature for setTrustedProxyCloudflare, which takes a Request object and returns void.

```php
protected function setTrustedProxyCloudflare(Request $request): void
```

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

### Disable Cloudflare middleware in tests

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

Disable the Cloudflare middleware during tests by setting this environment variable in .env or phpunit.xml.

```env
LARAVEL_CLOUDFLARE_ENABLED=false
```

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

### setRemoteAddr method signature

Source: https://github.com/monicahq/laravel-cloudflare/blob/main/_autodocs/api-reference/Http-Middleware-TrustProxies.md

Protected method signature that mutates the request's server parameters. It is invoked when the laravelcloudflare.replace_ip config is true.

```php
protected function setRemoteAddr(Request $request): void
```
Tokens:
Raw