Expose the raw query string to the application

[atymic]

Problem

HttpRequestEvent::rebuildQueryString() re-parses and re-encodes rawQueryString on every API Gateway v2 request, and there's no way to get the original back:

if ($this->isFormatV2()) {
    $queryString = $this->event['rawQueryString'] ?? '';
    // We re-parse the query string to make sure it is URL-encoded
    return http_build_query(self::queryStringToArray($queryString), '', '&', \PHP_QUERY_RFC3986);
}

An unencoded URL in a query value gets split on its own &:

in:  location=https://zoom.us/w/1?tk=AAA&pwd=SECRET
out: location => 'https://zoom.us/w/1?tk=AAA'
     pwd      => 'SECRET'

Re-encoding then bakes the split in and turns the ? into %3F, so an app can't tell "this was split" apart from "this was always properly encoded". This isn't hypothetical, it silently truncated live customer links for us (ActiveCampaign has no urlencode modifier, so a merge tag holding a URL lands in the query string raw).

I get why the normalisation is there and I'm not proposing changing it. Just asking to keep the original reachable.

No userland workaround

getQueryString(), getUri() and getQueryParameters() all derive from the normalised property. rawQueryString sits at the event top level, so it's not in getRequestContext() either. The only way in is subclassing the handler to read $event->toArray()['rawQueryString'], which forces a serverless.yml handler swap that's easy to lose on a deploy.

(v1/ALB is worse, not a fallback: AWS has already split those into queryStringParameters.)

Proposed change

Add an accessor:

public function getRawQueryString(): string
{
    return $this->event['rawQueryString'] ?? '';
}

and surface it as a server var in Psr7Bridge::convertRequest():

'BREF_RAW_QUERY_STRING' => $event->getRawQueryString(),

That covers Octane without touching laravel-bridge: OctaneHandler calls SymfonyRequestBridge::convertRequest(), which wraps Psr7Bridge::convertRequest() and then server->add()s its own LAMBDA_* vars on top, so anything already in the PSR-7 server array reaches $request->server in Laravel.

Additive, no behaviour change, no config.

One thing for review: on v1/ALB there's no rawQueryString in the event at all. Empty string, or leave the var unset so an app can tell "not available" apart from "genuinely empty"? Note Psr7Bridge filters $server on !== null, so '' survives but null drops out.

Happy to send a PR if you're open to it, just let me know which way you'd want that to go.

Environment

• Bref 3.0.9 (checked against master), PHP 8.5
• API Gateway HTTP API (payload format 2.0)
• Octane, via brefphp/laravel-bridge

[mnapoli]

Thanks for the report @atymic. I spent time digging into this. Sharing the findings here as I'm thinking about a larger change for Bref v4.

What happens today

On API Gateway v2 (HTTP APIs), Lambda gives us rawQueryString. But Bref doesn't pass it through: it parses it and rebuilds it with http_build_query() before handing it to PHP. In your case, location=https://zoom.us/w/1?tk=xxx&pwd=xxx gets split and percent-encoded, which is correct (the original URL was invalid, per RFC 3986, the ? and & should be encoded) BUT the original string is unrecoverable by the application (so an application that wants to re-parse the query string to do something custom cannot).

On a server, nginx and Apache both pass it through untouched, so Bref breaks the promise "things work like on any server".

Why does Bref rewrite the query string at all?

History lesson (mostly for myself 😄):

• In 2020, v2 support initially passed rawQueryString through verbatim. It was changed shortly after (49110f1) to re-parse + re-encode, "to match the format we get when using PHP outside of Lambda".
• In 2023, the parsing moved to crwlr/query-string (Better support for querystrings (qs) #1437, Add test cases for query arrays without brackets #1509), which added a behavior PHP doesn't have: ?foo=1&foo=2 (no brackets) becomes an array in $_GET, instead of PHP's native last-value-wins.
  • This was a good thing in theory (fix broken native PHP parsing into $_GET). But Laravel and Symfony don't do that and will use the "broken" data from $_GET. API Platform actually re-parses the raw query string to work around that bug.
  • So the normalization, added in the name of "behave like a normal server", actually made Bref the only piece of the stack that rewrites the query string.

This also matters because the raw $_SERVER['QUERY_STRING'] is used for byte-sensitive features like signed URLs and HMAC verification (e.g. Shopify webhooks). Rewriting the raw string can also break that.

Proposal for Bref v4, feedback wanted

• Never touch the raw query string. Pass rawQueryString through untouched, like every web server does. The FPM runtime then behaves exactly like nginx/Apache + PHP-FPM, including PHP's native quirks: ?foo=1&foo=2 = last value wins, dots in keys become underscores. If you want arrays, use foo[]=1&foo[]=2, like on any server.
  • BC impact: bracket-less duplicate keys go back to last-value-wins in $_GET (which was Bref's behavior until 2023 anyway).
• keep the better parser for PSR-7/Octane. For getQueryParameters() and the PSR-7/event-driven runtimes (e.g. Laravel Octane), keep our improved parser that correctly handles duplicates and dots (API Platform made the same choice). Slightly different from FPM, but more correct, and the raw string is intact everywhere either way.

WDYT? Especially interested in whether anyone relies on ?foo=1&foo=2 producing arrays in $_GET on the FPM runtime.

[atymic]

Sounds good to me :) Thanks for your work on this.