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.1.0(3mo ago)010GPL-3.0-or-laterPHPPHP >=8.2CI passing

Since Jan 23Pushed 3mo 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 1mo ago

READMEChangelog (1)Dependencies (6)Versions (2)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.

Features
--------

[](#features)

- **Multiple CDN Support** - Cloudflare, AWS CloudFront, Fastly out of the box
- **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()

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

[](#why-this-package)

When running Laravel behind proxies (CDN, Docker Swarm, load balancers), Laravel sees the proxy's IP instead of the real client IP. This breaks:

- Rate limiting
- IP-based access control
- Geolocation
- Logging and analytics
- Security features

This package configures Laravel to trust specific proxies and extract the real client IP from headers like `X-Forwarded-For` and `CF-Connecting-IP`.

Requirements
------------

[](#requirements)

- PHP >= 8.2
- Laravel Illuminate/Support ^10.0|^11.0|^12.0
- Laravel Illuminate/HTTP ^10.0|^11.0|^12.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)

The package uses environment variables for configuration:

```
# 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)

- `cloudflare` - Cloudflare CDN (includes CF-Connecting-IP header)
- `aws_cloudfront` - AWS CloudFront CDN
- `fastly` - Fastly CDN (includes Fastly-Client-IP header)
- `docker` - Docker networks (bridge, custom, Swarm ingress)

### 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();

// Use in your application
Log::info('Request from IP', ['ip' => $clientIp]);
```

### Environment-Specific Configurations

[](#environment-specific-configurations)

#### Local Development (.env.development)

[](#local-development-envdevelopment)

```
# Only trust Docker internal networks
TRUSTED_PROXY_PROVIDERS=docker
```

#### Staging (.env.staging)

[](#staging-envstaging)

```
# Trust Docker + Cloudflare
TRUSTED_PROXY_PROVIDERS=cloudflare,docker
```

#### Production with Docker Swarm (.env.production)

[](#production-with-docker-swarm-envproduction)

```
# Trust Docker (for Swarm ingress) + Cloudflare
TRUSTED_PROXY_PROVIDERS=cloudflare,docker
```

**Important:** Always keep `docker` enabled in production when using Docker Swarm, because the Swarm ingress network acts as an internal proxy.

### Custom Load Balancer

[](#custom-load-balancer)

If you have an additional load balancer:

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

### Multiple CDN Providers

[](#multiple-cdn-providers)

```
# Using both Cloudflare and Fastly
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',
]);
```

### Geolocation

[](#geolocation)

```
use Illuminate\Support\Facades\Http;

$ip = request()->ip();
$location = Http::get("http://ip-api.com/json/{$ip}")->json();

// Use real IP for accurate geolocation
```

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 and Docker networks
2. Read real client IP from CF-Connecting-IP header
3. Fall back to X-Forwarded-For if needed

```

### Technical Details

[](#technical-details)

**Request Flow:**

1. Request arrives at CDN (e.g., Cloudflare)
2. CDN adds headers: `CF-Connecting-IP`, `X-Forwarded-For`
3. Request reaches your server
4. If using Docker Swarm, goes through ingress network
5. Package configures `Request::setTrustedProxies()` with:
    - CDN IP ranges (Cloudflare, AWS, Fastly)
    - Docker network ranges (10.0.0.0/8, 172.16.0.0/12)
    - Custom ranges (if configured)
6. Laravel extracts real IP from trusted headers
7. `request()->ip()` returns real client IP

**Provider-Specific Headers:**

- Cloudflare: Uses `CF-Connecting-IP` (most reliable)
- Fastly: Uses `Fastly-Client-IP`
- Others: Use `X-Forwarded-For` (first non-private 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 to process it correctly.

Troubleshooting
---------------

[](#troubleshooting)

### Still seeing proxy IPs?

[](#still-seeing-proxy-ips)

Check your configuration:

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

// Check enabled providers
$providers = config('trustedproxies.providers');
var_dump($providers);

// Check all trusted IPs
$trustedIps = $service->getTrustedProxies();
var_dump($trustedIps);

// Check current IP
var_dump(request()->ip());
```

### Cloudflare not working?

[](#cloudflare-not-working)

Verify Cloudflare is passing the header:

```
// Check if header is present
var_dump($_SERVER['HTTP_CF_CONNECTING_IP'] ?? 'not set');
```

Make sure Cloudflare's orange cloud is enabled (proxying traffic).

### Docker Swarm issues?

[](#docker-swarm-issues)

Verify the ingress network:

```
# Check Docker network
docker network inspect ingress

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

### Wrong IP being returned?

[](#wrong-ip-being-returned)

Enable debug logging:

```
// In tinker or temporarily in code
Log::debug('IP Detection', [
    'request_ip' => request()->ip(),
    'remote_addr' => $_SERVER['REMOTE_ADDR'] ?? null,
    'cf_connecting_ip' => $_SERVER['HTTP_CF_CONNECTING_IP'] ?? null,
    'x_forwarded_for' => $_SERVER['HTTP_X_FORWARDED_FOR'] ?? null,
    'trusted_proxies' => $service->getTrustedProxies(),
]);
```

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

34

—

LowBetter than 77% of packages

Maintenance79

Regular maintenance activity

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity36

Early-stage or recently created project

 Bus Factor1

Top contributor holds 75% 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

Unknown

Total

1

Last Release

109d 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 (6 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 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

[ryoluo/sail-ssl

Laravel Sail plugin to enable SSL (HTTPS) connection with Nginx.

188672.6k2](/packages/ryoluo-sail-ssl)[vcian/pulse-docker-monitor

A Laravel Pulse card to show docker containers with CPU & Memory Utilization

348.0k](/packages/vcian-pulse-docker-monitor)

PHPackages © 2026

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