README

Laravel Trusted Proxies

Laravel trusted proxies configuration for applications behind CDNs, load balancers, or Docker networks.

Why This Package?

Laravel has built-in support for trusted proxies, but configuring it correctly for real-world infrastructure — especially when combining a CDN with Docker Swarm — requires non-trivial setup across multiple files.

This package solves that with a single .env variable:

TRUSTED_PROXY_PROVIDERS=cloudflare,docker

That's it. No middleware changes, no PHP configuration files, no hardcoded IP lists to maintain.

What it does that Laravel doesn't out of the box

Multi-provider orchestration — declare multiple providers (cloudflare, aws_cloudfront, fastly, docker) and the package merges their IP ranges automatically
Dynamic Cloudflare IPs — Cloudflare IP ranges are fetched from the official API and cached via monicahq/laravel-cloudflare, so they never go stale
Docker Swarm aware — includes the Docker internal network ranges (10.0.0.0/8, 172.16.0.0/12) needed when the Swarm ingress acts as an internal proxy
Environment-based — different providers per environment (local, staging, production) without touching PHP code

What it does not do

It does not replace or wrap Laravel's TrustProxies middleware. It configures Request::setTrustedProxies() directly, letting Symfony's battle-tested header resolution handle everything.

Features

Multiple CDN Support — Cloudflare (dynamic), AWS CloudFront, Fastly
Docker Swarm Ready — handles Docker ingress networks and overlay networks
Environment-Based Config — different settings for dev, staging, production
Custom Proxy Support — add your own load balancers or reverse proxies
Zero Configuration — works out of the box with sensible defaults
Laravel Native — uses Laravel's built-in Request::setTrustedProxies()

Requirements

PHP >= 8.2
Laravel Illuminate/Support ^10.0 | ^11.0 | ^12.0 | ^13.0
Laravel Illuminate/HTTP ^10.0 | ^11.0 | ^12.0 | ^13.0

Installation

1. Install the package

composer require laravel-foundry/trusted-proxies

The package auto-registers via Laravel's service provider discovery.

2. Configure environment variables

Add to your .env file:

# Development (local Docker)
TRUSTED_PROXY_PROVIDERS=docker

# Staging (Docker + Cloudflare)
TRUSTED_PROXY_PROVIDERS=cloudflare,docker

# Production (Docker Swarm + Cloudflare)
TRUSTED_PROXY_PROVIDERS=cloudflare,docker

That's it. The package will automatically configure trusted proxies on every request.

Configuration

Environment Variables

# Comma-separated list of providers
TRUSTED_PROXY_PROVIDERS=cloudflare,docker

# Custom IP ranges (optional)
TRUSTED_PROXY_CUSTOM_RANGES=10.20.0.0/16,192.168.100.5

Available Providers

Provider	Description	IP Source
`cloudflare`	Cloudflare CDN	Dynamic via API (cached)
`aws_cloudfront`	AWS CloudFront CDN	Static ranges
`fastly`	Fastly CDN	Static ranges
`docker`	Docker networks (bridge, custom, Swarm ingress)	Static ranges

Publish Configuration (Optional)

For advanced customization, publish the config file:

php artisan vendor:publish --tag=trustedproxies-config

This creates config/trustedproxies.php where you can customize settings.

Usage

Basic Usage

After installation, Laravel automatically gets the real client IP:

// Get real client IP (not proxy IP)
$clientIp = request()->ip();

Environment-Specific Configurations

Local Development

TRUSTED_PROXY_PROVIDERS=docker

Staging

TRUSTED_PROXY_PROVIDERS=cloudflare,docker

Production with Docker Swarm

TRUSTED_PROXY_PROVIDERS=cloudflare,docker

Important: Always keep docker enabled in production when using Docker Swarm. The Swarm ingress network acts as an internal proxy, so without trusting Docker IP ranges the real client IP cannot be resolved correctly even when Cloudflare provides it in CF-Connecting-IP.

Custom Load Balancer

TRUSTED_PROXY_PROVIDERS=cloudflare,docker
TRUSTED_PROXY_CUSTOM_RANGES=10.20.0.0/16

Multiple CDN Providers

TRUSTED_PROXY_PROVIDERS=cloudflare,fastly,docker

Common Use Cases

Rate Limiting

use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(60)->by($request->ip());
});

IP Whitelisting

namespace App\Http\Middleware;

class IpWhitelist
{
    public function handle($request, $next)
    {
        $allowedIps = ['1.2.3.4', '5.6.7.8'];

        if (!in_array(request()->ip(), $allowedIps)) {
            abort(403, 'Access denied');
        }

        return $next($request);
    }
}

Logging Real IPs

use Illuminate\Support\Facades\Log;

Log::channel('daily')->info('User action', [
    'ip' => request()->ip(),
    'user_id' => auth()->id(),
    'action' => 'login',
]);

How It Works

Architecture

Internet → CDN (Cloudflare) → Your Server → Docker Swarm Ingress → Container
         ↓ adds CF-Connecting-IP              ↓ adds X-Forwarded-*

Package configures Laravel to:
1. Trust IPs from Cloudflare (dynamic) and Docker networks
2. Let Symfony resolve the real client IP from X-Forwarded-For
3. request()->ip() returns the real client IP

Why Trust Docker in Production?

With Docker Swarm, requests flow through the ingress network before reaching your container:

Client → Cloudflare → Your VPS → Swarm Ingress (10.0.x.x) → Container

Without trusting Docker IPs, you'd see the ingress IP (10.0.x.x) instead of the real client IP. Cloudflare sends the real IP in CF-Connecting-IP, but you still need to trust the ingress network for Symfony to process the forwarded headers correctly.

Cloudflare IP Ranges

Cloudflare IP ranges are resolved dynamically at runtime via monicahq/laravel-cloudflare, which fetches them from https://www.cloudflare.com/ips-v4 and ips-v6 and stores them in Laravel's cache. You should schedule a periodic cache refresh to keep them up to date:

php artisan cloudflare:reload

Or via Laravel scheduler in routes/console.php:

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

Troubleshooting

Still seeing proxy IPs?

// In tinker or any PHP file
$service = app(\LaravelFoundry\TrustedProxies\Service\TrustedProxyService::class);

var_dump(config('trustedproxies.providers'));
var_dump($service->getTrustedProxies());
var_dump(request()->ip());

Docker Swarm issues?

# Check the ingress network
docker network inspect ingress

# Check your container's networks
docker inspect <container-id> | grep -A 20 Networks

Testing

composer test

More info

See here.

Changelog

Please see CHANGELOG for a detailed list of changes for each release.

We follow Semantic Versioning and use Conventional Commits to automatically generate our changelog.

Release Process

Major versions (1.0.0 → 2.0.0): Breaking changes
Minor versions (1.0.0 → 1.1.0): New features, backward compatible
Patch versions (1.0.0 → 1.0.1): Bug fixes, backward compatible

All releases are automatically created when changes are pushed to the main branch, based on commit message conventions.

Contributing

For your contributions please use:

See CONTRIBUTING for detailed guidelines.

Sponsor

License

(ɔ) Copyleft 2026 Frugan.
GNU GPLv3, see LICENSE file.

laravel-foundry / trusted-proxies

Maintainers

Package info

Fund package maintenance!

Statistics

Security