Answer UnionType comparisons from an identity-keyed FiniteTypeSet instead of scanning every member

[phpstan-bot]

Summary

Comparing a union of constant strings against another one cost one isSuperTypeOf() call per
pair of members. Membership among such values is exact-value equality, so it is a set lookup:
this PR keys a union's members by value identity once, caches that on the union, and answers
isSuperTypeOf(), isSubTypeOf(), accepts(), isAcceptedBy(), equals() and tryRemove()
from the map. O(n*m) member comparisons become O(n+m), and a single-value lookup becomes O(1).

The issue asked for a trie. A trie earns its keep on prefix or pattern queries — a router
matching URIs — and none of these comparisons are that (ConstantStringType::isSuperTypeOf()
on another constant string is value === value). As noted in the issue's comment thread, an
identity-keyed hash is the structure this actually wants, and it answers the same question for
constant ints, bools, null and enum cases, so all of them are keyed, not just strings.

Measured on 400-member unions (UnionType API directly, before → after):

operation	identical unions	disjoint unions
isSuperTypeOf	204 ms → 8 ms	575 ms → 6 ms
isSubTypeOf	203 ms → 6 ms	575 ms → 6 ms
accepts	2139 ms → 7 ms	2355 ms → 13 ms
isAcceptedBy	1504 ms → 6 ms	1731 ms → 12 ms
isSuperTypeOf(single value)	240 ms → 2 ms

End to end, analysing tests/bench/data/big-constant-string-union.php goes from 1.46 s to
0.76 s. PHPStan's own self-analysis is unchanged (55.8 s → 55.4 s), so ordinary code pays
nothing for the map.

Changes

• src/Type/FiniteTypeSet.php (new) — a union's members indexed by value identity. Keys
  null, constant scalars other than floats, and bare enum cases; everything else goes to
  $others, so a single object type next to fifty constant strings does not defeat the
  optimization, it only means callers still consult those few members the slow way. Also
  exposes containedIn() for union-vs-union answers and hasClassStringMember() for callers
  that hand a member back rather than only comparing values.
• src/Type/UnionType.php — builds the set lazily once per instance
  (getFiniteTypeSet()) and uses it in isSuperTypeOf(), isSubTypeOf(), accepts(),
  isAcceptedBy(), equals() and tryRemove().
• src/Type/TypeCombinator.php — finiteUnionMembers() reuses the shared, cached set
  instead of keying the union again on every intersect(). Its class-string bail is kept: the
  class-string flag is part of a constant string's representation but not of its value, and
  intersect() hands a member back.
• build/PHPStan/Build/SkipTestsWithRequiresPhpAttributeRule.php — the rule demanded an
  inverse comparison operator before checking that the comparison was about PHP_VERSION_ID
  at all, so a test method whose first statement is an if on any other binary operator (a
  || chain, say) crashed the analysis with ShouldNotHappenException. The new test file hit
  it. The PHP_VERSION_ID check now comes first.
• tests/bench/data/big-constant-string-union.php (new) — benchmark input.

Root cause

UnionType answered every comparison by walking $types and asking each member, and the
callers that pass a union walk it again — so union-vs-union was O(n*m) virtual calls. For
members that stand for one concrete value that scan is pure waste: two of them are
interchangeable iff they are equals(), and any two that are not equals() are disjoint. A
key derived from the value settles both questions with one hash lookup.

The same shape repeated across the whole comparison family, which is why the fix does too:

• isSuperTypeOf(value) — yes if the map holds it; otherwise every keyed member answers no,
  so only unkeyed members are left to ask.
• isSubTypeOf(union) / equals(union) — set containment between the two maps.
• accepts(value) — only the positive answer is value identity; a member that does not hold
  the value can still accept it through scalar coercion. So the miss is not simply no, but it
  is the same for every member of a kind (all constant strings behave alike as acceptors, and
  so do all cases of one enum), and consulting one member per kind is enough.
• accepts(union) — a member standing for a single value never accepts more than one of the
  other union's values, so the member-by-member or() cannot come out yes and its result is
  discarded for the compound answer anyway; go straight to isAcceptedBy().
• tryRemove(value) — drop the one member under that key instead of running
  TypeCombinator::remove() against every member.

Floats are the one finite scalar left out on purpose: equals() does not agree with value
identity for them (-0.0 === 0.0, NAN !== NAN). Template types are excluded outright, their
comparison semantics are not value identity, and a type that merely contains a value — an
intersection with an accessory type, a whole single-case enum, a conditional type resolving to
a constant — is excluded by an equals() check against its own constant scalar type.

Test

tests/PHPStan/Type/FiniteTypeSetTest.php. The map is an optimization, so the property worth
testing is that it never disagrees with comparing member by member: each test runs the real
operation against a reference implementation that spells out the loop UnionType used before,
over a matrix of 17 unions × 18 query types (and 17 × 17 union pairs) — 2397 cases covering
constant strings, ints, bools, null, enum cases, mixed-kind unions, unions diluted with an
object / a float / a general string / a class-string constant, and BenevolentUnionType.
accepts() additionally asserts that no member attaches a reason to its answer, which is what
lets one member of a kind stand in for the rest without changing error messages.

The reference implementations caught two real mistakes while writing them (the accepts()
compound-delegation tail and BenevolentUnionType::isAcceptedBy()'s or-semantics), and
mutating the fix afterwards — inverting the accepts() union shortcut, dropping the
completeness guard in isSuperTypeOf(), dropping the equals() guard in
FiniteTypeSet::key() — fails 254, 6 and 12 cases respectively.

Being an optimization, none of this fails without the fix; the benchmark data file and the
numbers above are what show the change did something. make tests (20029 tests), make phpstan and make cs are green. make name-collision fails identically with and without the
change (tests/PHPStan/Build/data/final-class-rule-pipe.php uses PHP 8.5 pipe syntax that the
detector's parser rejects on this PHP version).

Probed and deliberately left alone:

• TypeCombinator::union() already collapses constant scalars and enum cases through
  describe-keyed maps, so it is O(n) — no change needed.
• TypeCombinator::doRemove()'s finite-type loop is O(n*m), but for a union of values it is
  unreachable: isSuperTypeOf() settles the removal before it, and tryRemove() now handles
  the hit.
• IntersectionType, the composite sibling, gets nothing: its members are not
  mutually-disjoint values, so identity keying does not apply.
• UnionType::getFiniteTypes() dedupes by describe(VerbosityLevel::cache()). Switching it to
  identity keys would collapse a class-string constant with a same-valued plain one, which
  describe() keeps apart — left as is.

Fixes phpstan/phpstan#15008