README

Protect your PHP application from brute force, DDoS, SQL injection, XSS, and bot attacks with a single middleware.

Phirewall is a PSR-15 middleware that provides comprehensive application-layer protection. It's lightweight, framework-agnostic, and easy to configure.

Why Phirewall?

• Simple Setup - Add protection in minutes with sensible defaults
• Multiple Attack Vectors - Rate limiting, brute force protection, OWASP rules, bot detection
• Framework Agnostic - Works with any PSR-15 compatible framework (Laravel, Symfony, Slim, Mezzio, etc.)
• Production Ready - Redis support for multi-server deployments
• Observable - PSR-14 events for logging, metrics, and alerting

Quick Start

composer require flowd/phirewall

use Flowd\Phirewall\Config;
use Flowd\Phirewall\Middleware;
use Flowd\Phirewall\KeyExtractors;
use Flowd\Phirewall\Store\InMemoryCache;

// Create the firewall
$config = new Config(new InMemoryCache());

// Allow health checks to bypass all rules
$config->safelist('health', fn($req) => $req->getUri()->getPath() === '/health');

// Block common scanner paths
$config->blocklist('scanners', fn($req) => str_starts_with($req->getUri()->getPath(), '/wp-admin'));

// Rate limit: 100 requests per minute per IP
$config->throttle('api', limit: 100, period: 60, key: KeyExtractors::ip());

// Ban IP after 5 failed logins in 5 minutes
$config->fail2ban('login', threshold: 5, period: 300, ban: 3600,
    filter: fn($req) => $req->getHeaderLine('X-Login-Failed') === '1',
    key: KeyExtractors::ip()
);

// Add to your middleware stack
$middleware = new Middleware($config);

Add the middleware to your PSR-15 pipeline. All requests will be evaluated against your rules before reaching your application.

Try It Now

Run one of the included examples to see Phirewall in action:

# Basic setup demo
php examples/01-basic-setup.php

# See brute force protection
php examples/02-brute-force-protection.php

# Test SQL injection blocking
php examples/04-sql-injection-blocking.php

# Full production setup
php examples/08-comprehensive-protection.php

Examples

The examples/ folder contains 15 runnable examples:

Features

Protection Layers

Observability

• PSR-14 Events - SafelistMatched, BlocklistMatched, ThrottleExceeded, Fail2BanBanned
• Diagnostics Counters - Per-rule statistics for monitoring
• Standard Headers - X-RateLimit-*, Retry-After, X-Phirewall-*

Storage Backends

Documentation

For detailed documentation, see the docs/ folder:

• Getting Started - Step-by-step setup guide
• Common Attacks - Protection recipes for 10+ attack types
• Configuration - Complete API reference
• Storage Backends - Redis, APCu, and custom backends
• Pattern Backends - IP, CIDR, path, and header blocklists
• OWASP CRS - Loading and customizing rules
• Observability - Events, logging, and monitoring
• Infrastructure Adapters - Apache .htaccess integration

Installation

composer require flowd/phirewall

Optional Dependencies

# For Redis-backed distributed counters (multi-server)
composer require predis/predis

# For Monolog logging integration
composer require monolog/monolog

APCu: Enable the PHP extension and set apc.enable_cli=1 for CLI testing.

Response Headers

When a request is blocked:

Enable $config->enableRateLimitHeaders() for standard X-RateLimit-* headers.

Client IP Behind Proxies

When behind load balancers or CDNs, use TrustedProxyResolver:

use Flowd\Phirewall\Http\TrustedProxyResolver;
use Flowd\Phirewall\KeyExtractors;

$resolver = new TrustedProxyResolver([
    '10.0.0.0/8',      // Internal network
    '172.16.0.0/12',   // Docker
]);

$config->throttle('api', limit: 100, period: 60,
    key: KeyExtractors::clientIp($resolver)
);

Custom Responses

Customize blocked responses while keeping standard headers:

$config->blocklistedResponse(function (string $rule, string $type, $req) {
    return new Response(403, ['Content-Type' => 'application/json'],
        json_encode(['error' => 'Blocked', 'rule' => $rule])
    );
});

$config->throttledResponse(function (string $rule, int $retryAfter, $req) {
    return new Response(429, ['Content-Type' => 'application/json'],
        json_encode(['error' => 'Rate limited', 'retry_after' => $retryAfter])
    );
});

OWASP Core Rule Set

Load OWASP-style rules for SQL injection, XSS, and more:

use Flowd\Phirewall\Owasp\SecRuleLoader;

$rules = SecRuleLoader::fromString(<<<'CRS'
SecRule ARGS "@rx (?i)\bunion\b.*\bselect\b" "id:942100,phase:2,deny,msg:'SQLi'"
SecRule ARGS "@rx (?i)<script[^>]*>" "id:941100,phase:2,deny,msg:'XSS'"
CRS);

$config->owaspBlocklist('owasp', $rules);

Or load from files:

$rules = SecRuleLoader::fromDirectory('/path/to/crs-rules');

See 04-sql-injection-blocking.php and 05-xss-prevention.php for complete examples.

Real-World Recipes

API Rate Limiting

// Global limit
$config->throttle('global', limit: 1000, period: 60, key: KeyExtractors::ip());

// Burst detection
$config->throttle('burst', limit: 30, period: 5, key: KeyExtractors::ip());

// Higher limits for authenticated users
$config->throttle('user', limit: 5000, period: 60, key: KeyExtractors::header('X-User-Id'));

Login Protection

// Throttle login attempts
$config->throttle('login', limit: 10, period: 60, key: function($req) {
    return $req->getUri()->getPath() === '/login'
        ? $req->getServerParams()['REMOTE_ADDR']
        : null;
});

// Ban after failures
$config->fail2ban('login-ban', threshold: 5, period: 300, ban: 3600,
    filter: fn($req) => $req->getHeaderLine('X-Login-Failed') === '1',
    key: KeyExtractors::ip()
);

Bot Detection

$scanners = ['sqlmap', 'nikto', 'nmap', 'burp', 'dirbuster'];

$config->blocklist('scanners', function($req) use ($scanners) {
    $ua = strtolower($req->getHeaderLine('User-Agent'));
    foreach ($scanners as $scanner) {
        if (str_contains($ua, $scanner)) return true;
    }
    return false;
});

Development

# Run tests
composer test

# Fix code style
composer fix

# Mutation testing
composer test:mutation

Sponsors

This project received funding from TYPO3 Association through its Community Budget program.

Read more

License

Dual licensed under LGPL-3.0-or-later and proprietary. See LICENSE for details.