Hi Bob,

Thanks for the quick reply!

Let me respond inline to avoid backtracking too much.

I have a bunch of questions and feedback:

The requirement of ordering seems unnecessary to me - why would we not want to be able to write <T: Box<U>, U: Box<T>>. Alternatingly recursive types are not unheard of. Seems like an arbitrary restriction; and for compilation purposes it only requires collecting all parameter names before evaluating them.

Your tests also show restrictions around intersection types, e.g. "Type parameter T with bound mixed cannot be part of an intersection type" for 'class Foo {} function x<T>(): T & Foo {}'. What's the motivation behind it? This looks fairly natural to me: x() promises to return an instance of Foo which also fulfills the bound T. Any child class of Foo which happens to implement T will fulfill that contract.

I would like to plead to skip the arity validation, except for "more parameters than allowed":

• This inhibits graceful addition of generics - any library adding them requires callers to immediately update all caller sites.
  • It would also make addition of generics to Iterator classes etc. completely uncontroversial.
• This would be more in line with PHP's general "no type is effectively the highest possible bound" approach. I.e. "class A extends Box" and "class A extends Box<mixed>" would be equivalent.
• This would also allow for future incremental runtime generics: you'd start with <never> and as you call stuff with values, the type becomes broader.

This is the one thing which makes the whole RFC a non-starter for me if required:

Typing is optional in PHP!

Your tests show that this specific example is allowed, which strikes me as odd. Why would we not check the arity here?

class Container {}
function f(Container<int> $x): Container<string> { return $x; }

Diamond checks:

Are these necessarily problematic? if you inherit Box<int> and Box<string>, it simply means that the generic parameter, when placed in a contravariant location will accept int|string, when placed into return or property types it'll evaluate to never.

If you disagree (that's possibly fine), a diamond covariant parameter should be allowed in any case though, i.e. if Box<+T>, then an interface shall be able to implement Box<string>, Box<int>. At least at a glance I don't find such a test - if it already works, nice, then please just add the test!

Is class ABox implements Box<self> allowed, or do we need to write implements Box<ABox>?

I'm also not sold on the turbofish syntax. I hate it in Rust, which I have to write nearly daily. I forget these :: SO often. And then the Linter yells at me and I correct it.
I understand that there are language limitations, in particular with the array syntax, but honestly, I'd rather just have the parser shift in favor of the existing syntax - for these rare conflicting cases forcing parenthesis around the generic would be nicer, i.e. [A<B, B>(C)] would continue carrying the meaning it has today, and we'd require writing [(A<B, B>(C))] for that case.

I'm not quite sure if + and - are the proper choices. I'm more used to C# myself with in and out being more obvious to me. I also admit that I initially assumed "+" to be covariant - the sum of stuff accepted, and "-" contravariant, subtracting what can be returned. But this particular bikesheds color is not too important to me.

Otherwise, it's a pretty solid RFC which should be extensible with runtime generics eventually. (In particular runtime generics on the class inheritance level should be a no-brainer to add with the existing syntax.)

Thanks,
Bob

Thanks for the careful read. Going point by point.

1. Ordering of type parameter declarations

The restriction is implementation-level, not fundamental. We register
parameter names before we compile bounds, so allowing <T: Box<U>, U:
Box<T>> is a "small" change. I left it out for the initial cut because
I didn't want to bake mutually-recursive bounds into the spec without
seeing whether anyone actually wants them in practice. If others agree
this is worth having, I'm happy to drop the restriction before vote.

Yes, that's the impression I had - an arbitrary restriction to make it a bit simpler at compile time.

I'd suggest just dropping it, why have it, actually? It should be a relatively easy change. I don't see any concrete advantage of this, apart from the minor simplification this restriction would have in compiler.

2. Type parameters in intersection types

The check rejects an intersection where one side is a type parameter
whose bound is mixed, because the erased form can be anything,
including a scalar. Scalars don't intersect with anything, today. (
ref https://3v4l.org/mdvFA#v )

The error message in the test you saw is precisely about the unbounded
case. If T is bound to an object-shaped type (T: object, T: SomeInterface, T: SomeClass, ...), then T & Foo is allowed. the
erased form is guaranteed to be a legal intersection operand. So this
is the same rule PHP already enforces today, just applied through the
erased form.

Ah, I see, it needs a T: object. (or named class). It's not quite obvious from the error message, so I'd suggest adding a suggestion for "at least T: object or a stronger bound" then.

That makes some sense. The question would be if never types should be possible to reached, but this I've basically asked already when asking about diamond checks.

3. Arity validation at consumer call sites

I think this one is a misunderstanding. Arity validation only fires
when the caller writes turbofish. Without turbofish, nothing changes
at the call site:

function id<T>(T $v): T { return $v; }

id($x);                 // no validation, no behavior change
id::<int>($x);       // arity + bound checked

So a library can add generic parameters to its public surface and
every existing caller (none of which uses turbofish, because turbofish
doesn't exist today) keeps working unchanged. The validation is opt-in
at the use site. Same for new and method calls.

This is exactly the graceful-addition story you're asking for. The
existing tests demonstrate it.

This is not quite obvious from the RFC. I'd recommend adding a subsection to "What is enforced where" detailing that these are not checked: I thought "turbofish arity" would apply to everywhere, not just explicitly where the ::<> syntax is actually used.

Are they also not checked for inheritance? Or just for caller sites?

Sorry for missing it in tests, you have a LOT of tests!

4. Generic args on a non-generic class in a signature

class Container {}
function f(Container<int> $x): Container<string> { return $x; }

This is accepted, and on purpose. PHP doesn't load classes from
signatures, they load on use: https://3v4l.org/DnIKQ#v

To validate arity at compile time, we'd have to load Container,
which is a behavioral and performance regression. The cost of being
strict here is much higher than the cost of being permissive. The same
logic that already lets you reference an unloaded class in a signature
lets you reference an unloaded class with type arguments in a
signature. Validation happens once the class actually gets resolved at
a use site (new, turbofish call, etc.).

I'm actually suggesting validation at runtime here, i.e. once the class type check passes, to check whether the arity is matching for the class of the argument.

I'm certainly not asking for compile time checks here. But leaving this unchecked sort-of makes it the odd-one out here.

5. Diamond inheritance

The diamond check is necessary because methods get substituted with
the type arguments at link time. Consider:

interface Box<T> { public function set(T $v): void; }

class C implements Box<int>, Box<string> {}

After substitution, C must implement both set(int): void and
set(string): void. PHP has no way to represent two methods with the
same name and different signatures ( i.e overloading ), one of them
has to win, and either choice silently breaks one of the parent
contracts. Same problem in contravariant position. The check rejects
this at link time rather than letting it produce a class that violates
its own interface.

For purely covariant slots you have a point, get(): int and get(): string could in principle be reconciled to get(): int|string (an
LUB). The current implementation rejects all diamonds uniformly to
keep linking deterministic and to avoid synthesizing union types
during inheritance. Relaxing it for the covariant case is a reasonable
follow-up, not something I want to bake in before vote.

You got it the wrong way round, the union needs to be allowed on the parameters, not the return type.

set(string): void and set(int): void can be merged into set(string|int): void.

I'd also like to mention here that:

interface A { public function set(int $v): void; }
interface B { public function set(string $v): void; }
class C implements A, B { public function set(int|string $v): void {} }

is perfectly valid today. Not allowing this for the contravariant case would make it inconsistent with what's currently supported in PHP.

This needs no overloading at all.

6. class ABox implements Box<self>

It is allowed and works as you'd expect. self resolves to the
implementing class.

interface Box<+T> { public function get(): T; }

class ABox implements Box<self> {
    public function get(): self { return $this; }
}

var_dump((new ABox)->get() instanceof ABox); // true

Nice!

7. Turbofish

We have to disagree here. Turbofish:

• has zero parser conflict with comparison operators in expression position
• is uniform across new, function calls, method calls, FCCs, attributes
• requires no context-sensitive disambiguation rule

The alternative adds a rule a developer has to learn and apply at
exactly the worst places (inside attributes, array expressions,
ternaries). I'd rather pay the :: tax than introduce a
context-sensitive parser rule that bites people inside attributes
specifically. Rust's choice was a forced one because of <> overload,
and it's the right one for PHP too for the same reason.

Alright, let's disagree here.

8. • / - markers

Picked because they don't require any new reserved words. in/out
reads well but I'm not comfortable burning two keywords for a feature
where two pieces of punctuation already do the job.

On the "+ = sum of accepted" intuition: the convention here is the
standard one from variance literature. + marks positions where the
type can be widened (covariant, e.g., returns), - marks positions
where it can be narrowed (contravariant, e.g., parameters). It also
matches Hack, Scala, and Kotlin, so there is prior art the ecosystem
already maps to.

I understand, I've never used any of those languages for more than targeted edits, so I didn't know.

I guess it's fine to not diverge here.

By the way, you don't necessarily need a new keyword, in fact you could just allow two consecutive T_STRING at that position and emit a parser error when the first one is neither of "in" or "out".

Thanks,
Bob

Thanks for the reply!

1. Ordering of type parameter declarations

Agreed, dropped. Forward references and mutually recursive bounds
within a single parameter list are now allowed:

function f<U : T, T>(U $x): T { /* ... */ }            // forward
class Pair<T : Box<U>, U : Box<T>> {}                  // mutual

Defaults still require backward-only references, meaning omitted
arguments resolve in one pass at instantiation. Direct self-reference
at the head of a bound (<T : T>) is still rejected; the indirect
form (<T : Box<T>>) is still allowed.

Diff: https://github.com/php/php-src/compare/9ebcf28cef5563a63fe0bcc2fd5ec45211fa1f15..f8ced4dacacda2038118bcc889f4905a92cf05de

2. Intersection error message

Improved the diagnostic to point directly at the fix instead of just
stating the rule. The message now reads:

Type parameter T with bound mixed cannot be part of an intersection
type; use an object-shaped bound (e.g. T: object)

Diff:
Thanks for the reply!

1. Ordering of type parameter declarations

Agreed, dropped. Forward references and mutually recursive bounds
within a single parameter list are now allowed:

function f<U : T, T>(U $x): T { /* ... */ }            // forward
class Pair<T : Box<U>, U : Box<T>> {}                  // mutual

Defaults still require backward-only references, meaning omitted
arguments resolve in one pass at instantiation. Direct self-reference
at the head of a bound (<T : T>) is still rejected; the indirect
form (<T : Box<T>>) is still allowed.

Diff: https://github.com/php/php-src/compare/9ebcf28cef5563a63fe0bcc2fd5ec45211fa1f15..f8ced4dacacda2038118bcc889f4905a92cf05de

2. Intersection error message

Improved the diagnostic to point directly at the fix instead of just
stating the rule. The message now reads:

Type parameter T with bound mixed cannot be part of an intersection
type; use an object-shaped bound (e.g. T: object)

Diff: https://github.com/php/php-src/compare/f8ced4dacacda2038118bcc889f4905a92cf05de..6b5588d8e927d60e4b4509658af62601dfa0802a

3. Arity validation at consumer call sites

You're right that the RFC didn't say this clearly. Added a "What is
not checked" subsection under "What is enforced where" that lists the
exact sites where the engine intentionally omits arity or bounds
validation. The whole point of opt-in is the graceful-addition story
you're after; the RFC now spells that out.

4. Runtime arity check at call boundaries

In principle, sure. Once the runtime confirms the value matches the
class, we can also validate the signature's type arguments against the
class's actual declared arity and bounds. So in:

class C {}
function foo(C<int, string> $x): void {}

foo(new C());

we'd error because C has no generic parameters but the signature
supplied two type arguments.

The catch is that this isn't only about parameters. It applies to
every place the engine resolves a class-typed type expression at
runtime.

So a bit more complicated, not a small change. I want to spend more
time on it before committing to text: what exactly gets validated,
where the result gets cached so we aren't paying for it on every typed
call, how it interacts with the substitution chain at link time, and
what the hot-path cost actually is on a profiled workload. I'd like to
see what others on the list think too, since the call is a trade-off
between strictness and performance and people will weigh those
differently.

If after that the answer is "yes, fold it in", I'll fold it in. But I
don't want to promise it inside this RFC until I've done the
investigation.

5. Diamond inheritance - I had the direction wrong

Yea, sorry. Contravariant (parameter) positions are the ones that
merge cleanly into a union, not return positions. Your example is
right.

For the generic case, the contravariant side is the easy one:

interface Box<-T> { public function set(T $v): void; }

class C implements Box<int>, Box<string> { /* set(int|string) */ }

The implementer's substituted prototype is the union of the two
contravariant slots.

The covariant side is more nuanced. get(): int and get(): string
merged would have to return both ( i.e. int & string ), and PHP
rejects intersections involving scalars (because impossible!). So a
covariant diamond with scalar bindings is unrepresentable. It only
becomes representable when the type parameter is bounded by an
object-shaped type, in which case the implementer's return type
collapses cleanly to an intersection:

interface Box<+T : object> { public function get(): T; }
interface A {}
interface B {}

class C implements Box<A>, Box<B> {
    public function get(): A&B { /* ... */ }
}

Here A & B is a valid PHP intersection, so the merge is sound.

I'll look into this. I think we can fit it into this RFC, but I want
to investigate the implementation first. I keep the RFC and the
implementation in sync and don't want to commit to text that isn't
backed by working code yet.

Thanks,
Seifeddine.

3. Arity validation at consumer call sites

You're right that the RFC didn't say this clearly. Added a "What is
not checked" subsection under "What is enforced where" that lists the
exact sites where the engine intentionally omits arity or bounds
validation. The whole point of opt-in is the graceful-addition story
you're after; the RFC now spells that out.

4. Runtime arity check at call boundaries

In principle, sure. Once the runtime confirms the value matches the
class, we can also validate the signature's type arguments against the
class's actual declared arity and bounds. So in:

class C {}
function foo(C<int, string> $x): void {}

foo(new C());

we'd error because C has no generic parameters but the signature
supplied two type arguments.

The catch is that this isn't only about parameters. It applies to
every place the engine resolves a class-typed type expression at
runtime.

So a bit more complicated, not a small change. I want to spend more
time on it before committing to text: what exactly gets validated,
where the result gets cached so we aren't paying for it on every typed
call, how it interacts with the substitution chain at link time, and
what the hot-path cost actually is on a profiled workload. I'd like to
see what others on the list think too, since the call is a trade-off
between strictness and performance and people will weigh those
differently.

If the answer after that is "yes, add it,", I'll fold it in. But I
don't want to promise it inside this RFC until I've done the
investigation.

5. Diamond inheritance

Yea, sorry. Contravariant (parameter) positions are the ones that
merge cleanly into a union, not return positions. Your example is
right.

For the generic case, the contravariant side is the easy one:

interface Box<-T> { public function set(T $v): void; }

class C implements Box<int>, Box<string> { /* set(int|string) */ }

The implementer's substituted prototype is the union of the two
contravariant slots. No new type-system rules are needed.

The covariant side is more nuanced. get(): int and get(): string
merged would have to return both ( i.e. int & string ), and PHP
rejects intersections involving scalars (because impossible!). So a
covariant diamond with scalar bindings is unrepresentable. It only
becomes representable when the type parameter is bounded by an
object-shaped type, in which case the implementer's return type
collapses cleanly to an intersection:

interface Box<+T : object> { public function get(): T; }
interface A {}
interface B {}

class C implements Box<A>, Box<B> {
    public function get(): A&B { /* ... */ }
}

Here A & B is a valid PHP intersection, so the merge is sound.

I'll look into this. I think we can fit it into this RFC, but I want
to investigate the implementation first. I keep the RFC and the
implementation in sync and don't want to commit to text that isn't
backed by working code yet.

Thanks,
Seifeddine.

Hi Bob,

Pulled an all-nighter on #5 because the more I thought about it the
more it seemed like the right thing to do, and it turned out to
compose really cleanly with the existing parametric LSP machinery.
Both directions are now in:

Contravariant diamond -> union merge
Covariant diamond on object-bounded T -> intersection merge

The RFC has a new "Diamond inheritance" subsection covering both:
https://wiki.php.net/rfc/bound_erased_generic_types#diamond_inheritance

Genuinely happy with how this turned out. Example from the RFC:

interface Renderable {}
interface Cacheable {}

class Article implements Renderable, Cacheable {}

interface Pipeline<T : object> {
    public function process(T $value): T;
}

interface RenderingPipeline extends Pipeline<Renderable> {}
interface CachingPipeline extends Pipeline<Cacheable> {}

class ArticlePipeline implements
    RenderingPipeline,
    CachingPipeline,
    Pipeline<Renderable & Cacheable>
{
    public function process(Renderable | Cacheable $value): Renderable
& Cacheable {
        if ($value instanceof Renderable && $value instanceof Cacheable) {
            return $value;
        }
        return new Article();
    }
}

The synthesized prototype across the three views is
process(Renderable | Cacheable): Renderable & Cacheable. The merge
is computed at link time against PHP's existing union and intersection
operators, so no new type-system rules are needed.

Thanks for pushing on this :D

Cheers,
Seifeddine.

On 11 May 2026 22:17:22 BST, Seifeddine Gmati azjezz@carthage.software
wrote:

The principle: as long as we don't change the semantics of existing
syntax, no future improvement introduces a BC break. Reified generics,
for example, can be added later as opt-in, just like how HackLang did
it (https://docs.hhvm.com/hack/reified-generics/reified-generics-migration/).
A class or function would need to declare #[ReifiedGenerics] (or
similar) to opt into reified semantics; everything else continues to
behave exactly as the bound-erased model specifies. Library and
framework authors then choose the strictness-vs-performance tradeoff
that fits their use case, and existing code never breaks because the
default behavior never changes.

This feels like a cop-out to me. Imagine we had done the same for
visibility keywords: "private" was a reserved word, but the engine
didn't enforce it, it was just there for static analysers; then later,
we added an opt-in attribute #[EnforceVisibility]. Either everyone would
use it and whinge about it not being the default; or nobody would use
it, and whinge about the language having a broken visibility system.

Or imagine if we implemented scalar type declarations, but couldn't
decide whether to make them fully-static or auto-coercing, so we
implemented a switch that had to be set at the call-site, and was widely
misunderstood ... oh, wait, we did that one...

The existing SA tools (PHPStan, Psalm, Mago) aren't just type
checkers. Type checking is part of what they do, but they also handle
a much larger surface: types PHP itself has no notion of
(positive-int, non-empty-lowercase-string, class-string<Foo>,
list{1, 3, "hello"}, and 100s more, see
https://carthage-software.github.io/suffete/universe/elements.html),
plus code quality rules, security analysis, dead code detection, and
so on. A first-party tool would need to compete on that whole surface
to be useful, anything narrower would disappoint the audience that
actually wants SA.

I think it's possible to separate "people who want static analysis" from
"people who want the type system to be efficiently enforced". And it
would be perfectly reasonable to maintain separate tools for those
separate audiences.

Take Java, for instance: every Java compiler will automatically complain
about basic type violations; but there are still plenty of third-party
Java static analysis tools. I don't think that indicates a flaw in the
compiler design; it's just different tools for different audiences.

In the same way, a bundled tool that statically enforced generic types
and nothing else would still have value - particularly if it was
somehow mandatory, like a pre-processing step.

--
Rowan Tommins
[IMSoP]

Hi Larry,

Thank you for your review.

As you note, this RFC is a little more than erased generics; it does provide a little validation, and reflection support (in addition to a standardized syntax that's much more understandable than the current de facto standard docblock syntax). That's not nothing, and is a marginal improvement over the status quo. The question is whether that is enough of a benefit, and what future improvements it makes easier/harder.

I'd argue this RFC makes future improvements strictly easier, not
harder. see https://wiki.php.net/rfc/bound_erased_generic_types#future_scope.
The work this RFC does (syntax, parsing, compile time enforcement,
reflection) is baseline infrastructure that any generics
implementation in PHP will need regardless of approach. Landing it now
gives us a foundation to build on.

Technically, anyone using Symfony or Laravel is "using generics" in that Symfony and Laravel have generic doc-types on their code. That doesn't imply that everyone building a site with Symfony or Laravel is regularly running PHPStan to verify those, or adding their own doc-types to match it.

I disagree here. Someone using a Laravel collection class without
engaging with its @template annotations isn't "using generics",
they're consuming a typed API and ignoring the type parameters. That
pattern continues unchanged under this RFC: a user can call
$collection->map(...) without ever writing or reading a generic type
argument. The only place behavior changes is inheritance: someone who
extends or implements a generic class is now required to provide type
arguments (e.g. class MyCollection extends Collection<int>), and
that get enforced at both compile time and runtime, because concrete
type arguments get substituted into method signatures.

Where this becomes a land-mine is less the production deploys today, but that future improvements become BC breaks. [...] My fear is that people who don't use SA tools will write code on top of someone else's generic code, not care that their types are buggy, not notice, and then we start enforcing it in the future and their code breaks.

This is the right concern to raise, and I think it's addressable
without needing the "your types are wrong, not covered by BC" escape
hatch you propose below.

The principle: as long as we don't change the semantics of existing
syntax, no future improvement introduces a BC break. Reified generics,
for example, can be added later as opt-in, just like how HackLang did
it (https://docs.hhvm.com/hack/reified-generics/reified-generics-migration/).
A class or function would need to declare #[ReifiedGenerics] (or
similar) to opt into reified semantics; everything else continues to
behave exactly as the bound-erased model specifies. Library and
framework authors then choose the strictness-vs-performance tradeoff
that fits their use case, and existing code never breaks because the
default behavior never changes.

So the "BC only for sloppy code" risk you describe doesn't
materialize, sloppy code today stays sloppy tomorrow at exactly the
same level.

My concern is something like this:

function foo<T>(T $val): bool {}

// With this RFC, this will compile and run, and maybe error inside foo() in oddball ways, or not.
foo::<int>('beep');

Because the type param isn't enforced. So someone is going to write code that bad, guaranteed. (This is PHP, after all.)

Now fast forward a few years, and we figure out a way to performantly enforce that check at runtime and turn that function call into a call-site TypeError. I would consider that a good improvement to the language. However, it would also mean that the previous mismatched line would now generate an error where it didn't before. And the author is going to get up in arms about how "PHP is breaking my code and destroying the language why can't they respect BC" and so on and so on, because we've seen that movie several times now.

But what I would absolutely not want to see is someone arguing that "well we can't start enforcing that type at runtime, because someone might have stupid code." Or, even worse, #[ParamTypeMismatchesThatsOk] as an attribute on the function to opt-out of enforcing it, the way we did for return types on magic methods. I would consider both of those to be Very Bad(tm) outcomes.

So the question for me is how do we set it up, both technically and politically, so that if/when we figure out how to enforce that we can do so without creating another "boo hoo you broke my code" round of blog posts, as those are quite bad for PHP's image.

Another option, if we want to take the stance that SA is The Solution(tm) to generics, is to ship an actual first-party SA tool with PHP.

I want to push back on this strongly. speaking as Mago's author for a moment.

The existing SA tools (PHPStan, Psalm, Mago) aren't just type
checkers. Type checking is part of what they do, but they also handle
a much larger surface: types PHP itself has no notion of
(positive-int, non-empty-lowercase-string, class-string<Foo>,
list{1, 3, "hello"}, and 100s more, see
https://carthage-software.github.io/suffete/universe/elements.html),
plus code quality rules, security analysis, dead code detection, and
so on. A first-party tool would need to compete on that whole surface
to be useful, anything narrower would disappoint the audience that
actually wants SA.

That leaves two options, neither good:

1. A weaker tool than what exists. This doesn't serve the audience
   that wants real SA, and users will rightly be frustrated that PHP
   shipped something less capable than third-party alternatives.

2. A tool competitive with existing ones. This is probably a year or
   two long C project requiring a dedicated team, on top of the PHP core
   team's existing scope. As someone who built a full toolchain in Rust
   from scratsh following Psalm/Hakana's footsteps, I can tell you this
   is substantially harder than it looks, and it would be considerably
   harder in our case than it was for me, for two reasons:

   2.1. Mago is written in Rust, which is a more productive language
   for this kind of tool and has the ecosystem to match. Building the
   equivalent in C, against PHP's existing engine constraints, means a
   much higher cost per feature, per bug fix, per refactor.

   2.2. Mago isn't part of PHP. If we get variance wrong, we ship a
   fix the same day. sometimes twice a day, sometimes once a week. We
   aren't bound by the php-src release cycle, and we iterate as soon as
   we have a fix. A first-party SA tool inherits PHP's release cadence:
   fixed-cadence releases, feature freeze windows, stability guarantees.
   For a tool whose value depends on keeping up with framework patterns,
   library conventions, and emerging idioms, that release shape is wrong.

Beyond the engineering cost, there's a parser problem: PHP's current
parser doesn't produce the full CST that an SA tool needs. You'd need
a new parser, a static name resolver, a static reflection system that
doesn't execute files to extract type information, and so on, a
substantial reimplementation of analysis infrastructure in C, which
the community already has high-quality versions of in Rust and PHP.

In short: shipping a first-party SA tool would be a large, probably
multi-year, investment for a result that's almost certainly worse than
the tools the community has already built. I don't think it's a good
use of PHP's resources, and I'd argue strongly against it.

In general, several of those issues are entirely self-created, and PHP can easily resolve them.

1. Nothing says we can't provide a first-party SA tool that's written in Rust instead of C.

2. Nothing says a first-party SA tool must follow the exact same cadence as the engine. Making improvements to it at the same time as a .z release of the engine is completely reasonable; it would be purely an administrative decision to do that or not.

First-party doesn't have to mean "in the php-src C code directories." Though leveraging some parts of those as externs could certainly make sense.

(Joking: Should we just ship Mago with PHP? :-) )

I agree with Bob that the +/- syntax is very confusing. I would much rather use in/out, as seen in Kotlin and C#, which are both vastly more self-documenting and match what some of our peer languages are doing.

No strong preference here. I went with +/- because that's what
HackLang uses and it's familiar to me, but in/out is fine if
that's the consensus. Happy to switch if enough people prefer the
keyword form.

Kotlin and C# have several orders of magnitude more users, so the "familiarity" argument goes firmly in that direction.

An interesting quirk I found in my previous research is that languages that use : for inheritance use : for bounding generics. Languages that use "extends" for inheritance also use "extends" for bounding generics. PHP uses "extends", so that pattern would suggest we use "class Box<T extends FooBar>" rather than :.

I'd disagree on this one. class A<T extends C> extends B reads
awkwardly to me, especially when the bound is scalar or a union eg.,
class A<T extends int|string> extends B, is rough to parse visually.
The colon form keeps the type-parameter bound visually distinct from
the class's own extension relationship, which I think is the more
important consistency to optimize for.

I don't disagree with you here. As I said, it's more that I want to bring it up and make sure it's an explicit decision to use a different signifier than everyone else.

I fully expect "turbofish" to result in all kinds of slide shenanigans at conferences. At least on my slides. :-)

It hasn't been a problem in Rust, and I don't think it will be in PHP
either. (Looking forward to the slides though)

At what point did I say slide shenanigans are a problem? :-)

I'd be completely OK with lowering the argument cap from 127, too.

that makes sense in principle, but assuming you mean the
actual-parameter cap rather than the type-parameter cap, that's a
separate RFC and would itself be a BC break. Worth doing eventually,
just not as part of this one.

No no, I meant the type argument cap.

function foo<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P>(/* */) {}

That's 16 type arguments, an order of magnitude less than the cap, and I'll already say any such code should be rejected on sight as bonkers. So reserving more than one bit for future flags seems completely fine to me, and perhaps advisable.

Why is ReflectionGenericVariance backed? I don't see what the ints add.

It's backed because the values match what the engine uses internally.
no strong preference though, i can switch it to a unit enum if that
reads better.

I'd probably omit it, but if it's kept, the RFC should at least include that explanation.

OK, having read the full RFC, it seems to be sort of "mostly-erased" generics. There is notably more enforcement than the term "erased" would imply. [...] It looks like, in practice, basically everything on the declaration side is enforced; it's just the call side that is unenforced. Is that an approximately accurate summary?

Approximately, yes, declaration-side enforcement is substantial,
call-side type arguments are erased. The proposal is closer to Java's
model than Python's, but I want to keep the "erased" terminology
because the defining property, type arguments not available at
runtime, is what distinguishes this from reified generics.
"Bound-erased" is the precise term: bounds are enforced where they can
be (declaration sites, substituted method signatures), type arguments
themselves are erased at use sites. That said, your point about
expectations is fair, I'll consider moving the enforcement section
higher in the RFC to set those expectations earlier.

And explicitly calling out something like "despite the name, this is mostly-enforced generics." Or something like that, which seems more accurate.

Would this be enforceable?

class Collection<T> {
public function add(T $val): void {}
}

$c = new Collection<int>();

$c->add('string'); // Error, or would this be allowed at runtime?

My gut sense is that is the most common place where it would come up; function/method generics are going to be a lot less common than class generics, so that would be the place to ensure we get as much enforcement as we can.

If I understand correctly, this RFC would allow for foo(Collection<int> $c) {}, but wouldn't actually enforce it at runtime. Within the function, instanceof Collection would still work, but there's no instanceof Collection<int> alternative. Am I reading that correctly?

yes. that's exactly the erasure behavior. the type argument isn't
available at runtime, so instanceof Collection<int> is the same as
instanceof Collection. If you pass a Collection<string> to a
function expecting Collection<int>, runtime accepts it because both
are Collection at runtime; the mismatch is caught by SA, not by the
engine.

I think at this point I am still skeptical, but warming to it, and could be convinced. But more convincing is needed. And lunch, which I think I need after reading all of this. :-)

Hopefully the above moves you a bit further along. Please let me know
if you have more questions or concerns.

Cheers,
Seifeddine.

Two additional questions:

• With reflection, would it be possible to tell what a given object was instantiated with, or only the class? new ReflectionObject($listOfInts)->getTypeParam() => ReflectionType(int)? Or is that also the erased part?

• I assume that dynamically specifying the type parameter is also right-out, yes?

function make(string $className, int $count) {
$c = new Foo<$className>();
foreach ($count as $i) {
$c->add(new $className());
}
return $c;
}

--Larry Garfield

I'd like to put a syntax proposal on the table that may address Rowan's
concern, and that also addresses something I'm worried about independently:
the migration path for existing libraries.

How does a library that uses @template docblocks today migrate to native
syntax without forcing a BC break on its consumers? Multiplied across the
libraries out there, this is a major point of tension for the ecosystem we
need to anticipate.
Existing @template annotations were adoptable gradually because they're
invisible to the engine.
Native <T> syntax, as the RFC proposes it, doesn't have that property: a
library cannot adopt it without bumping its minimum PHP version and pulling
all its consumers with it.

We've solved this exact problem once before for attributes. The #[...]
syntax was deliberately designed so older PHP versions would parse it as a

line comment, which is what made the adoption across the ecosystem so

smooth.
The same trick is available for generics if we pick the right delimiter.
Concretely, write #<...> everywhere <...> appears in the current RFC:
declarations, inheritance clauses, type uses in signatures, call-site
arguments. One syntax, used uniformly.

Three benefits, beyond the migration story:

1. FC for free. A library can adopt native generics in source today and
   continue running on older PHP versions, because the engine just sees
   comments. No need to coordinate with the min-PHP bump.
2. The turbofish goes away. No need to disambiguate < from less-than
   comparison. With #<...>, the token is unique and unambiguous everywhere: at
   declaration, use, and call site. We get to drop a whole grammar mechanism
   rather than introduce one.
3. Rowan's concern is addressed typographically. Anything inside #<...> is
   the erased, SA-enforced layer; everything outside follows the engine's
   normal runtime-checked rules.

For codebases that want to adopt native generics while still supporting
earlier PHP versions, #<...> would need to sit at the end of a line so
older parsers consume it as a # line comment. Code targeting only
generics-aware PHP can write it inline. The line-break constraint is a
transitional code-style cost, not a permanent property of the syntax, and
it's bounded by however long libraries support pre-generics versions.

WDYT? I expect Seifeddine has good reasons to prefer the current syntax.
I'd like to put this on the table because the FC story it unlocks, combined
with the turbofish simplification, might be worth the trade-off and might
help gather a broader consensus.

Cheers,
Nicolas

Nicolas,

I think this is a brilliant idea. I was thinking that libraries would take
ages to adopt this new syntax if they didn’t want to break compatibility
with existing PHP versions, and your proposal solves this issue in a great
way.

The price to pay is slightly uglier syntax, but we already went through
that with attributes. I think that initially we all thought the attribute
syntax was quite terrible, but nowadays no one bats an eye at it.

Cheers,

Carlos

I'd like to put a syntax proposal on the table that may address Rowan's concern, and that also addresses something I'm worried about independently: the migration path for existing libraries.
How does a library that uses @template docblocks today migrate to native syntax without forcing a BC break on its consumers? Multiplied across the libraries out there, this is a major point of tension for the ecosystem we need to anticipate.
Existing @template annotations were adoptable gradually because they're invisible to the engine.
Native <T> syntax, as the RFC proposes it, doesn't have that property: a library cannot adopt it without bumping its minimum PHP version and pulling all its consumers with it.
We've solved this exact problem once before for attributes. The #[...] syntax was deliberately designed so older PHP versions would parse it as a # line comment, which is what made the adoption across the ecosystem so smooth.
The same trick is available for generics if we pick the right delimiter. Concretely, write #<...> everywhere <...> appears in the current RFC: declarations, inheritance clauses, type uses in signatures, call-site arguments. One syntax, used uniformly.
Three benefits, beyond the migration story:

1. FC for free. A library can adopt native generics in source today and continue running on older PHP versions, because the engine just sees comments. No need to coordinate with the min-PHP bump.
2. The turbofish goes away. No need to disambiguate < from less-than comparison. With #<...>, the token is unique and unambiguous everywhere: at declaration, use, and call site. We get to drop a whole grammar mechanism rather than introduce one.
3. Rowan's concern is addressed typographically. Anything inside #<...> is the erased, SA-enforced layer; everything outside follows the engine's normal runtime-checked rules.

For codebases that want to adopt native generics while still supporting earlier PHP versions, #<...> would need to sit at the end of a line so older parsers consume it as a # line comment. Code targeting only generics-aware PHP can write it inline. The line-break constraint is a transitional code-style cost, not a permanent property of the syntax, and it's bounded by however long libraries support pre-generics versions.
WDYT? I expect Seifeddine has good reasons to prefer the current syntax. I'd like to put this on the table because the FC story it unlocks, combined with the turbofish simplification, might be worth the trade-off and might help gather a broader consensus.
Cheers,
Nicolas

How would generic types be expressed in parameters and return types?

// Current RFC:
function DoStuff<T>(myParam: T, otherParam: int): T {
    // ...
}

Existing PHP versions will have no clue what T is. Only one of the uses of T here is inside <...>. Wrapping the others in #<...> would be syntactically incoherent (and rather ugly, I think). But the only alternative that comes to mind is:

function DoStuff#<T>(myParam#: T, otherParam: int)#: T {}

// which would have to look like this in projects continuing to support prior PHP versions:
function DoStuff#<T>
(
    myParam#: T
    , otherParam: int // bizarre comma placement
)#: T
{
    // ...
}

Syntax parsing would, I suspect, be rather more complicated, unless you required the type to be placed in parentheses, which would only make the syntax even less appealing:

function DoStuff#<T>(myParam#:(T), otherParam: int)#:(T) {}

// and in projects continuing to support prior PHP versions:
function DoStuff#<T>
(
    myParam#:(T)
    , otherParam: int
)#:(T)
{
    // ...
}

If not for those (major, in my view) syntactical issues, I might've been on board with the idea. (Just to be clear, I don't have voting privileges.) Conceptually, it feels proper to use "#" again for structured metadata that has some engine-enforced functionality, but which is primarily targeted at (static analysis) developer tools. But once one realizes that generics will be used in places outside of <...>, I think the viability of the syntax crumbles, and I'd rather just have the original proposal.

Hi all,

Thanks Seifeddine for putting this together. This is an impressive
piece of work, and the general approach is sound to me. Looking forward
to where this discussion lands; I hope we'll reach enough consensus to
merge.

Le ven. 15 mai 2026 à 13:13, Rowan Tommins [IMSoP]
imsop.php@rwec.co.uk a écrit :

Generic type information currently lives in optional levels because it
lives in optional syntax (docblocks).

This is, quite frankly, nonsense.

If you write a function with no native type information, but an "@return int" docblock, PHPStan will report an error for a missing return statement at Level 0, and for an incorrect return statement on Level 3.

There's no relationship between the syntax needed and the types of analysis performed.

That's the point: native syntax means the language
did the work, and tools surface violations at whatever strictness the
user already has configured.

As Daniil pointed out, SA tools analyse code with offline parsers, not by loading and reflecting it; so the native enforcement of arity etc will still need to be reimplemented in each tool.

The RFC will act as a standardisation of what tools should enforce around those things; but that could equally be done by agreeing a set of conformance tests based on the existing docblock syntax. In fact, those conformance tests would be needed whatever the syntax, if the goal is to eliminate different handling in different tools.

The actual situation is that PHP has a runtime-checked layer (what the
engine validates) and an SA-checked layer (what tools verify). The two
layers complement each other. Native generics formalize a part of the
SA-checked layer that the engine can partially absorb.

I can agree with this framing. I think where we differ is that you see unifying those layers in one syntax as a good thing, but I see it as a bad thing: I think it is useful to be able to look at the code, and understand which parts are definitely going to be enforced by the runtime-checked layer.

I'd like to put a syntax proposal on the table that may address Rowan's
concern, and that also addresses something I'm worried about
independently: the migration path for existing libraries.

How does a library that uses @template docblocks today migrate to
native syntax without forcing a BC break on its consumers? Multiplied
across the libraries out there, this is a major point of tension for
the ecosystem we need to anticipate.
Existing @template annotations were adoptable gradually because
they're invisible to the engine.
Native <T> syntax, as the RFC proposes it, doesn't have that property:
a library cannot adopt it without bumping its minimum PHP version and
pulling all its consumers with it.

We've solved this exact problem once before for attributes. The #[...]
syntax was deliberately designed so older PHP versions would parse it
as a # line comment, which is what made the adoption across the
ecosystem so smooth.

Though recall that was an after-passage change; the original attribute syntax was << >>, which everyone apparently hated, so we changed it twice in rapid succession. (I am very very glad we did switch to the Rust-inspired syntax, but just making sure the history is clear.)

The same trick is available for generics if we pick the right
delimiter. Concretely, write #<...> everywhere <...> appears in the
current RFC: declarations, inheritance clauses, type uses in
signatures, call-site arguments. One syntax, used uniformly.

Three benefits, beyond the migration story:

1. FC for free. A library can adopt native generics in source today and
   continue running on older PHP versions, because the engine just sees
   comments. No need to coordinate with the min-PHP bump.
2. The turbofish goes away. No need to disambiguate < from less-than
   comparison. With #<...>, the token is unique and unambiguous
   everywhere: at declaration, use, and call site. We get to drop a whole
   grammar mechanism rather than introduce one.
3. Rowan's concern is addressed typographically. Anything inside #<...>
   is the erased, SA-enforced layer; everything outside follows the
   engine's normal runtime-checked rules.

For codebases that want to adopt native generics while still supporting
earlier PHP versions, #<...> would need to sit at the end of a line so
older parsers consume it as a # line comment. Code targeting only
generics-aware PHP can write it inline. The line-break constraint is a
transitional code-style cost, not a permanent property of the syntax,
and it's bounded by however long libraries support pre-generics
versions.

WDYT? I expect Seifeddine has good reasons to prefer the current
syntax. I'd like to put this on the table because the FC story it
unlocks, combined with the turbofish simplification, might be worth the
trade-off and might help gather a broader consensus.

Cheers,
Nicolas

I'm not a huge fan of this approach. With attributes, most use cases already had a natural line-break built in. The only one that didn't was parameter attributes, and that was easy enough to work around by veritcalizing the parameter list, which is already common practice when it gets long.

In this case, what you're proposing is I'd need to write something like this:

class Foo
#<Bar>
implements Baz
#<Beep>
{
public do(
#Bar
$bar) : List
#<string>
)
}

That's just disgusting. :-) I'm never going to do that. I'll just write it properly, but now I have comment tags floating around my code forever that aren't actually comments. Please, no.

Really, Attributes' FC-friendliness was a one-off. Pretty much any other new syntax we've added has always been a "upgrade or get a parse error, deal", like any other language. I realize Symfony and its BC policy puts it in a position where a hard-cut to the new syntax would be harder than for most projects, but the cost is just way too high.

--Larry Garfield

Hey Nicolas,

Am 15.05.2026 um 14:09 schrieb Nicolas Grekas nicolas.grekas+php@gmail.com:

I'd like to put a syntax proposal on the table that may address Rowan's concern, and that also addresses something I'm worried about independently: the migration path for existing libraries.

How does a library that uses @template docblocks today migrate to native syntax without forcing a BC break on its consumers? Multiplied across the libraries out there, this is a major point of tension for the ecosystem we need to anticipate.
Existing @template annotations were adoptable gradually because they're invisible to the engine.
Native <T> syntax, as the RFC proposes it, doesn't have that property: a library cannot adopt it without bumping its minimum PHP version and pulling all its consumers with it.

We've solved this exact problem once before for attributes. The #[...] syntax was deliberately designed so older PHP versions would parse it as a # line comment, which is what made the adoption across the ecosystem so smooth.
The same trick is available for generics if we pick the right delimiter. Concretely, write #<...> everywhere <...> appears in the current RFC: declarations, inheritance clauses, type uses in signatures, call-site arguments. One syntax, used uniformly.

Three benefits, beyond the migration story:

1. FC for free. A library can adopt native generics in source today and continue running on older PHP versions, because the engine just sees comments. No need to coordinate with the min-PHP bump.
2. The turbofish goes away. No need to disambiguate < from less-than comparison. With #<...>, the token is unique and unambiguous everywhere: at declaration, use, and call site. We get to drop a whole grammar mechanism rather than introduce one.
3. Rowan's concern is addressed typographically. Anything inside #<...> is the erased, SA-enforced layer; everything outside follows the engine's normal runtime-checked rules.

For codebases that want to adopt native generics while still supporting earlier PHP versions, #<...> would need to sit at the end of a line so older parsers consume it as a # line comment. Code targeting only generics-aware PHP can write it inline. The line-break constraint is a transitional code-style cost, not a permanent property of the syntax, and it's bounded by however long libraries support pre-generics versions.

WDYT? I expect Seifeddine has good reasons to prefer the current syntax. I'd like to put this on the table because the FC story it unlocks, combined with the turbofish simplification, might be worth the trade-off and might help gather a broader consensus.

Cheers,
Nicolas

I'd like to ask you: do we need to migrate this quickly?

For attributes the #[] syntax was chosen, because it was actually on the table in the first place - we needed a delimiter - and by chance it's something generally on its dedicated line of code - the primary target being classes and methods.

Types? They're neither generally suffixed to a line (except for classes with many extends/implements and for classes without any as well as return types). Everything else is in the middle of the line.

It doesn't really fit here. And also it has a bit of ugliness. Would you really want to use #<...> long-term? I wouldn't compromise long-term syntax for short-term benefits.

Also, again, do we need people to switch over to the language provided generics right now? As far as I see, most libraries and frameworks support a 2~3 years old PHP version on their master version (I.e. what becomes their next major).
People can still use @template for now. It's not a fundamental ability which wouldn't be there without this feature.
Unlike attributes, which were more or less not doable without manual hand-rolled docblock parsing (as opposed to a handful static analysis tools which handle docblock parsing).

Another benefit of it would probably be, if we were to introduce reified generics over the next few versions of PHP, the blast radius of previously-unverified types now becoming checked is much smaller than when every framework already had first-class support for it.

So, having a slower adoption of language-generics could actually be a feature rather than an annoyance.

Bob

Straw man example:

class Foo ~~Foo<T> extends Bar ~~Bar<int,T> {
public function foo(string ~~non-empty-string $in): array ~~list<T> {
...

Maybe PHP would process the syntax, but not the semantics, of the extra
type information; SA tools would then be free to invent new pseudotypes
within that framework, without needing to wait for a full PHP release
cycle every time.

This feels like it would be isomorphic to attributes, no? Syntax validated, available via reflection, but nothing done with it.

Yeah, the basic concept is "attributes on types", but with a more concise syntax.

There are, I think, three basic cases such a syntax would need to handle:

• the "SA type" is the "runtime type" qualified by a generic parameter, either placeholder or concrete: e.g. Collection vs Collection<T> or Collection<int>, array vs array<Foo>
• more generally, the "SA type" is the "runtime type" with extra rules applied: e.g. string vs non-empty-string
• the "SA type" is something that just can't be expressed at all, and the "runtime type" has to be "mixed" or some other broad type: e.g. "function foo(): T", where T is a type parameter on a generic class.

For the first two, you can just suffix the extra information rather than repeating yourself, so more like this:

class Foo~<T> extends Bar~<int,T> {
public function foo(string~non-empty $in): array~<T> {

Other than properties, annotating with "mixed" is redundant anyway, so you could have this

public function bar(~T): ~T {

But if you wanted to enforce the lower bound, you'd have to manually include it:

public function bar(int~T): int~T {

It's obviously not as elegant as making every type string reserved natively, but it allows for much faster iteration in SA tools, and could replace all their use of docblocks over night.

As and when the language added full runtime support for those types, users could just delete the ~ (or whatever delimiter we used) and opt in to enforcement. "class Foo~<T>" would be an erased generic, "class Foo<T>" would be a reified or monomorphized one.

Regards,

Rowan Tommins
[IMSoP]

The only governance body that the ecosystem actually treats as
authoritative is internals. That's the structural fact behind this
RFC: not just "syntax in PHP is intrinsically better than syntax in
docblocks" (which is true), but "the standardisation step that would
make docblock generics consistent across tools requires authority no
party in the ecosystem currently has."

I think this is a part I'm fuzzy on: which of the inconsistencies that currently exist are actually solved by the parts of this RFC which are enforced? Will users still get different results in different tools for the parts that are not enforced natively, or is PHP Internals going to become a standards body defining conformance tests for those parts?

The visual-distinction argument cuts both ways too. You're arguing
that ~~ makes the SA-checked layer visible to the reader. But the
same argument applies to <...>: anything in angle brackets is the
generic type layer, anything outside is the runtime-checked layer.

I think you missed the point of the suggestion, which was to allow all unchecked type information to be included in the same place. Every single docblock annotation for guiding SA tools would be moved next to the "real" type it was qualifying.

The base shape of the syntax would be standardized by PHP, but the semantics would be open to innovation and (dis)agreement by tool authors.

It's also not true that <> is always present to make the distinction with generics; where the type parameter is used, it just looks like a real type:

public function hasEdge(TNode $from, TNode $to): bool

The actual checked type there is invisible - the "bound erasure" means that it might be just "mixed", but might be some base interface.

Rowan Tommins
[IMSoP]

On 25 May 2026 20:26:41 BST, Matthew Brown matthewmatthew@gmail.com
wrote:

https://thephp.foundation/blog/2025/08/05/compile-generics/ is

That blog post is a year old, and the top comment on the attached Reddit
thread captures my view on it:

The problem with such an approach is that it locks generics to be
reified.

I think the two proposals have a lot more overlap than their framing
suggests. Both block us from having completely erased generics, because
they include some reification/monomorphization, but nothing in
Gina/Larry's blog post would actually block Seifeddine's proposal as
far as I can see.

Specifically, if you take everything Seifeddine has implemented, but 1)
restrict generic declarations to only interfaces and abstract classes;
and 2) remove the "turbofish" syntax completely; then you end up
basically with what the blog post suggests.

The main difference of opinion is what to do with those "missing" parts:

• Larry & Gina proposed just leaving then forbidden until we decide how
  to implement them
• Seifeddine proposed locking in the syntax with some partial checking,
  but mostly just reflection support

I would agree. Seif's proposal is effectively a superset of what Gina was
working on, and should it pass, it would include all of the functionality
of Gina's proposal and then some.

--Larry Garfield

Yes it's a superset of the syntax, and leaves the door open to some runtime
checks being added in the future, per you & Gina's proposal.