[RFC] Typed array declarations

I would like to propose native type declarations for PHP array keys and
values. The RFC draft is available at:

https://wiki.php.net/rfc/typed_array_declarations

Hello,

Thanks for the RFC. I am also a long time silent follower of the list.

I would like to highlight a possible mistake. I copy the text here:

For by-value boundaries, one parameterized array is a subtype of another

when both its key and value types are subtypes:

array<K1, V1> <: array<K2, V2>
when K1 <: K2 and V1 <: V2

There are some problems here:

1. You have limited K to int or string, but none of these types can be
   subtyped. As a result K1<:K2 never applies. We can only have K1:=K2.
2. You also claim that V is covariant. However, this holds true only for
   read-only arrays. Write operations of an array use V in contra-variant
   positions.

I am afraid that we cannot have sound covariant subtyping of an array,
unless we clearly separate the read interface from the write one.

Lazare INEPOLOGLOU
Architecte Logiciel

On Thu, 16 Jul 2026 at 11:27, Wendell Adriel wendelladriel.ti@gmail.com
wrote:

Hi everyone,

I've been off for quite a while from internals, so I'm going to
re-introduce myself briefly.

I'm Wendell Adriel, I've been working with PHP since 2009.
Worked over a decade with PHP enterprise applications, and currently I'm
working as a Senior Software Engineer in the Laravel OSS Team. You can
check more about me on my website (link in my email signature).

I would like to propose native type declarations for PHP array keys and
values. The RFC draft is available at:

https://wiki.php.net/rfc/typed_array_declarations

The proposal adds array<TValue> for integer-keyed arrays and
array<TKey, TValue> when the key type must be declared explicitly. Plain
array declarations remain unchanged.

The RFC proposes three implementation levels that share the same syntax
and Reflection metadata, but they provide different runtime guarantees:

final class ProductCatalog
{
    public array<string, Product> $products = [];
}

$catalog = new ProductCatalog();

$catalog->products = ['featured' => new stdClass()]; // Whole-property
assignment
$catalog->products['featured'] = new stdClass();      // Direct dimension
write

• Level 1 parses the declaration and exposes it through Reflection,
  but does not validate elements. Both writes are accepted.
• Level 2 validates keys and values when an array crosses a declared
  boundary, such as a complete property assignment, argument, return value,
  default, or typed class constant. The first write throws TypeError, but
  the direct dimension write is still accepted.
• Level 3 includes Level 2 and enforces the constraint for later
  property mutations and references. Both writes throw TypeError before the
  invalid value is stored.

I currently recommend Level 3 for typed properties because it preserves
the guarantee the declaration appears to make. There is no implementation
yet, because I first wanted to see which implementation level would be
accepted. I will work on one after incorporating early feedback.

I would appreciate any feedback, especially on the runtime semantics and
the appropriate implementation level.

Thanks in advance!

---
Best Regards,
Wendell Adriel.
Software Engineer & Architect
https://wendelladriel.com https://wendelladriel.com

czw., 16 lip 2026 o 11:25 Wendell Adriel wendelladriel.ti@gmail.com
napisał(a):

Hi everyone,

I've been off for quite a while from internals, so I'm going to
re-introduce myself briefly.

I'm Wendell Adriel, I've been working with PHP since 2009.
Worked over a decade with PHP enterprise applications, and currently I'm
working as a Senior Software Engineer in the Laravel OSS Team. You can
check more about me on my website (link in my email signature).

I would like to propose native type declarations for PHP array keys and
values. The RFC draft is available at:

https://wiki.php.net/rfc/typed_array_declarations

The proposal adds array<TValue> for integer-keyed arrays and
array<TKey, TValue> when the key type must be declared explicitly. Plain
array declarations remain unchanged.

The RFC proposes three implementation levels that share the same syntax
and Reflection metadata, but they provide different runtime guarantees:

final class ProductCatalog
{
    public array<string, Product> $products = [];
}

$catalog = new ProductCatalog();

$catalog->products = ['featured' => new stdClass()]; // Whole-property
assignment
$catalog->products['featured'] = new stdClass();      // Direct dimension
write

• Level 1 parses the declaration and exposes it through Reflection,
  but does not validate elements. Both writes are accepted.
• Level 2 validates keys and values when an array crosses a declared
  boundary, such as a complete property assignment, argument, return value,
  default, or typed class constant. The first write throws TypeError, but
  the direct dimension write is still accepted.
• Level 3 includes Level 2 and enforces the constraint for later
  property mutations and references. Both writes throw TypeError before the
  invalid value is stored.

I currently recommend Level 3 for typed properties because it preserves
the guarantee the declaration appears to make. There is no implementation
yet, because I first wanted to see which implementation level would be
accepted. I will work on one after incorporating early feedback.

I would appreciate any feedback, especially on the runtime semantics and
the appropriate implementation level.

Thanks in advance!

---
Best Regards,
Wendell Adriel.
Software Engineer & Architect
https://wendelladriel.com https://wendelladriel.com

Hi Wendell,

I've been implementing a prototype of persistent list-typed properties
(where list is a structural refinement of array, i.e. array_is_list() must
always hold), and during the implementation I ran into what appears to be a
more general issue that may also affect Level 3 typed arrays.

The interesting part is that this is not specific to list. It seems to be a
consequence of trying to maintain a persistent refinement invariant on
mutable IS_ARRAY values.

A simplified example for typed arrays would be:

class C {
public array<string, int> $data = [];
}

parse_str("a=1&b=2", $c->data);

A typical internal implementation pattern is roughly:

1. initialize the output parameter as an empty array,
2. the empty array satisfies the declared type,
3. populate the HashTable in place,
4. return.

For nominal types this is fine. For structural refinements (such as list)
or future element-constrained arrays (array<string, int>, array<int, Foo>,
etc.), the invariant can be violated after the initial type check has
already succeeded.

What my prototype uncovered is that there are really two distinct classes
of operations:

Incremental mutations (DIM writes, append, unset, sort variants, etc.),
where the invariant can often be preserved with operation-specific checks.
Opaque out-parameter builders, where an empty array is first assigned and
then populated internally without further type validation.

The second category appears much harder to support in a general way.

This raises a broader architectural question:

Should Level 3 typed arrays rely on function-specific guards for these
APIs, or should internal APIs gradually move towards a model where the
result is built in a temporary zval and only assigned through a single
typed assignment after construction?

That approach would naturally preserve atomicity and would work not only
for list, but also for future typed arrays.

I'm not claiming this makes Level 3 impossible. Quite the opposite - I
think it highlights an implementation issue that any persistent refinement
over mutable arrays will eventually have to solve, regardless of whether
the refinement is list, array<T>, or something else.

I'd be interested to hear whether this has already been considered during
the design of Level 3, or whether this class of internal APIs simply hasn't
been explored yet.

Kind regards,
Michał Marcin Brzuchalski