Utils Laravel Package

Getting Started

Require the package with Composer (composer require laragraph/utils) and confirm how it is wired into your GraphQL endpoint. This package sits in front of webonyx/graphql-php request parsing, so look first at its request parser/middleware and the tests covering JSON and multipart batch requests. Your first use case should be protecting a GraphQL endpoint from malformed batch payloads: v2.3.2 rejects JSON and multipart bodies that webonyx would otherwise parse as a batch containing non-object entries, preventing a TypeError. Exercise a valid single operation, a valid batch array, and malformed shapes such as {"query":"…","0":"x"} before rolling it out.

Implementation Patterns

• Route through the package parser: Place the package’s GraphQL request parsing/middleware in front of your GraphQL controller so malformed batch payloads are rejected before they reach webonyx.
• Treat batch input as an array of operation objects: Valid batch requests should be arrays whose entries are objects. Do not accept objects that merely contain a query key plus numeric keys as a batch.
• Cover both transport formats: Add feature tests for application/json and multipart/form-data; the v2.3.2 fix applies to both parsing paths.
• Map rejections consistently: Convert invalid batch bodies into your API’s standard 400/422 response rather than allowing a 500 from a downstream TypeError.
• Integrate early in the request lifecycle: Run parsing before authorization or resolver execution so invalid payloads never consume GraphQL execution resources.

Gotchas and Tips

• Behavior change in v2.3.2: Payloads like {"query":"…","0":"x"} now produce a controlled rejection instead of a TypeError. Update tests and client expectations that previously saw a 500.
• Do not infer batch mode from array-like JSON: A JSON object with numeric keys is not a valid batch. Let the package enforce object entries rather than normalizing the payload yourself.
• Test multipart edge cases separately: Multipart parsing can produce different PHP array shapes than JSON; verify malformed entries are rejected in both paths.
• Check middleware order: The parser must execute before your GraphQL handler and before anything that assumes a valid webonyx request.
• Debug with the raw parsed body: When a client reports an unexpected rejection, inspect the decoded JSON/multipart structure before blaming webonyx.
• Pin the patch version: This is a targeted bugfix release, but it changes error behavior for malformed batches. Document the minimum version (^2.3.2) if your clients depend on controlled rejection rather than 500s.