Laravel Any Trusted Proxies

Easily configurable any popular, custom, or niche proxy providers for Laravel.

A Laravel package for dynamic loading of trusted proxy IPs from multiple CDN and proxy providers: Cloudflare, Fastly, AWS CloudFront, Gcore, Bunny CDN, CDNvideo, Megafon — and any custom provider you add.

📖 Русская версия

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Publishing Configuration
• Middleware Setup
  • Laravel 11+
  • Laravel 10
• Configuration
  • Environment Variables
  • Options Reference
  • Available Providers
• IP Address Formats
• Cache Safety
• Available Commands
• Scheduler Setup
• Architecture
• Adding a Custom Provider
• Testing
• License

Features

• Pick any providers — enable only the ones you need via a single .env variable
• 7 built-in providers: Cloudflare, Fastly, AWS CloudFront, Gcore, Bunny CDN, CDNvideo, Megafon
• Custom provider support — add your own or niche providers via the IpProvider interface
• HTTP retries via Http::retry with configurable attempts and delay
• Safe cache refresh: if any provider fails, the existing cache is preserved — partial results are never saved
• Middleware that injects trusted proxy IPs at runtime — replaces the stock TrustProxies middleware
• Artisan command for manual/scheduled cache refresh
• CIDR and plain IP support — transparently works with both formats

Requirements

Installation

composer require myscode/laravel-any-trusted-proxies

The package uses Laravel auto-discovery — the ServiceProvider is registered automatically.

Quick Start

1. Add to your .env the providers you want to enable:

TRUSTED_PROXIES=cloudflare,fastly

1. Register the middleware in bootstrap/app.php (Laravel 11+):

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

1. Done! The trusted proxy IPs will be fetched, cached, and applied automatically.

If TRUSTED_PROXIES is left empty, no providers are loaded — the middleware will have an empty proxy list.

Publishing Configuration

php artisan vendor:publish --tag=trusted-proxy-config

After publishing, the file will be placed at config/trusted-proxy.php. You can add custom providers, change TTL, or tweak retry settings.

Middleware Setup

The package provides its own middleware Myscode\AnyTrustedProxies\Http\Middleware\TrustProxies that replaces the stock Illuminate\Http\Middleware\TrustProxies.

Laravel 11+

In bootstrap/app.php:

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

Laravel 10

In app/Http/Kernel.php:

protected $middleware = [
    // ...
    \Myscode\AnyTrustedProxies\Http\Middleware\TrustProxies::class,
];

Configuration

Environment Variables

All configuration can be done through .env:

# Comma-separated list of providers to enable (leave empty to disable all)
TRUSTED_PROXIES=cloudflare,fastly,aws_cloudfront

# Cache key (optional, default: trusted_proxy_ips)
TRUSTED_PROXY_CACHE_KEY=trusted_proxy_ips

# Cache TTL in seconds (optional, default: 604800 = 7 days)
TRUSTED_PROXY_TTL=604800

# HTTP retry attempts (optional, default: 3)
TRUSTED_PROXY_RETRY_TIMES=3

# HTTP retry delay in ms (optional, default: 200)
TRUSTED_PROXY_RETRY_SLEEP=200

Options Reference

The headers value is a bitmask from Illuminate\Http\Request:

Available Providers

IP Address Formats

The package does not validate or transform IP addresses on its own — it passes them "as is" to Laravel's standard middleware. Verification happens at the framework level via Symfony's IpUtils::checkIp().

Both formats are supported:

Cache Safety

• On refresh/load, the list is cached only if all enabled providers succeed
• If any provider fails, the existing cache is used (if available), so the application never loses its trusted proxies
• Partial results on failure are never saved — this prevents a scenario where a single failed provider removes its IPs from the trusted list
• All IPs are deduplicated across providers

Available Commands

any-trustedproxy:reload

Force-refreshes the trusted proxy list from all enabled providers:

php artisan any-trustedproxy:reload

Output:

Trusted proxies refreshed. Count: 42

Exit codes:

• 0 (SUCCESS) — refresh completed successfully

Scheduler Setup

In routes/console.php:

use Illuminate\Support\Facades\Schedule;

Schedule::command('any-trustedproxy:reload')->weekly();
// or: ->daily(), ->twiceDaily(), ->everySixHours()

Architecture

┌─────────────────────────────────────────────┐
│                  .env                        │
│        TRUSTED_PROXIES=cloudflare,fastly     │
└──────────────────┬──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│  ServiceProvider                             │
│  ┌───────────────────────────────────────┐  │
│  │  Read enabled[] from config           │  │
│  │  Filter providers map by enabled      │  │
│  │  Instantiate only selected providers  │  │
│  └───────────────┬───────────────────────┘  │
└──────────────────┼──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│               HTTP Request                   │
└────────────────┬────────────────────────────┘
                 ▼
┌─────────────────────────────────────────────┐
│  Middleware: TrustProxies                    │
│  ┌───────────────────────────────────────┐  │
│  │  $this->proxies = TrustedProxy::load()│  │
│  │  $this->headers = config(...)         │  │
│  └───────────────┬───────────────────────┘  │
└──────────────────┼──────────────────────────┘
                   ▼
┌─────────────────────────────────────────────┐
│  Facade: TrustedProxy                       │
│  ┌───────────────────────────────────────┐  │
│  │  IpCacheManager                       │  │
│  │  ┌─────────────────────────────────┐  │  │
│  │  │  Cache::get(cache_key)          │  │  │
│  │  │  ├── hit  → return cached       │  │  │
│  │  │  └── miss → fetchFromProviders  │  │  │
│  │  └──────────────┬──────────────────┘  │  │
│  └─────────────────┼─────────────────────┘  │
└────────────────────┼────────────────────────┘
                     ▼
┌─────────────────────────────────────────────┐
│  IpProvider[] (only enabled)                 │
│  ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │Cloudflare│ │  Fastly  │ │   Gcore    │  │
│  │ getIps() │ │ getIps() │ │  getIps()  │  │
│  └────┬─────┘ └────┬─────┘ └─────┬──────┘  │
│       └─────────────┴─────────────┘          │
│                     │                        │
│              array_merge +                   │
│              array_unique                    │
│                     ▼                        │
│              Cache::put()                    │
└─────────────────────────────────────────────┘

Key Components

Adding a Custom Provider

Implement the IpProvider interface and optionally use the FetchesWithRetry trait:

<?php

namespace App\TrustedProxies;

use Myscode\AnyTrustedProxies\Contracts\IpProvider;
use Myscode\AnyTrustedProxies\Services\Concerns\FetchesWithRetry;

class MyCdnProvider implements IpProvider
{
    use FetchesWithRetry;

    public function getIps(): array
    {
        // Option 1: JSON API
        $data = $this->getJsonWithRetry('https://api.mycdn.com/public-ips');
        return collect($data['ip_ranges'] ?? [])
            ->pluck('subnet')
            ->filter()
            ->values()
            ->all();

        // Option 2: Plain text (one IP per line)
        // return $this->getTextLinesWithRetry('https://mycdn.com/ips.txt');

        // Option 3: Static list
        // return ['10.0.0.0/8', '172.16.0.0/12'];
    }
}

Register it in config/trusted-proxy.php and .env:

// config/trusted-proxy.php
'providers' => [
    // ...built-in providers...
    'my_cdn' => \App\TrustedProxies\MyCdnProvider::class,
],

# .env
TRUSTED_PROXIES=cloudflare,fastly,my_cdn

Implementation Guidelines

• getIps() must return a flat array of strings — CIDR (10.0.0.0/8) or plain IP (192.168.1.1)
• Do not throw exceptions — IpCacheManager catches \Throwable and logs the error without breaking other providers
• Use the FetchesWithRetry trait for automatic retries according to your retry settings
• Filter out empty values — use array_filter on the result

Testing

composer install
composer test
composer test-coverage   # with coverage

Tests use Orchestra Testbench. HTTP requests are mocked via Http::fake().

License

MIT License — see LICENSE.