Firewall Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider, no config/firewall.php, and no artisan command. If you are coming from Laravel, the first step is deciding whether you need the bundle at all or just the IP-matching logic underneath it.

Minimal path with Symfony Flex:

composer require yipikai/firewall-bundle

1. Confirm auto-registration. Flex should add it to config/bundles.php. If not, register it manually and check the bundle class name in vendor/yipikai/firewall-bundle/ — the extension alias (roughly yipikai_firewall) is what you will reference in YAML.
2. Look here first: the bundle's DependencyInjection/Configuration.php. That file is the authoritative list of every option, its default, and whether it is required. Read it before the README; at zero stars and zero dependents, the README is likely thinner than the code.
3. Find the enforcement point. Search the source for getClientIp, RequestEvent, or AccessDeniedException. That tells you whether it hooks into Symfony's security firewall or runs as a plain kernel request listener — which changes how you debug it.
4. First use case: lock a single route prefix down to a known IP list. Configure the allowlist from an environment variable so staging and production differ without code changes, then hit the route from an allowed and a disallowed IP and confirm you get 403 (or a redirect) rather than a 500.

If you are genuinely on Laravel, stop here and vendor the IP-range comparison class only; the bundle's HTTP plumbing will not run.

Implementation Patterns

Environment-scoped allowlists. The common real-world shape is one list per environment: office/VPN ranges in staging, CDN and uptime-monitor ranges in production, wide open locally. Drive it from env()-backed parameters rather than committing CIDRs to YAML, and keep the local list explicit (127.0.0.1, ::1) so a misconfigured env var fails closed locally instead of blocking your own dev loop.

CIDR blocks over single IPs. Any IP firewall worth using compares ranges, not strings. Verify the bundle supports /24-style entries and IPv6 before you rely on it — if it does exact string matching, wrap it in your own matcher rather than duplicating IPs into config.

Custom IP source. The hard part is never the comparison, it is which IP. If the bundle exposes a resolver interface or a tagged service for extracting the client IP, implement it and delegate to Request::getClientIp()-equivalent logic with your proxy trust settings. This is the extension point worth finding on day one.

Allowlist vs. denylist asymmetry. Allowlisting is a security control; denylisting is a nuisance filter. Use the allowlist mode for admin panels, internal tooling, webhooks with fixed egress, and /health endpoints that only your load balancer should reach. Do not allowlist your public API.

Pair it with normal auth. Treat the IP firewall as a second gate, not a replacement for authentication. The pattern that ages well is: IP allowlist on the route prefix and the existing login/session check behind it, so a spoofed or shared egress IP does not become a full bypass.

Test with a real client IP. In functional tests, set the remote address on the request object ($client->request(..., server: ['REMOTE_ADDR' => '203.0.113.5'])) and assert both the allowed and denied paths. An IP firewall with only an "allowed" test is untested.

Gotchas and Tips

Proxies will silently break this. Behind a load balancer, the socket IP is the balancer, so either everything is allowed or everything is blocked. Configure Symfony's framework.trusted_proxies and trusted_headers correctly, and remember that a raw X-Forwarded-For header from an untrusted client is trivially spoofable. Get this wrong and your allowlist is decorative.

Listener ordering matters. If enforcement runs before the security firewall authenticates, you get 403s where you expected 401s, and error pages may leak route existence. If it runs too late, expensive work happens before the block. Check the priority in the service definition and confirm the listener is registered on kernel.request with an explicit priority rather than a default.

Config is compiled and cached. Symfony caches the container; changing bundle YAML without bin/console cache:clear (or in dev, without the cache rebuilding) leaves you debugging a config that is not loaded. The classic symptom is "my new IP isn't allowed" after an edit that never took effect.

IPv6 and IPv4 are different keys. ::1 is not 127.0.0.1, and an IPv4-mapped IPv6 address (::ffff:192.0.2.1) will not match a plain IPv4 entry in most naive matchers. Normalize before comparing, or you will ship a firewall that blocks localhost on some machines.

Trust level is the real risk. Zero stars, zero dependents, and a single recent release means no downstream production history to learn from. Pin the exact version in composer.json, read the enforcement path end to end (it is probably a few hundred lines), and write your own integration test that asserts a non-allowlisted IP is actually rejected — not just that the service resolves. Wrap the bundle behind a thin internal interface so you can swap it for a middleware or a kernel listener without touching call sites.

Debug by logging the decision, not the outcome. Add a log line on every evaluation with the resolved client IP, the matched rule, and the verdict. Nearly every bug report about IP firewalls is "the wrong IP was resolved," and that is invisible from a 403 alone.