Json Request Check Bundle Laravel Package

Getting Started

• Install with Composer: composer require iwf-web/json-request-check-bundle. The package targets Symfony (Flex recipe may not exist, so plan to wire it manually).
• Register the bundle in config/bundles.php:

  return [
      // ...
      Iwf\JsonRequestCheckBundle\JsonRequestCheckBundle::class => ['all' => true],
  ];
  

• Publish/author the config at config/packages/json_request_check.yaml. At minimum set a size ceiling so the bundle has something to enforce:

  json_request_check:
      max_size: 1048576      # bytes, 1 MB
      max_depth: 32          # nesting depth
      max_keys: 1000         # top-level/scalar key count (HashDos surface)
  

• First use case to validate end-to-end: point it at a single JSON API endpoint (e.g. POST /api/orders), then curl a normal payload (expect 2xx) and an oversized/wide payload (expect a 4xx before your controller/deserializer runs). If the controller never executes for the bad payload, the listener is wired correctly.
• For a Laravel developer stepping into this: the mental model is a global middleware that runs before request validation and body parsing. In Symfony terms it's a kernel request listener; in Laravel you'd reach for the same shape in app/Http/Middleware. Keep that mapping in mind while reading the bundle source — the interesting logic is the payload checker class, not the Symfony glue.

Implementation Patterns

• Guard the edge, not each controller. Register the listener globally and rely on Content-Type: application/json detection rather than annotating routes. This is the pattern the bundle is built for and avoids forgetting a new endpoint.
• Per-endpoint ceilings. If the bundle exposes per-route or per-firewall options (check the config tree), override limits for endpoints that legitimately accept large payloads (bulk imports, base64 uploads). Otherwise set a strict global default and whitelist exceptions:

  json_request_check:
      max_size: 65536
      paths_excluded:
          - ^/api/bulk-import
  

• Order it before deserialization. Ensure the listener priority puts it ahead of any kernel.request subscribers that read the body (e.g. FOSRest body listeners, API Platform's DeserializeListener). HashDos mitigation is only meaningful if you reject before json_decode allocates the collision-heavy map.
• Pair with Symfony Validator / DTO mapping. Treat the size check as a coarse gate; keep per-field validation in your normal pipeline. Don't try to encode business rules in max_keys.
• Test the guard, not just the happy path. In a WebTestCase (or Laravel's TestCase if you port the checker), assert on the status code for three payloads: normal, max_size + 1 bytes, and a deep/wide JSON object that exceeds max_depth/max_keys. This is the regression suite that catches "someone reordered the listeners".
• Reuse the checker outside Symfony. The payload-inspection logic is the valuable part. If you're a Laravel shop that wants this behavior but not the Symfony bundle, wrap the checker in a Laravel middleware and call it from handle() before $request->json(). That gives you the HashDos guard without a second HTTP layer.
• Expose the limits via env vars. In Symfony config use %env(int:JSON_MAX_SIZE)% so ops can tighten limits in production without a deploy — particularly useful during an incident.

Gotchas and Tips

• Content-Type is trusted. If the bundle keys off the header, a client sending text/plain with a JSON body slips past. If downstream code parses it as JSON anyway (or you have a permissive deserializer), the guard is bypassed. Either enforce application/json upstream or confirm the bundle sniffs the body.
• Content-Length can lie or be absent. Chunked transfer encoding and Transfer-Encoding: gzip mean the header doesn't reflect the decoded body size. Verify whether the check measures the raw stream, the post-decompression size, or trusting the header — and whether that matches your threat model.
• Depth vs. width. HashDos is a width attack (many colliding keys at one level); deeply nested arrays are a recursion/stack attack. Make sure both max_depth and max_keys are actually enforced, not just max_size, or a compact 200 KB payload with 500k keys can still pin a CPU.
• Listener ordering is the #1 debugging headache. If a 413/400 isn't returned and your controller runs anyway, dump the kernel's event dispatcher subscribers (bin/console debug:event-dispatcher kernel.request) and check priorities. xdebug breaking on the checker class is the fast way to confirm it even fires.
• Status code semantics. The bundle likely returns 400 or 413; make sure your API contract and any client retry logic agree. 413 with Retry-After is nicer than 500, and either is better than a controller-level 422.
• Config key names drift between versions. With a 2025-06 release and no recipe, the config tree is your source of truth — read DependencyInjection/Configuration.php before assuming a key exists. Don't copy snippets from the README without diffing against the installed version.
• Low adoption = limited battle-testing. One star and zero dependents means you should pin the version ("iwf-web/json-request-check-bundle": "0.1.*" or an exact tag) and skim the source before production. The logic is small enough to audit, and porting it to a Laravel middleware is a realistic fallback if Symfony integration is awkward for your stack.
• Extension point: if the bundle exposes a checker interface or an event, use it to log rejected payloads (size, key count, route, IP) — this is exactly the telemetry you want when a real HashDos attempt hits, and it costs nothing when it doesn't.