Cache filter URLs with more than one value

[titouanmathis]

Closes the gap .planning/research_facets.md (#166) identified as the blocker: the page cache keyed query args already, but not the shape a filter actually emits.

What was broken

cacheQueryArgs works and is proven end to end — ?lang=fr is served from nginx today. But QueryKey::VALUE_CHARACTER_CLASS had no comma, and a bracketed name can never match the keyed-name pattern. So both spellings of a multi-value filter bypassed:

URL	Before	After
?genre=rock,jazz	bypass	HIT, from nginx
?genre[]=rock&genre[]=jazz	bypass	HIT, from the drop-in, same file
?s=chaise	bypass	HIT when s is keyed with a pattern

?genre=rock,jazz is the format docs/guide/query-filters.md documents, so the framework's own filter URLs were the one shape its own page cache refused to store.

How the bracketed form is handled

nginx cannot read it — a variable name may not hold brackets, and there is no $arg_genre[]. Rather than teach it to guess, it declines: a bracketed name fails knownQueryPattern(), so the request goes to PHP, and the drop-in joins the members and serves the file the comma form wrote. A couple of milliseconds slower, same bytes, no second file.

What never happens is nginx reading $arg_genre, finding it empty and serving the unfiltered page to someone who asked for a filtered one. That property — the two readers never compute keys that disagree — is what every rule in QueryKey exists for, and it is unchanged.

Members are joined in request order and never sorted. Sorting is the obvious fix and the wrong one: nginx cannot sort, so a sorted key is one only PHP could compute. Two orders are two files holding the same HTML — wasted disk, which is the cheap half of the trade.

A member may not contain a comma. ?genre[]=rock,jazz asks for one term whose slug has a comma; ?genre=rock,jazz asks for two. Joining the first would key it where the second lives, so it bypasses.

Values instead of patterns

cacheQueryArgs: [
    'page',                                     // any value the charset allows
    'lang' => ['fr', 'en'],                     // only these two
    'posts_per_page' => [12, 24, 48],
    'genre' => '^[a-z0-9-]+(?:,[a-z0-9-]+)*$',  // a pattern, when a list will not do
],

A project states what it knows and the pattern is compiled from it. Values are quoted, so 1.5 matches 1.5 and not 165. An empty list matches nothing — "these values are allowed" with none named is a bypass, not a free pass.

The page cache config and the query filters config stay independent: neither reads the other, and there is no require of one config file inside another. Naming a filter for the cache is its own step, in the file that owns caching. The cost is stated in both guides — a filter added later is a bypass until it is named here.

Search, by parameter

s bypasses unless it is keyed, and keying it means giving the pattern that bounds it. No new flag — it is the mechanism that already existed.

Verification

• 2155 tests across all five suites, exit code 0 (checked, not read off the summary). composer lint clean of anything new; composer analyse reports no issues.
• New unit coverage for both spellings, the mixed spelling, the comma-in-member collision, an empty member, %5B%5D, derivation and precedence, and search.
• packages/starter/tests/smoke/NginxKeyedQueryTest.php gains the two cases that matter, because only a real nginx can settle a claim about two implementations of one algorithm: the comma form must be HIT/nginx, and the bracketed form must be HIT/php out of the same single file.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KZusb9DU8coizq3CDgHEqi

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.66%. Comparing base (276215c) to head (dd53e71).

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #167      +/-   ##
============================================
+ Coverage     85.55%   85.66%   +0.10%     
- Complexity     2510     2535      +25     
============================================
  Files           194      194              
  Lines          6938     6988      +50     
============================================
+ Hits           5936     5986      +50     
  Misses         1002     1002              

Flag	Coverage Δ
unittests	85.66% <100.00%> (+0.10%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.