README

Laravel IP firewall — whitelist, blacklist, and attack blocking.

Fork of antonioribeiro/firewall (originally published as pragmarx/firewall), modernized for PHP 8.1+ and Laravel 10–13.

Version matrix

The cell list is kept in docker/matrix.txt (single source of truth for local Docker runs) and mirrored in .forgejo/workflows/tests.yml.

Local matrix testing

Run the full matrix or a single cell locally via Docker:

make test-all                              # full matrix
make test-matrix PHP=8.2 LARAVEL=11        # single cell

Cells run inside pre-built thecodingmachine/php CLI images, pinned by digest in docker/digests.txt for reproducibility. The repository is mounted read-only and copied to a scratch directory inside the container, so composer require cannot mutate the host composer.json or vendor/.

Refreshing image digests. Update docker/digests.txt when adding a new PHP version or pulling in upstream base-image changes. The refresh command is documented in the header of that file; after running it, commit the updated digests alongside any matrix changes.

Installation

composer require magentron/laravel-firewall

The service provider and Firewall facade are auto-discovered via extra.laravel in composer.json.

Publish configuration

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

This writes config/firewall.php to your application.

Run migrations (optional, database mode)

php artisan vendor:publish --tag=firewall-migrations
php artisan migrate

Set firewall.use_database = true in the config to persist IP lists in the database. When false (default), lists are kept in config arrays only.

Middleware

Three named middleware aliases are registered automatically:

Usage in routes

// Apply to a single route
Route::get('/admin', AdminController::class)->middleware('fw-only-whitelisted');

// Apply to a route group
Route::middleware(['fw-block-blacklisted'])->group(function () {
    Route::get('/api/public', PublicApiController::class);
});

// Stack multiple middleware
Route::middleware(['fw-block-blacklisted', 'fw-block-attacks'])->group(function () {
    Route::post('/api/sensitive', SensitiveController::class);
});

Facade API

use Firewall;   // or use PragmaRX\Firewall\Vendor\Laravel\Facade as Firewall;

// Add to lists
Firewall::blacklist('1.2.3.4');
Firewall::whitelist('1.2.3.4');

// Force move between lists (overrides existing entry)
Firewall::blacklist('1.2.3.4', force: true);

// Query lists
Firewall::isBlacklisted('1.2.3.4');   // bool
Firewall::isWhitelisted('1.2.3.4');   // bool
Firewall::whichList('1.2.3.4');       // 'blacklist'|'whitelist'|null

// Remove / clear
Firewall::remove('1.2.3.4');
Firewall::clear();

// Attack detection
Firewall::isBeingAttacked('1.2.3.4');  // bool
Firewall::responseToAttack();          // Response|RedirectResponse|null

// Misc
Firewall::all();             // Collection of all stored IPs
Firewall::report();          // alias of all()
Firewall::find('1.2.3.4');  // Eloquent model|null
Firewall::ipIsValid('...');  // bool
Firewall::getMessages();     // Collection<string>

Supported IP formats

127.0.0.1
192.168.17.0/24
127.0.0.1/255.255.255.255
10.0.0.1-10.0.0.255
172.17.*.*
country:br
host:example.com
/path/to/iplist.txt   (file containing IPs, one per line)

Artisan commands

IP detection and proxy support

This fork delegates IP resolution entirely to Laravel's Request::getClientIp(). That method honors Symfony's Request::$trustedProxies, which Laravel configures via the TrustProxies middleware.

If your application runs behind Cloudflare, an AWS ALB, or any other reverse proxy, configure TrustProxies once and IP detection works automatically — no package-specific configuration needed.

Cloudflare example — add Cloudflare's published IP ranges to App\Http\Middleware\TrustProxies:

protected $proxies = [
    '103.21.244.0/22',
    '103.22.200.0/22',
    // ... full list from https://www.cloudflare.com/ips/
];

protected $headers = Request::HEADER_X_FORWARDED_FOR;

See Laravel's trusted proxy documentation for details.

Migrating from pragmarx/firewall: The previous version read HTTP_CF_CONNECTING_IP and HTTP_X_FORWARDED_FOR headers directly, bypassing Laravel's proxy trust list. This was a spoofing risk. The new behavior is safer: configure TrustProxies and the right IP will be detected.

GeoIP / country filtering

Country-based filtering (country:us, country:br, etc.) requires a MaxMind GeoLite2-Country database.

Automatic download

Set the environment variable and run the Artisan command:

FIREWALL_MAXMIND_LICENSE_KEY=your_key_here php artisan firewall:updategeoip

Or add to .env:

FIREWALL_MAXMIND_LICENSE_KEY=your_key_here

A free license key can be obtained from MaxMind.

Manual placement

Download GeoLite2-Country.mmdb from MaxMind and place it at the path configured in firewall.geoip_database_path (defaults to <package>/src/config/geoip/GeoLite2-Country.mmdb).

Graceful degradation

When no database file exists, country lookups return null silently. Country filtering is skipped and no exception is thrown. Users who don't need country features are unaffected.

Migrating from pragmarx/firewall

magentron/laravel-firewall is a true drop-in replacement: it reuses the PragmaRX\Firewall PHP namespace and declares a Composer replace for pragmarx/firewall, so Composer's dependency resolver will accept this package wherever pragmarx/firewall is required. Existing code that imports PragmaRX\Firewall\... classes continues to work without modification.

Config file keys and defaults, middleware aliases (fw-only-whitelisted, fw-block-blacklisted, fw-block-attacks), the Firewall facade, Artisan command signatures, the database table schema, and the AttackDetected event class are all unchanged.

Steps

1. Remove pragmarx/firewall and install this fork:

   composer remove pragmarx/firewall
   composer require magentron/laravel-firewall

2. If you published the config previously, re-publish or manually verify it — config keys are identical, so the existing file will work.

3. Review the behavioural changes in changelog.md — in particular, the trusted-proxy IP resolution hardening (see below) may require configuring Laravel's TrustProxies middleware if you run behind Cloudflare, AWS ALB, or similar.

License

BSD-3-Clause

Original work Copyright (c) 2014, Antonio Carlos Ribeiro
Fork modifications Copyright (c) 2026, Jeroen D. a.k.a. Magentron

Upstream: https://github.com/antonioribeiro/firewall