PHP RFC Debate: Should Literal Scalar Types Join the Type System?

A newly opened RFC by Seifeddine Gmati (implementation: php-src PR #22314) proposes literal scalar types for PHP, letting signatures declare exact values like -1|0|1 or "ascii"|"utf-8" instead of just int or string. Internals discussion weighed the idea against enums, debated float-literal precision issues, constant/enum exclusions, and possible future numeric ranges or pattern-matching alternatives.

PHP contributor Seifeddine Gmati opened discussion on a new RFC, "Literal Scalar Types" (implementation in php-src pull request #22314), which would let type declarations reference specific scalar values directly, e.g. -1|0|1 or "ascii"|"utf-8", rather than only base types like int or string.

Gmati argues the feature covers ground enums cannot: existing APIs already typed as plain int or string (such as array_filter's mode parameter) could gain precise contracts without breaking callers; open-ended value sets (e.g. encoding names) can grow via contravariant union widening without forcing consumers to add default match arms; and literal values remain plain scalars, so they work as array keys, compare with ===, and round-trip through JSON without the ->value/::from() mapping enums require.

Reviewers pushed back on several points. David Gebler doubted enums are as fragile against new cases as claimed. Tim Düsterhus cited the existing RoundingMode enum migration (from the 'Correctly name the rounding mode' RFC) as proof that scalar APIs can be safely retyped to enums via a deprecation path, and pointed to a draft 'non_exhaustive_marker' RFC for formalizing non-exhaustive enums.

On scope, the RFC excludes referencing constants or enum cases in type positions (ambiguous with class names, and enum values are runtime expressions, not literals), and excludes NAN/INF since they are constants, not literals. Mixing literal types with wider base types in a union (e.g. int|'bar') is explicitly allowed by design.

Float literals proved the most contested detail: Düsterhus and Larry Garfield argued floats are too imprecise for exact matching (0.1 + 0.2 !== 0.3) and recommended limiting the feature to int and string literals; Gmati said he is now inclined to drop float support pending further feedback.

Andreas Heigl suggested numeric ranges (e.g. int 1..PHP_INT_MAX) as a natural follow-up; Gmati agreed but said ranges deserve a separate RFC due to added complexity (bounds, inclusivity, coercion). Bob Weinand and Sarina Corrigan raised pattern matching (per the Pattern Matching RFC's future-scope 'parameter/return guards' proposal by Larry Garfield and Ilija) as a possibly more general alternative; Gmati maintains literal types are a distinct, complementary type-system building block, also feeding future array-shape and tuple types, not a substitute for pattern matching.

Gmati also proposed splitting the eventual vote into separate questions covering string literals, integer literals, float literals, and whether literal-to-base-type coercion should be identity-only (matching the existing behavior of true/false/null) or coercive.