magentron/laravel-firewall

Laravel IP firewall — whitelist, blacklist, and attack blocking. Fork of pragmarx/firewall.

v3.0.1 2026-04-12 22:48 UTC

Requires

• php: ^8.1
• illuminate/cache: ^10.0|^11.0|^12.0|^13.0
• illuminate/console: ^10.0|^11.0|^12.0|^13.0
• illuminate/database: ^10.0|^11.0|^12.0|^13.0
• illuminate/events: ^10.0|^11.0|^12.0|^13.0
• illuminate/http: ^10.0|^11.0|^12.0|^13.0
• illuminate/notifications: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0

Requires (Dev)

• geoip2/geoip2: ^3.0
• orchestra/testbench: ^8.0|^9.0|^10.0
• phpunit/phpunit: ^10.0|^11.0

Suggests

• geoip2/geoip2: ^3.0 — required for country-based filtering

Replaces

• pragmarx/firewall: *

BSD-3-Clause

• security
• firewall
• laravel
• IP
• blacklist
• whitelist

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

Laravel	PHP
10	8.1, 8.2
11	8.2, 8.3
12	8.2, 8.3, 8.4
13	8.3, 8.4

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:

Alias	Behaviour
fw-block-blacklisted	Returns 403 for blacklisted IPs; lets others through
fw-only-whitelisted	Returns 403 for non-whitelisted IPs; lets whitelisted through
fw-block-attacks	Returns 403 when attack-blocker threshold is exceeded

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

Command	Description
firewall:whitelist <ip>	Add IP to whitelist
firewall:blacklist <ip>	Add IP to blacklist
firewall:remove <ip>	Remove IP from all lists
firewall:clear	Remove all IPs from lists
firewall:list	Display all stored IPs
firewall:updategeoip	Download/update GeoLite2 database
firewall:cache:clear	Flush the firewall in-memory cache

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