PHPackages                             laravel-foundry/trusted-proxies - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. laravel-foundry/trusted-proxies

ActiveLibrary[DevOps & Deployment](/categories/devops)

laravel-foundry/trusted-proxies
===============================

Laravel trusted proxies configuration for applications behind CDNs, load balancers, or Docker networks. Supports Cloudflare, AWS CloudFront, Fastly, Docker Swarm, and custom proxies.

v0.2.1(2mo ago)041[2 PRs](https://github.com/laravel-foundry/trusted-proxies/pulls)GPL-3.0-or-laterPHPPHP >=8.2CI passing

Since Jan 23Pushed 2mo agoCompare

[ Source](https://github.com/laravel-foundry/trusted-proxies)[ Packagist](https://packagist.org/packages/laravel-foundry/trusted-proxies)[ Docs](https://github.com/laravel-foundry/trusted-proxies)[ Fund](https://buymeacoff.ee/frugan)[ RSS](/packages/laravel-foundry-trusted-proxies/feed)WikiDiscussions main Synced today

READMEChangelog (3)Dependencies (13)Versions (6)Used By (0)

[![PHP Version](https://camo.githubusercontent.com/908e533f4eb14b1906126f99c4d7cfbe3e38ba1b9d5ccfa09b9a2534c0c3cac1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)](https://camo.githubusercontent.com/908e533f4eb14b1906126f99c4d7cfbe3e38ba1b9d5ccfa09b9a2534c0c3cac1/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)[![Packagist Downloads](https://camo.githubusercontent.com/77059bd05fefe5c91b052475b455295aeaade0593c86c8699307527230263752/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)](https://camo.githubusercontent.com/77059bd05fefe5c91b052475b455295aeaade0593c86c8699307527230263752/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)[![Packagist Stars](https://camo.githubusercontent.com/bdc25b8399aaf6701229cd0fbbbff52f4dd99a7bd1ceecd63ec26b76b4324717/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)](https://camo.githubusercontent.com/bdc25b8399aaf6701229cd0fbbbff52f4dd99a7bd1ceecd63ec26b76b4324717/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f73746172732f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)[![GitHub Actions Workflow Status](https://github.com/laravel-foundry/trusted-proxies/actions/workflows/release.yml/badge.svg)](https://github.com/laravel-foundry/trusted-proxies/actions/workflows/release.yml/badge.svg)[![Coverage Status](https://camo.githubusercontent.com/73667671c30256b6f1e523466a8c6e591ea03e7e74d369927a1d16a7f521701d/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)](https://camo.githubusercontent.com/73667671c30256b6f1e523466a8c6e591ea03e7e74d369927a1d16a7f521701d/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)[![Known Vulnerabilities](https://camo.githubusercontent.com/93d9c20fe1caf43afffb6eace0a348fc785a537d195c01efd5a2b41ad18faa8d/68747470733a2f2f736e796b2e696f2f746573742f6769746875622f6c61726176656c2d666f756e6472792f747275737465642d70726f786965732f62616467652e737667)](https://camo.githubusercontent.com/93d9c20fe1caf43afffb6eace0a348fc785a537d195c01efd5a2b41ad18faa8d/68747470733a2f2f736e796b2e696f2f746573742f6769746875622f6c61726176656c2d666f756e6472792f747275737465642d70726f786965732f62616467652e737667)[![GitHub Issues](https://camo.githubusercontent.com/614da1dd4a0202562ca25d674751e4045cf874f82e31a9cd53d4d71f5ebcf303/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)](https://camo.githubusercontent.com/614da1dd4a0202562ca25d674751e4045cf874f82e31a9cd53d4d71f5ebcf303/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6973737565732f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)[![GitHub Release](https://camo.githubusercontent.com/2716b182e7dd78096adea09f9c809ac749b311d4c42544bb5f6845e668626d98/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)](https://camo.githubusercontent.com/2716b182e7dd78096adea09f9c809ac749b311d4c42544bb5f6845e668626d98/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)[![License](https://camo.githubusercontent.com/d8ad9e94ce03cbaef064a17134edb29b21c81e68d3f18b3213d3ebe070606cb4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)](https://camo.githubusercontent.com/d8ad9e94ce03cbaef064a17134edb29b21c81e68d3f18b3213d3ebe070606cb4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6c61726176656c2d666f756e6472792f747275737465642d70726f78696573)

Laravel Trusted Proxies
=======================

[](#laravel-trusted-proxies)

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

Why This Package?
-----------------

[](#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

[](#what-it-does-that-laravel-doesnt-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`](https://github.com/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

[](#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
--------

[](#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
------------

[](#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
------------

[](#installation)

### 1. Install the package

[](#1-install-the-package)

```
composer require laravel-foundry/trusted-proxies
```

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

### 2. Configure environment variables

[](#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
-------------

[](#configuration)

### Environment Variables

[](#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

[](#available-providers)

ProviderDescriptionIP Source`cloudflare`Cloudflare CDNDynamic via API (cached)`aws_cloudfront`AWS CloudFront CDNStatic ranges`fastly`Fastly CDNStatic ranges`docker`Docker networks (bridge, custom, Swarm ingress)Static ranges### Publish Configuration (Optional)

[](#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
-----

[](#usage)

### Basic 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

[](#environment-specific-configurations)

#### Local Development

[](#local-development)

```
TRUSTED_PROXY_PROVIDERS=docker
```

#### Staging

[](#staging)

```
TRUSTED_PROXY_PROVIDERS=cloudflare,docker
```

#### Production with Docker Swarm

[](#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

[](#custom-load-balancer)

```
TRUSTED_PROXY_PROVIDERS=cloudflare,docker
TRUSTED_PROXY_CUSTOM_RANGES=10.20.0.0/16
```

### Multiple CDN Providers

[](#multiple-cdn-providers)

```
TRUSTED_PROXY_PROVIDERS=cloudflare,fastly,docker
```

Common Use Cases
----------------

[](#common-use-cases)

### Rate Limiting

[](#rate-limiting)

```
use Illuminate\Support\Facades\RateLimiter;

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

### IP Whitelisting

[](#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

[](#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
------------

[](#how-it-works)

### Architecture

[](#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?

[](#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)

Cloudflare IP ranges are resolved dynamically at runtime via [`monicahq/laravel-cloudflare`](https://github.com/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
---------------

[](#troubleshooting)

### Still seeing proxy IPs?

[](#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?

[](#docker-swarm-issues)

```
# Check the ingress network
docker network inspect ingress

# Check your container's networks
docker inspect  | grep -A 20 Networks
```

Testing
-------

[](#testing)

```
composer test
```

More info
---------

[](#more-info)

See [here](docs/README.md).

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for a detailed list of changes for each release.

We follow [Semantic Versioning](https://semver.org/) and use [Conventional Commits](https://www.conventionalcommits.org/) to automatically generate our changelog.

### Release Process

[](#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
------------

[](#contributing)

For your contributions please use:

- [Conventional Commits](https://www.conventionalcommits.org)
- [Pull request workflow](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)

See [CONTRIBUTING](.github/CONTRIBUTING.md) for detailed guidelines.

Sponsor
-------

[](#sponsor)

[![Buy Me A Coffee](https://camo.githubusercontent.com/0cf29a542375e1a46e84d8bf5805a4e5c0a6ee98b6547ccdc0c55eed49d99c69/68747470733a2f2f63646e2e6275796d6561636f666665652e636f6d2f627574746f6e732f76322f64656661756c742d79656c6c6f772e706e67)](https://buymeacoff.ee/frugan)

License
-------

[](#license)

(ɔ) Copyleft 2026 [Frugan](https://frugan.it).
[GNU GPLv3](https://choosealicense.com/licenses/gpl-3.0/), see [LICENSE](LICENSE) file.

###  Health Score

38

—

LowBetter than 83% of packages

Maintenance84

Actively maintained with recent releases

Popularity10

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 70% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~38 days

Total

3

Last Release

85d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/d63132b36d930fc7ea4bc04b54843b6d17ffb0354514ec3eb8a949df882fd5e9?d=identicon)[frugan](/maintainers/frugan)

---

Top Contributors

[![frugan-dev](https://avatars.githubusercontent.com/u/7957714?v=4)](https://github.com/frugan-dev "frugan-dev (7 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)")

---

Tags

aws-cloudfrontcloudflaredockerdocker-swarmfastlyk8skuberneteslaravelproxytrusted-proxieslaravelproxydockercloudflarefastlytrusted proxiesAWS Cloudfrontdocker-swarm

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/laravel-foundry-trusted-proxies/health.svg)

```
[![Health](https://phpackages.com/badges/laravel-foundry-trusted-proxies/health.svg)](https://phpackages.com/packages/laravel-foundry-trusted-proxies)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3355.3M346](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

77022.3M151](/packages/laravel-mcp)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

816333.8k3](/packages/defstudio-telegraph)[api-platform/laravel

API Platform support for Laravel

58171.6k14](/packages/api-platform-laravel)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5021.9k](/packages/simplestats-io-laravel-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)