PHPackages magentron/laravel-firewall - 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. [Security](/categories/security) 4. / 5. magentron/laravel-firewall ActiveLibrary[Security](/categories/security) magentron/laravel-firewall ========================== Laravel IP firewall — whitelist, blacklist, and attack blocking. Fork of pragmarx/firewall. v3.0.1(1mo ago)0161↓27.4%1BSD-3-ClausePHPPHP ^8.1 Since Jan 31Pushed 1mo agoCompare [ Source](https://github.com/Magentron/laravel-firewall)[ Packagist](https://packagist.org/packages/magentron/laravel-firewall)[ RSS](/packages/magentron-laravel-firewall/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (10)Versions (37)Used By (1) magentron/laravel-firewall ========================== [](#magentronlaravel-firewall) Laravel IP firewall — whitelist, blacklist, and attack blocking. Fork of [antonioribeiro/firewall](https://github.com/antonioribeiro/firewall) (originally published as `pragmarx/firewall`), modernized for PHP 8.1+ and Laravel 10–13. --- Version matrix -------------- [](#version-matrix) LaravelPHP108.1, 8.2118.2, 8.3128.2, 8.3, 8.4138.3, 8.4The 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 [](#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`](https://github.com/thecodingmachine/docker-images-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 ------------ [](#installation) ``` composer require magentron/laravel-firewall ``` The service provider and `Firewall` facade are auto-discovered via `extra.laravel` in `composer.json`. ### Publish configuration [](#publish-configuration) ``` php artisan vendor:publish --tag=firewall-config ``` This writes `config/firewall.php` to your application. ### Run migrations (optional, database mode) [](#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 ---------- [](#middleware) Three named middleware aliases are registered automatically: AliasBehaviour`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 [](#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 ---------- [](#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 ``` ### Supported IP formats [](#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 ---------------- [](#artisan-commands) CommandDescription`firewall:whitelist `Add IP to whitelist`firewall:blacklist `Add IP to blacklist`firewall:remove `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 ------------------------------ [](#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](https://laravel.com/docs/requests#configuring-trusted-proxies) 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 ------------------------- [](#geoip--country-filtering) Country-based filtering (`country:us`, `country:br`, etc.) requires a MaxMind GeoLite2-Country database. ### Automatic download [](#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](https://www.maxmind.com/en/geolite2/signup). ### Manual placement [](#manual-placement) Download `GeoLite2-Country.mmdb` from MaxMind and place it at the path configured in `firewall.geoip_database_path` (defaults to `/src/config/geoip/GeoLite2-Country.mmdb`). ### Graceful degradation [](#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` ---------------------------------- [](#migrating-from-pragmarxfirewall) `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 [](#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 ------- [](#license) BSD-3-Clause Original work Copyright (c) 2014, Antonio Carlos Ribeiro Fork modifications Copyright (c) 2026, Jeroen D. a.k.a. Magentron Upstream: ### Health Score 55 — FairBetter than 97% of packages Maintenance88 Actively maintained with recent releases Popularity15 Limited adoption so far Community19 Small or concentrated contributor base Maturity84 Battle-tested with a long release history Bus Factor1 Top contributor holds 91.6% 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 ~127 days Recently: every ~601 days Total 36 Last Release 58d ago Major Versions v0.5.4 → v1.0.02015-12-24 v1.1.0 → v2.0.02017-08-21 v1.1.1 → v2.2.02018-02-10 v2.3.2 → v3.0.02026-04-12 PHP version history (3 changes)v0.1.0PHP >=5.3.7 v2.1.0PHP >=5.6 v3.0.0PHP ^8.1 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/853900?v=4)[Jeroen D.](/maintainers/Magentron)[@Magentron](https://github.com/Magentron) --- Top Contributors [![antonioribeiro](https://avatars.githubusercontent.com/u/3182864?v=4)](https://github.com/antonioribeiro "antonioribeiro (358 commits)")[![zek](https://avatars.githubusercontent.com/u/3463291?v=4)](https://github.com/zek "zek (6 commits)")[![Magentron](https://avatars.githubusercontent.com/u/853900?v=4)](https://github.com/Magentron "Magentron (5 commits)")[![liepumartins](https://avatars.githubusercontent.com/u/2070205?v=4)](https://github.com/liepumartins "liepumartins (4 commits)")[![Hornet-Wing](https://avatars.githubusercontent.com/u/10299554?v=4)](https://github.com/Hornet-Wing "Hornet-Wing (3 commits)")[![RobertBoes](https://avatars.githubusercontent.com/u/2871897?v=4)](https://github.com/RobertBoes "RobertBoes (2 commits)")[![swilla](https://avatars.githubusercontent.com/u/304159?v=4)](https://github.com/swilla "swilla (2 commits)")[![mmeklin15](https://avatars.githubusercontent.com/u/19165277?v=4)](https://github.com/mmeklin15 "mmeklin15 (1 commits)")[![phroggyy](https://avatars.githubusercontent.com/u/7256451?v=4)](https://github.com/phroggyy "phroggyy (1 commits)")[![ryan-eurecab](https://avatars.githubusercontent.com/u/30040673?v=4)](https://github.com/ryan-eurecab "ryan-eurecab (1 commits)")[![StyleCIBot](https://avatars.githubusercontent.com/u/11048387?v=4)](https://github.com/StyleCIBot "StyleCIBot (1 commits)")[![lloricode](https://avatars.githubusercontent.com/u/8251344?v=4)](https://github.com/lloricode "lloricode (1 commits)")[![bryant1410](https://avatars.githubusercontent.com/u/3905501?v=4)](https://github.com/bryant1410 "bryant1410 (1 commits)")[![EcoinTest](https://avatars.githubusercontent.com/u/153815470?v=4)](https://github.com/EcoinTest "EcoinTest (1 commits)")[![exfriend](https://avatars.githubusercontent.com/u/769995?v=4)](https://github.com/exfriend "exfriend (1 commits)")[![jamesggordon](https://avatars.githubusercontent.com/u/650785?v=4)](https://github.com/jamesggordon "jamesggordon (1 commits)")[![justplayingames](https://avatars.githubusercontent.com/u/29954155?v=4)](https://github.com/justplayingames "justplayingames (1 commits)")[![alariva](https://avatars.githubusercontent.com/u/3021314?v=4)](https://github.com/alariva "alariva (1 commits)") --- Tags laravelsecurityIPblacklistfirewallwhitelist ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/magentron-laravel-firewall/health.svg) ``` [![Health](https://phpackages.com/badges/magentron-laravel-firewall/health.svg)](https://phpackages.com/packages/magentron-laravel-firewall) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k14.1M120](/packages/laravel-pulse)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9732.3M121](/packages/roots-acorn)[spatie/laravel-health Monitor the health of a Laravel application 88011.3M149](/packages/spatie-laravel-health) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)