[RFC] [Discussion] Literal Scalar Types

On Mon, Jun 15, 2026 at 3:13 AM Seifeddine Gmati azjezz@carthage.software
wrote:

On Mon, Jun 15, 2026 at 2:24 AM Seifeddine Gmati
azjezz@carthage.software wrote:

Hello Internals,

I'd like to start the discussion on a new RFC adding literal scalar
types to PHP.

Prima facie, I feel like enums already do what this aims to achieve,
much better.

• RFC: https://wiki.php.net/rfc/literal_scalar_types
• Implementation: https://github.com/php/php-src/pull/22314

Thanks,
Seifeddine.

Hi David,

I agree enums are the better fit for a lot of cases. but not all.

1. describing APIs that already exist. array_filter's $mode really
   accepts 0|1|2, but it's typed int because that's all the type
   system can say today. we can't retype it as an enum without breaking
   every caller. a literal union lets the signature state the actual
   contract.

This is probably the strongest case (and should be mentioned on the RFC, I
think), though I'm not sure it's a sufficient justification for the scope
of change.

2. ad-hoc / open value sets. for a library, "ascii"|"utf-8" would need
   its own named symbol ( enum BorderStyle { case Ascii; case Utf8 }, a
   new file, an import ) for what is really two strings. and because an
   enum is a closed set, adding a third style later breaks any consumer
   that match-es over it without a default. widening the union on a
   parameter ( "ascii"|"utf-8"|"unicode" ) is contravariant, so it breaks
   nobody.

I'm not so convinced on this point. You add a new case to an enum, that
library's API isn't inherently broken. Users passing Ascii or Utf8 per the
original case-set remain valid. The only code that breaks there is code
that assumes the enum would never gain another case and the same could be
said of code matching on string literals without a default. And if
"ascii"|"utf-8" is what a library exposes, consumers may treat that as
exhaustive, whereas an enum doesn't inherently break as a type hint. A set
that's expected probably shouldn't be an enum, but the strength of an
enum is precisely that it's a (probably) closed set of values. On the
flip-side, if a set of values is genuinely open-ended, a closed set of
scalar literal unions as a type isn't going to help.

3. scalar interop. a literal value is the scalar, so it works as an
   array key, compares with ===, round-trips through json, etc. enum
   cases are objects and don't.

I think backed enums already cover this through value exposure.

so they overlap a lot, but literal unions reach things enums
structurally can't: existing scalar APIs, and open sets that grow
without a BC break.

Cheers,
Seifeddine.

Hi

1. describing APIs that already exist. array_filter's $mode really
   accepts 0|1|2, but it's typed int because that's all the type
   system can say today. we can't retype it as an enum without breaking
   every caller. a literal union lets the signature state the actual
   contract.

We can retype this kind of API with enums.

See the “Correctly name the rounding mode and make it an Enum” RFC
(https://wiki.php.net/rfc/correctly_name_the_rounding_mode_and_make_it_an_enum)
for an example: We first widen the parameter to accept the enum so that
folks can opt-in to the new API. At a later point we alias the constants
to the corresponding enum cases and deprecate passing the integers and
then we remove the support for the integers (and constants).

Using literal types is going to result in a terrible user-experience,
because the signature does not provide any hint as to which constants
are supposed to be used with the API which means that the resulting
error message is also useless to the user. Enums - or the existing
manual validation - is much preferable here.

2. ad-hoc / open value sets. for a library, "ascii"|"utf-8" would need
   its own named symbol ( enum BorderStyle { case Ascii; case Utf8 }, a
   new file, an import ) for what is really two strings. and because an
   enum is a closed set, adding a third style later breaks any consumer
   that match-es over it without a default. widening the union on a
   parameter ( "ascii"|"utf-8"|"unicode" ) is contravariant, so it breaks
   nobody.

The existing \RoundingMode enum is already intended to be a
non-exhaustive (parameter-only) enum where users are expected to include
a default case in case new values are being added.

I have a very rough draft in
https://wiki.php.net/rfc/non_exhaustive_marker to make this type of
contract more explicit.

Having an “own named symbol” for the allowed values is a benefit to me,
because this makes it easy to reuse the list of allowed values in
different locations without needing to resort to copy and paste, for
example in decorators that just pass through the values without touching
them.

3. scalar interop. a literal value is the scalar, so it works as an
   array key, compares with ===, round-trips through json, etc. enum
   cases are objects and don't.

Enums can be compared with ===.

Best regards
Tim Düsterhus

Hello Internals,

I'd like to start the discussion on a new RFC adding literal scalar
types to PHP.

• RFC: https://wiki.php.net/rfc/literal_scalar_types
• Implementation: https://github.com/php/php-src/pull/22314

Thanks,
Seifeddine.

I think I'm okay with this. David mentioned enums, and I do think enums
are useful in many places where you want types like this, but there's a
simplicity in this that I can't deny, and I like it.

I do like the simplicity of this.

But - especially for floats and ints - the next level would be to allow
not only

public function check(int -1|0|1 $minusOneThroughOne)

but also something like

public function check(int -1..1 $minusOneThrougOne)

which would then also allow

public function check (int 1..PHP_INT_MAX $positiveInt)

would that also be something to be considered? It seems like a logical
alternate option to not have to add every value literally to the option
list...

Cheers

Andreas

                                                           ,,,
                                                          (o o)

+---------------------------------------------------------ooO-(_)-Ooo-+
| Andreas Heigl |
| mailto:andreas@heigl.org N 50°22'59.5" E 08°23'58" |
| https://andreas.heigl.org |
+---------------------------------------------------------------------+
| https://hei.gl/appointmentwithandreas |
+---------------------------------------------------------------------+
| GPG-Key: https://hei.gl/keyandreasheiglorg |
+---------------------------------------------------------------------+

Hi Andreas,

Thanks! Your first example, -1|0|1, is already exactly what this RFC
does: a union of three int literals (you don't even need the int
prefix, just function check(-1|0|1 $x): void {}).

The second part, ranges like -1..1 or 1..PHP_INT_MAX, is a
genuinely different feature. And you're right that it's the logical
next step: enumerating every value doesn't scale, and something like
1..PHP_INT_MAX can't be written as a union at all.

I'd keep it out of this RFC, though. A range isn't a set of literals,
it's a constraint that has to be checked with a bounds predicate ($v

= lo && $v <= hi), and it brings its own design questions: inclusive
vs exclusive bounds, open-ended ranges (1.., ..10), what's allowed as
a bound (plain constants? expressions like PHP_INT_MAX?), and how
coercion behaves at the edges. That's really a refinement-type feature
sitting on top of this one.

So it's a great follow-up, and a natural one once literals exist, but
I think it deserves its own proposal rather than being folded in here.

Cheers,
Seifeddine

Den 15. jun. 2026 kl. 19.23 skrev Sarina Corrigan sarina.corrigan@gmail.com:


It may be worth mentioning that within the Pattern Matching RFC future scope, and mentioned a couple times within the discussion thread for the RFC, there is a similar proposal that would allow for this without using specific literal types.

It's outlined in https://github.com/Crell/php-rfcs/blob/master/pattern-matching/future.md under "Parameter or return guards"

It would allow for:

function setLogLevel (string $level is 'debug' | 'info' | 'warning' | 'error'): void {}

Of course, I don't think that a potential future scope of an in-draft RFC is reason to dismiss a more direct implementation of literal scalar types, but it may be useful to compare other ways we could achieve the same functionality. I personally find pattern matching within parameter/return types more versatile while keeping direct typing system more simplified. Specifically for a range feature that Ben Ramsey brought up, pattern matching for parameters seems much more appropriate.

All that being said, I would gladly welcome literal scalar types.

Hello Internals,

I'd like to start the discussion on a new RFC adding literal scalar
types to PHP.

• RFC: https://wiki.php.net/rfc/literal_scalar_types
• Implementation: https://github.com/php/php-src/pull/22314

Thanks,
Seifeddine.

Hi,
This sounds very promising. But I would be confused about receiving a TypeError when just the value of the parameter is wrong.

As described in the RFC if I send 4 to a parameter that could only be 1, 2 or 3. I would expect a TypeError if I sent “abc” ?

Kind regards
Lars Nielsen

Hi Lars,

I think the confusion comes from treating "type" and "value" as two
separate things, which is the usual mental model. Literal scalar types
deliberately blur that line: each value is itself a type, a unit type
containing exactly one value.

So 1|2|3 is not "an int that happens to be restricted", it is the
union of three unit types 1, 2 and 3. Under that view, both 4
and "abc" fail for the same reason: neither is a member of the
declared type. There is no separate "the value is wrong" category, it
is all type membership, so a TypeError is the consistent outcome.

It is the same thing that already happens with the true type today:
passing false to a true parameter is a TypeError, even though
both are booleans.

Hi Tim,

I think I might agree here, and others have raised the same concern on
Discord. Dropping float literals for now simplifies the RFC, so I am
inclined to do that, though I would like to hear what others think
before removing them.

We debated allowing float as a backing type for enums, and eventually decided against it for a similar reason: It's not stable or discrete enough to be useful, and no other language we looked at supported them.

I'm still undecided on the RFC as a whole (I need to fully read it first), but would support limiting the literals to just int and string.

--Larry Garfield

Hi

For what it is worth, I am personally fine with tenths(0.1 + 0.2)
failing to match 0.3. This is not new behaviour: 0.1 + 0.2 == 0.3
is already false, and a match (0.1 + 0.2) already skips a 0.3 arm
for exactly the same reason. So a literal float type behaves
consistently with comparison and match, rather than introducing a
new surprise.

Yes, it is consistent with the existing behavior, but I don't think that
this makes it any less confusing. And for this specific proposal, adding
support for floats would be a deliberate decision rather than just
something that naturally follows from “existing === semantics” as with
match() which works on two values rather than values + types.

On your concrete questions: 4e3 is a valid float literal and works
today; it normalizes to 4000.0 (the type also stringifies as
4000.0). NAN and INF, on the other hand, are not literals but
constant identifiers that go through constant resolution. They are out
of scope for the same reason FOO is above: NAN $foo could just as
well mean a class named NAN.

Yes, I'm aware (based on a look at the implementation). This was
intended to be a subtle note that this is not explicitly spelled out in
the RFC.

The RFC text should comprehensively explain the behavior all possible
edge cases and ambiguities so that folks can form an educated opinion
based on the RFC text alone without needing to be able to understand the
implementation.

Writing that out, I also notice that the “Ecosystem” sub-section is
missing from the “RFC Impact” section (and the “To Existing Extensions
” sub-subsection would probably also be useful to know) and the voting
widget is also missing.

Best regards
Tim Düsterhus

On Mon, Jun 15, 2026, 20:05 Seifeddine Gmati azjezz@carthage.software
wrote:

While this RFC works alongside the pattern matching proposal by Larry and
Ilija, neither requires the other. The two are unrelated for several
reasons.

So to answer your question, no, I am not looking for pattern matching. I
see these as two distinct features that address different needs within the
language.

I don't believe they are addressing entirely different needs. I believe the
feature that static analysis tools support is pattern matching more than it
is typing. The question for me becomes whether patterns be represented
through types, or whether they should be matched against values.

Strictly denoting types and validating patterns are two separate concerns.
One asks "What can I do with this?" while the other asks "Is this within
expected bounds?". I am personally not against validating patterns within
type declarations, as is supported in Typescript, Scala (I believe), and to
an extent PHP with false|true. But I do believe they are different concerns.

I also think that, this being a form of pattern matching, if approved would
set a direction for the pattern matching RFC to treat patterns more closely
as types than assertions and guards (as their RFC currently proposes). I am
again not saying this is a bad thing, but it is worth acknowledging.

FWIW: The list is extremely busy right now with (new) proposals that I
feel would do well waiting until after the feature freeze. Personally
I'm having troubles keeping up with all the discussion, RFCs, and code
review. I assume that others feel similar, so that would explain the
absence of feedback.

Hi Tim,

Thanks for the read, and no worries about the timing. The list is clearly
busy right now, so I appreciate you getting to it.

All four remarks are addressed in v0.3, which I've just pushed:

1. The RFC specifies "Integer literals, with an optional leading minus
   sign: 1, 0, -1.", are leading + signs also legal? What about multiple
   signs or spaces?

A single leading unary + or - is accepted, so both -1 and +1 are
legal, and +1 denotes the same type as 1.

2. I don't believe this statement is accurate. ... I believe that
   "making literal types strict" is the correct choice (for the consistency
   reasons), but I don't think this specific statement is backed up by
   evidence.

Agreed, and I've dropped the claim entirely. The case for strict matching
now rests only on consistency with null/true/false, and on the single
rule that a type whose identity is one value matches only that value.

3. I don't think making this a parser error is in the interest of
   "providing useful error messages". This should be a compiler error ...

Done, it's a compile-time error now, consistent with how function foo(true&Foo $foo) {} is handled.

4. For the "Ecosystem" impact: I believe there is also an impact to
   anything consuming types from Reflection (such as mappers).

Spelled out explicitly now.

I'm also concerned about folks shooting themselves in the foot with type
checking performance for "wide unions of literal types". It might make
sense to provide a dedicated performance section in the RFC.

Added. It states plainly that the membership check is O(n) left-to-right,
uses your exact example (passing 9 to 0|1|2|3|4|5|6|7|8|9 scans all ten
members, while 0 returns immediately), and notes that although this is
the same behaviour every union type already has, literal unions invite much
larger member counts, so the footgun is more reachable here.

That example also prompted a Future Scope note, which I've added. If
integer range types were later introduced, the engine can collapse a
contiguous run like 0|1|...|9 into a single range 0..9 and check it
with two bound comparisons instead of a linear scan, turning the wide-union
cost into O(number of ranges). This is what we already do in Mago, so I'm
fairly confident it will carry over to the engine. See
https://github.com/carthage-software/mago/blob/14bf9e84884117ff385fa4ebfd90dd08622e7359/crates/codex/src/ttype/atomic/scalar/int.rs#L818-L958
https://github.com/carthage-software/mago/blob/14bf9e84884117ff385fa4ebfd90dd08622e7359/crates/codex/src/ttype/atomic/scalar/int.rs#L818-L958

Note: The implementation has not been updated, I will address it later
when/if the RFC is accepted

Best regards,
Seifeddine

Hey Seifeddine,

I'm not sure why my last message did not receive a response, but I will try
again.

similar to what we see in TypeScript
This is exactly my concern. Literal types are useful in TypeScript, but
they are also often directly overused. I do not think PHP should encourage
the same pattern.

I would prefer type aliases, such as Robert’s proposal from last year, as a
foundation before considering this direction:
https://wiki.php.net/rfc/typed-aliases

My concern is that the RFC encourages public APIs like function f(1|2|3 $x)
or function sort('asc'|'desc' $direction), where magic scalar values become
part of the runtime API instead of being represented by a properly domain
modeled entity.

Modern AI-assisted engineering makes semantic naming even more important.
Inline literal types such as 1|2|3 or 'asc'|'desc' provide less semantic
signal than named concepts such as enums or type aliases. This can make
code harder not only for humans, but also for AI tools that rely heavily on
names and surrounding context. However, I'm aware that this secondary
argument is not very plausible in this group.

Language features should be evaluated from the long-term user and
API-design perspective, not only from the static-analysis perspective. From
that perspective, I think this RFC approaches the problem from the wrong
side.

Kind regards,

Jorg

Het Seifeddine,

Hi Nick,

Thanks for the feedback.

1. if I did not miss anything the empty string case is not covered.
   Would "" be legal? Any thoughts on providing ways to explicitly
   disallow empty strings? I don't think this should be further scope --
   because we would need to make sure that we actually have a usable syntax
   to disallow empty strings.

Empty strings are supported; "" is a valid literal string type.
Regarding non-empty-string, that is a separate concept from literal
types. However, this RFC provides the building blocks to express it in
the future, through negated types (e.g., !""). There's also the option
of doing refinement markers on base types (e.g., string[1..]), which
IIRC Gina is working on or mentioned it somewhere.

Example ( using literal types, negated types, and type aliases ):

type NonEmptyString = ! "";

function getNonEmptyString(): NonEmptyString {
  return 'ok'; // ok
  return ''; // err
}

Sounds good, thanks. Would be great if this would be spelled out in the RFC.

2. having strict and non-strict mode in PHP is bad enough, IMO. Seeing
   this brought further, and combined with "literal" (literal should be
   literal) feels wrong -- a coerced true is de facto not a literal 1,
   it's a coerced true. I understand that you recommend strict and want
   to leave it to a vote, but I feel like the "Coercive matching
   (alternative)" section should make a stronger point against it, to
   discourage a tempting "always been like that" for a new concept.

The RFC highlights that strict matching is already the established
behavior for existing value-types in PHP, and is the preferred path.
true, false, and null never coerce, even in coercive mode. Maintaining
this for all literal types is the only way to ensure a consistent type
system where a unit type matches exactly its identity, hence it is the
preferred option.

I believe we speak past each other here. With you that it should be
strict matching, which you also prefer! I am just asking to make the
"Coercive matching (alternative)" section more explicitly spell out why
it isn't a good choice. As in: literal types would be a new feature for
PHP, why would we apply and carry over lose semantics to something
that's called "literal"? Not sure if I express myself good enough here,
get what I mean? In short: make a stronger point for strict!

3. the performance section is thin; solely addressing what Tim brought
   up. I am wondering, does introducing this have any implications for
   non-literal types? Having a benchmark would be nice. I also agree with
   Jorg, that a benchmark comparing the performance with enums (memory +
   speed) would be helpful.

This proposal has no performance impact on non-literal type checks.
Comparing it to enums isn't quite apples-to-apples; enums are objects
and follow standard object comparison logic, whereas these are scalar
identity checks.

Maybe a benchmark would make a strong point for your proposal? Maybe
better performance? Likely mess memory usage?

4. the last part of the previous point extends to the general usefulness
   of the feature. I again have to agree with Jorg: it is not clear what
   problem it is trying to solve. Why not enums? It is a trend to get rid
   of stringy APIs, and magic strings and ints -- for reasons. But this
   feature will encourage bringing them back. With an enum you define it in
   one place (easier to refactor), with literal scalar types you repeat it
   in multiple places. Do we really want that?

The core goal is to expand the type system to allow for more precise
descriptions of data. While literal types can be used standalone, they
are fundamental for future features like array shapes, where keys and
values often need to be narrowed to specific literals (e.g., a status
key being exactly 'ok' | 'error'). A richer type system, similar to
what we see in TypeScript, requires literals as a foundational
building block.

Example ( using literal types, type aliases, array shapes, and integer
ranges ):

type ActionResponse = ['status' => 'ok' | 'error', 'message' => 
string, ?'data' => array];

interface Action {
  public function perform(Context $ctx, Request $request): ActionResponse;
}

type PingActionResponse = ['status' => 'ok', 'message' => 'pong', 
'data' => ['time' => 0..]];

final readonly class PingAction extends Action {
  public function perform(Context $ctx, Request $request): 
PingActionResponse {
    return ['status' => 'ok', 'message' => 'pong', 'data' => ['time' 
=> get_time()]];
  }
}

Well, I believe you know my opinion here, and that we have fundamentally
different ones -- which is fine. Before we bake anything more types into
the language we should standardise PHPDoc, make an official spec. We got
so many things wrong over the recent years that it would be the more
sensible approach. And then the question remains, should we even inline
types? Or is PHPDoc just great with some improvements and official
acknowledgement?

Not sure if potential future language features, that might never come,
are a good selling point that make an argument for getting literal types
in now.

RE type aliases specifically... Something like: "we need to inline types
to have them right where they are used, but then we want to have type
aliases to move them away elsewhere right after" does make zero sense to
me. How does both fit in the very same argument?

Some years ago I wrote the following somewhere (a "thing" refers to an
"object"):

This is one of the reasons I don’t like TypeScript. They put type
definitions everywhere.

My thinking:
An email is a thing. By having that thing we can describe it, with a
type. In real life, something that doesn’t exist, can’t have a type.

So why would we do it differently in programming?

A dedicated file/class for each thing is imho better. Eventually, the
thing is the type by itself. Because if you need the type, you need
the thing.

What would be cool, is to have a type standard library so that not
everyone must write it on their own.

Just TypeScript having all these things doesn't mean that they are good
for PHP. We should not make PHP another TypeScript.

Cheers,
Seifeddine.

--

Cheers
Nick