Download the PHP package rennf93/laravel-guard without Composer

laravel-guard

Laravel middleware adapter for guard-core-php: maps Illuminate\Http\Request objects to the guard-core engine and translates block verdicts back to Laravel-native responses. Works with Laravel 10, 11, and 12.

Docs: https://rennf93.github.io/laravel-guard/

Install

Usage

Bind the middleware in the container and register it globally:

Blocked requests get the engine's block verdict translated exactly (status, body, headers) as an Illuminate\Http\Response: 403 Forbidden for a blacklisted IP, 429 Too many requests with Retry-After for a rate limit hit.

Pass-through responses are finished by the middleware too: the engine's security headers and CORS verdict headers are merged on top of the handler's response, and the engine's behavioral return rules observe the response status code plus a body prefix bounded by behaviorMaxResponseBodyInspectBytes (only while behaviorScanResponseBody is on). Per-route configuration attaches through the middleware's route map or a custom resolver:

routes patterns match a path exactly or as a prefix when they end with /. Geo rate-limit tiers need a country resolver: pass geoRateLimitResolver explicitly, or configure geoIpHandler together with blockedCountries/whitelistCountries (the engine keeps the injected handler only when country lists are set) and the middleware bridges it onto the engine's rate-limit handler automatically.

Lifecycle

PHP shared-nothing applies: construct GuardEngine (and therefore GuardMiddleware) per request in classic FPM, or per worker under Octane/FrankenPHP. The middleware holds no mutable state of its own. In-memory fallbacks are per-request safety nets; distributed rate limits, IP bans, and cloud-range caches require Redis (set enableRedis: true and point REDIS_HOST/REDIS_PORT at your instance).

Behavior notes

• Fail-closed: if the engine throws, the middleware returns the engine's fail-closed response (500 Security check failed, honorably overridden by customErrorResponses) instead of letting the request through.
• Bounded body read: the request body is scanned as a prefix of at most 256 KiB (LaravelGuardRequest::MAX_BODY_BYTES, matching the engine's full-scan window). The framework materializes the full body in memory; the engine only ever sees the capped prefix. Payloads beyond the prefix, or signatures split across its boundary, are not detected.
• Client address: the adapter maps the engine's clientHost() onto $request->ip(). Without Laravel's TrustProxies middleware that is the connecting REMOTE_ADDR, and the engine's own trusted_proxies / X-Forwarded-For resolution applies. With Laravel's TrustProxies configured, Laravel resolves the forwarded chain first and the engine sees the resolved client. Pick one side to do the resolving; configuring both can double-hop.
• With redisFailOpen: true the middleware constructs and serves requests even when Redis is unreachable; with redisFailOpen: false construction fails closed.
• No security headers or CORS are added by this adapter. (Laravel/Symfony response mechanics put a Date and a private Cache-Control on every response object; the engine's own headers are copied exactly.)

Testing

composer test runs the plain-PHP suite in bin/test_laravel.php (unit coverage always; set REDIS_HOST to a reachable Redis to include the shared-state integration cases).

Status

Released: v1.1.0 on Packagist. The engine floor is rennf93/guard-core-php ^4.1.0; no 4.1.0 of the engine is currently published (its tag is absent and Packagist's latest is v4.0.4), so public resolution is collapsed until the synchronized 4.2.0 train retags the engine - CI resolves the engine from the master sibling checkout in the meantime.

License

MIT