particle-academy / fancy-http-guard
Laravel request guards checked before the body is parsed (413, nesting depth, list length, finite numbers with the field path, workbook rows x columns caps paired with holy-sheet), one error envelope with a request id on every response, and an HTTP-client normaliser. Every limit configurable.
Package info
github.com/Particle-Academy/fancy-http-guard
pkg:composer/particle-academy/fancy-http-guard
Requires
- php: ^8.4
- ext-json: *
- ext-mbstring: *
- illuminate/contracts: ^13.0
- illuminate/http: ^13.0
- illuminate/routing: ^13.0
- illuminate/support: ^13.0
- illuminate/validation: ^13.0
Requires (Dev)
- laravel/framework: ^13.30
- particle-academy/holy-sheet: ^2.14
- pestphp/pest: ^5.0
Suggests
- particle-academy/holy-sheet: Reads uploaded workbooks under the route's rows x columns caps: FancyHttpGuard::readWorkbook().
Provides
None
Conflicts
None
Replaces
None
README
Request guards for Laravel, checked before the body is parsed, plus one error envelope with a request id on every response, and an HTTP-client normaliser for the errors your app receives.
composer require particle-academy/fancy-http-guard
// bootstrap/app.php use ParticleAcademy\HttpGuard\FancyHttpGuard; ->withMiddleware(fn (Middleware $middleware) => FancyHttpGuard::install($middleware)) ->withExceptions(fn (Exceptions $exceptions) => FancyHttpGuard::exceptions($exceptions))
// routes/api.php Route::post('/imports', ImportController::class)->guard('upload'); // 10 MiB here Route::post('/rates', RateController::class)->guard(['maxDepth' => 4]); // inline limits
For agents. This package is not listed on the Fancy MCP catalog server yet. The server,
https://ui.particle.academy/mcp(streamable HTTP, no API key; MCP idfancy-ui), lists the released Fancy packages with install commands and docs. How an agent installs and uses this package is in AGENTS.md.
Before the body is parsed
install() PREPENDS the guard to the global middleware stack. That matters:
TrimStrings and ConvertEmptyStringsToNull are global middleware that decode
the whole JSON body before any route middleware runs. To honour per-route limits
anyway, the guard asks the route collection which route will serve the request.
| Check | Answer |
|---|---|
Content-Length over the route's cap |
413, and not one body byte is read |
a missing or lying Content-Length |
413 once maxBodyBytes + 1 bytes are read; the rest is never pulled |
a malformed Content-Length |
400 |
nesting deeper than maxDepth |
422 too_deep, naming the field; the scan stops there |
an array OR object with more than maxListLength members |
422 list_too_long; the scan stops there |
NaN, Infinity, 1e400 (which json_decode silently makes INF) |
422 not_finite, naming the field: items.3.price |
| not JSON at all | 400 malformed_body |
The scan is one pass over the bytes with no tree built. A body that passes reaches your controller byte for byte.
What PHP does before any PHP runs. Under PHP-FPM, multipart/form-data and
urlencoded bodies are parsed into $_FILES / $_POST by PHP itself, governed by
post_max_size. For those, the guard checks only Content-Length. Set
post_max_size at or above your largest route cap, and nginx
client_max_body_size above that. Under Octane the body is already in memory,
so the cap protects the parse, not the read.
The envelope
Every JSON error is one shape, with the request id in the body and the
X-Request-Id header (on every response, a pass included, and in Context, so
every log line carries it):
{"error":"validation_failed","message":"2 fields need attention.",
"errors":[{"error":"not_finite","message":"This must be a finite number.","field":"items.3.price"},
{"error":"invalid","message":"The email field is required.","field":"email"}],
"requestId":"4f8c2a9e-..."}
- A crash is a fixed 500 in every environment,
APP_DEBUGincluded: "Something went wrong on our side. If it keeps happening, quote reference 4f8c2a9e-...". The detail is in the log Laravel already wrote, under that id. - A deliberate 4xx keeps your sentence:
abort(410, 'This invite has expired.'). A message Laravel made from another exception is NOT shown, since aModelNotFoundExceptionnames your model class; a policy's denial message is. - A 5xx never shows its message, unless you declare it public:
throw HttpError::public(503, 'maintenance', 'Back at 14:00 UTC.', retryAfter: 600). - 429 and 503 carry
retryAfterandRetry-After. Validation becomeserrors[]. - Responses your app RETURNS are never rewritten, so Inertia's 409s pass through.
- HTML pages and Inertia requests keep Laravel's own handling. A guard 422 on
an Inertia request becomes a native
ValidationExceptionafter the session starts, so the form gets flatprops.errors. An oversize Inertia body is still refused immediately.
Workbooks
Rows x columns cannot be checked from the raw bytes, because an xlsx's
<dimension> is a claim the file makes about itself. The guard sets the limits
and holy-sheet
counts them, streaming each part before one cell exists:
$schema = FancyHttpGuard::readWorkbook($request->file('file')->get(), field: 'file'); // or, under this route's limits: $schema = $request->attributes->get('fancy_guard')->readWorkbook($bytes);
- A refusal is a 413:
workbook_too_large, with holy-sheet'slimit,maxandactual. - A file that is not a spreadsheet is a 422 naming the field.
- The limits are paired. The archive cap is the route's body cap, and the
part caps follow
maxCellsat 64 bytes per cell. - holy-sheet is optional.
The HTTP-client normaliser
$response = Http::post($upstream, $data); if ($error = $response->fancyError()) { // null on a 2xx/3xx return back()->withErrors($error->fields)->with('status', $error->sentence); }
It reads the Fancy envelope, FastAPI's detail sentence and 422 list, Laravel's
validation map and message, and HTML or empty bodies.
- A 5xx never shows the upstream's text, fields included.
- It reads at most 64 KiB of the body (
['maxBodyBytes' => ...]).
Settings
php artisan vendor:publish --tag=fancy-http-guard-config. Every limit is a
setting with a secure default:
| Setting | Default |
|---|---|
maxBodyBytes |
1 MiB (the upload profile: 10 MiB) |
maxDepth |
32 |
maxListLength |
10,000 |
maxErrors |
20 |
finiteNumbers |
true |
workbook.maxRows |
100,000 |
workbook.maxColumns |
1,000 |
workbook.maxCells |
100,000 |
Beyond the limits:
profiles: your own named profiles.routes: limits by route name.request_id_header: the request-id header's name.trust_incoming_request_id: off by default. Turn it on only behind a proxy that sets the header.
A bad key or value is refused when the app boots, or when a route declares it.
Contract
The rules are fancy-conformance suites/http/SPEC.md (CC-fancy-0031).
- This package runs all 88 rows of
http/request-guardsand all 82 rows ofhttp/error-envelopein CI. - The Python guard (
fancy-http-guard) runs the same request-guard rows. - The TypeScript normaliser (
@particle-academy/fancy-http-errors) runs the same normaliser rows.
No third-party runtime dependency, only Laravel's own components. MIT.