feat: HTTP QUERY method support (RFC 10008)

[soyuka]

Q	A
Branch?	main
Tickets	RFC 10008
License	MIT
Doc PR	todo

What

Adds foundational support for the HTTP QUERY method (RFC 10008): a safe, idempotent collection operation that carries its parameters in the request body instead of the URI query string.

#[ApiResource(operations: [
    new Query(parameters: [
        'name' => new QueryParameter(filter: new PartialSearchFilter(), property: 'name'),
    ]),
])]
class Book {}

QUERY /books
Content-Type: application/x-www-form-urlencoded

name=foo&order[name]=asc

How

The whole modern parameter chain (parameter filters, parameter validation, security, strict query-parameter validation) reads values from the _api_query_parameters request attribute. So the feature is a single chokepoint: ParameterProvider sources _api_query_parameters from the QUERY body rather than the query string, negotiated by Content-Type:

• application/x-www-form-urlencoded → shares the query-string grammar, reuses RequestParser::parseRequestParams
• any JSON-based media type → decoded to an associative array
• empty body → no parameters
• unsupported media type → 415 with an Accept-Query response header
• malformed JSON → 400

The new Query operation defaults to read=true, write=false, validate=false, deserialize=false. Because the read/write/validate listeners already derive their behaviour from the operation flags (not blindly from Request::isMethodSafe(), which only recognises GET/HEAD as safe), these defaults treat QUERY as a safe read and keep its body out of resource-input negotiation — no listener changes required. The QUERY body negotiation is a distinct concern owned by the provider, not ContentNegotiationProvider.

This deliberately targets the Parameter API only; the legacy #[ApiFilter] / _api_filters path is not wired (it is on the deprecation track).

Tests

tests/Functional/HttpQueryMethodTest.php: empty body returns the full collection, form-urlencoded and JSON bodies filter, unsupported content type → 415, malformed JSON → 400, unknown parameter → 400 via strict validation. Plus Query metadata defaults unit test.

Out of scope (follow-ups)

• OpenAPI 3.2 query verb emission (PathItem has no query before 3.2)
• HTTP cache / Vary: Accept-Query / Content-Location result URIs
• JSON:API Transform*ParametersListener body sourcing
• Nested JSON syntax for bracket-style filters ({"price":{"gt":100}})

[soyuka]

Good first implementation but to be feature-complete we need to add OpenAPI support.

[soyuka]

RFC 10008 coverage — remaining gaps

Tracking everything in the spec not yet wired, so we have the full picture. This PR lands the core (QUERY operation + body negotiation + 415/400/empty-body). The list below is what's left. We'll take OpenAPI first.

1. OpenAPI emission (do first)

• No query verb on PathItem — slot only exists in OpenAPI 3.2, so it requires bumping/extending the OpenAPI model.
• No request schema generated from the operation's parameters metadata. The QueryParameter set should produce the QUERY body input schema (form-urlencoded + JSON variants), the way query-string params produce parameter objects today.

2. Accept-Query advertisement

• Today Accept-Query is emitted only on the 415 error path (ParameterProvider::parseQueryParametersFromBody).
• RFC § "Accept-Query": the server should advertise QUERY support proactively — at minimum on the OPTIONS response, ideally on successful QUERY responses too. Without it a client cannot discover QUERY support or the accepted media types without first triggering an error.

3. Content-Location header

• RFC: a QUERY response MAY include Content-Location pointing to a resource that returns the same results via plain GET.
• Not implemented. Relevant once we can mint a stable results URI.

4. Location + 303 See Other (equivalent resource / indirect response)

• RFC: server MAY persist the query and respond 303 + Location so the client can GET the saved query later without resending the body.
• Whole indirect-response mode is absent — PR only does direct 200 OK with results inline.

5. Conditional requests → 304 Not Modified

• RFC: If-None-Match / If-Modified-Since evaluated against equivalent-resource semantics, yielding 304.
• No conditional handling on the QUERY path.

6. Caching / Vary

• Real caching is a proxy concern — we only emit HTTP cache headers, we don't cache. So scope here is headers, not a cache key implementation.
• Caveat that still matters: QUERY carries parameters in the body, which proxies key on URI only. So a cacheable QUERY response is unsafe to cache unless we either signal it correctly or keep it non-cacheable. Need to decide what cache-control/Vary headers (if any) we emit for QUERY and document that proxy caching of body-keyed QUERY is generally unsafe.

Already noted as out-of-scope in PR description (kept here for completeness)

• JSON:API Transform*ParametersListener body sourcing.
• Nested JSON syntax for bracket-style filters ({"price":{"gt":100}}) — parser limitation, not strictly RFC.