Download the PHP package laikait/laika-shield without Composer

🛡️ Laika Shield

Laika Shield is the firewall layer for the Laika PHP Framework — IP and country filtering, rate limiting, SQL injection and XSS detection, and request filtering.

✨ Features

📦 Installation

Laika Shield ships as part of the framework — laikait/laika-framework already requires it, so there is usually nothing to install.

To pull it into a project directly:

Requires PHP 8.1+ and geoip2/geoip2. Country blocking additionally needs a MaxMind GeoLite2-Country database, which is not bundled — see Country Blocking.

🚀 Quick Start

1. Register the pipeline

Add ShieldPipeline to your route pipeline stack — first, ahead of everything else. It is only a firewall if nothing has run yet.

There is no config file to publish — the defaults are already complete, so the line above gives you a working firewall.

2. Adjust the configuration

A blocked request emits its JSON body and terminates. It never reaches the rest of the chain, so no downstream pipeline — auth, logging, database writes — runs for a request the firewall rejected.

Upgrading from 1.2.x: Laika\Shield\Http\ShieldMiddleware has been removed. It fell through its own catch block and let blocked requests reach the application. Replace it with ShieldPipeline as above.

3. Or use the static API

4. Or use the fluent builder

⚙️ Configuration Reference

Every option lives on a typed object with a fluent accessor: call it with no argument to read, with one to write. Defaults are declared on the properties themselves.

Accessors chain, and reading is the same method without an argument:

The six section accessors — ip(), rateLimit(), sqlInjection(), xss(), requestFilter(), country() — are static because there is only one configuration. The three top-level scalars (trustProxy, trustedProxies, ipVersion) stay on the instance: they are declared as instance methods, and PHP will not let a method be both static and non-static under one name.

Nullable options can be set back to null — storageDir, contentLengthMax, contentLengthMin and ipVersion all accept it as a real value.

Arrays still work

ShieldPipeline and Shield::fromConfig() accept a plain array, which is applied over the defaults rather than replacing them. Supplying one option in a section leaves the rest of that section alone:

Shield::boot() takes no arguments at all — it always reads the shared ShieldConfig instance, so configure that first with ShieldConfig::add() or ShieldConfig::instance().

Note the difference in where the defaults come from: fromConfig() layers an array over a fresh set of defaults and never touches global state, which keeps it predictable and testable. ShieldPipeline layers an array over the shared instance, so pipeline options combine with whatever the application configured.

ShieldConfig is a singleton

ShieldConfig has no public constructor. There is exactly one shared configuration, and that is what Shield::boot() and ShieldPipeline read:

The static section accessors are shortcuts onto that same shared instance — ShieldConfig::rateLimit() is exactly ShieldConfig::instance()->rateLimit.

If you need a throwaway configuration — for a test, or to run one request under different rules — ShieldConfig::make() gives you a detached object. boot() will not see it, so run it explicitly:

⚠️ The static accessors always resolve the shared instance. If you are holding a detached config, reach its sections through the object ($config->rateLimit) — ShieldConfig::rateLimit() would configure the shared one instead.

🔧 ShieldConfig Class

ShieldConfig also exposes a static, array-keyed API over one shared instance. It is kept for compatibility — the ShieldConfig relay is bound to it — and remains handy for one-off tweaks during bootstrap. New code should prefer the object API above.

ShieldConfig API

🏗️ Architecture

🔌 Writing Custom Rules

Implement RuleInterface to create your own firewall rules:

🧪 Running Tests

🌐 IP Version Detection

Shield exposes IpHelper for standalone IP utilities:

🔐 Trusting Proxies

Forwarded headers are attacker-controlled. Anyone can send X-Forwarded-For: 8.8.8.8, so believing the wrong one turns every IP rule into a suggestion.

Shield only consults them when trust.proxy is on, and:

• CF-Connecting-IP / X-Real-IP are believed only when the connecting peer is listed in trusted.proxies. A direct client can set these headers just as easily as a proxy can.
• X-Forwarded-For is walked right to left, discarding hops that match trusted.proxies, and the first remaining address wins. The leftmost entry — the one a client fully controls — is never trusted.
• With trusted.proxies empty, the rightmost X-Forwarded-For entry is used, since that is the only entry your own proxy wrote.

If your app is not behind a proxy, leave trust.proxy => false.

🌍 Country Blocking

The GeoLite2 database is not distributed with this package — it is MaxMind-licensed and roughly 9.5 MB. Fetch it with your own licence key:

Then point the config at it:

A missing or unreadable database does not block anyone and does not raise an error — requests simply pass the country check.

🎯 Tuning The Detectors

The detectors match SQL and HTML syntax, not vocabulary. Words like select, sleep, drop table or #42 in ordinary prose are not treated as attacks.

strict mode adds keyword-only SQL patterns. It will flag normal sentences, so enable it only for fields that never carry free text:

For rich-text or markup-bearing fields, use skip.keys rather than weakening the patterns for everything.

📄 License

MIT © Laika IT

GeoLite2 data, if you use it, is © MaxMind and governed by the GeoLite2 End User Licence Agreement.