Open array and list shape support

Group: Arrays and shapes · Category: phpdoc · File: arrays_open_shapes.php

References: - Psalm unsealed array and list shapes - python-typing tuple-style prefix compatibility inspiration

Analyzer results

Analyzer	Version	Result	Diagnostics
phan	6.0.7Phan 6.0.7 php-ast version 1.1.3 PHP version used to run Phan: 8.5.9	Unrecognized	arrays_open_shapes.php:24: Saw possibly unextractable annotation for a fragment of comment '* @param array{name: string, ...} $options // E?: some tools cannot parse open array shape PHPDoc syntax': after array, did not see an element name (will guess based on comment order) [PhanUnextractableAnnotationElementName] arrays_open_shapes.php:24: Saw a token Phan may have failed to parse after '* @param array{name: string, ...} $options // E?: some tools cannot parse open array shape PHPDoc syntax': after array, saw '{' [PhanUnextractableAnnotationSuffix] arrays_open_shapes.php:36: Saw possibly unextractable annotation for a fragment of comment '* @param list{string, int, ...} $values // E?: some tools cannot parse open list shape PHPDoc syntax': after list, did not see an element name (will guess based on comment order) [PhanUnextractableAnnotationElementName] arrays_open_shapes.php:36: Saw a token Phan may have failed to parse after '* @param list{string, int, ...} $values // E?: some tools cannot parse open list shape PHPDoc syntax': after list, saw '{' [PhanUnextractableAnnotationSuffix] Recognition: spelling not resolved — reported on declaration line(s) 24, 36 Enforcement: 0/5 of the expected violations reported — incidental, since the spelling was not resolved
phpstan	2.2.8PHPStan - PHP Static Analysis Tool 2.2.8	Partly enforced (2/5) reported Lv.5+	arrays_open_shapes.php:33: Parameter #1 $options of function Conformance\Tests\ArraysOpenShapes\inspectOpenArrayShape expects array{name: string, ...}, array{extra: 123} given. [identifier=argument.type] [reported-from-level=5] arrays_open_shapes.php:51: Parameter #1 $values of function Conformance\Tests\ArraysOpenShapes\inspectOpenListShape expects array{string, int, ...}, array{1, 'demo', true} given. [identifier=argument.type] [reported-from-level=5] With strict-rules arrays_open_shapes.php:33: Parameter #1 $options of function Conformance\Tests\ArraysOpenShapes\inspectOpenArrayShape expects array{name: string, ...}, array{extra: 123} given. [identifier=argument.type] arrays_open_shapes.php:51: Parameter #1 $values of function Conformance\Tests\ArraysOpenShapes\inspectOpenListShape expects array{string, int, ...}, array{1, 'demo', true} given. [identifier=argument.type] Recognition: spelling resolved Enforcement: 2/5 of the expected violations reported
psalm	6.16.1Psalm 6.16.1@f1f5de594dc76faf8784e02d3dc4716c91c6f6ac next: 7.0.0-beta19	Partly enforced (2/5)	arrays_open_shapes.php:33: Argument 1 of Conformance\Tests\ArraysOpenShapes\inspectOpenArrayShape expects array{name: string, ...<array-key, mixed>}, but array{extra: 123} provided [InvalidArgument] arrays_open_shapes.php:51: Argument 1 of Conformance\Tests\ArraysOpenShapes\inspectOpenListShape expects list{string, int, ...<mixed>}, but list{1, 'demo', true} provided [InvalidArgument] Recognition: spelling resolved Enforcement: 2/5 of the expected violations reported
mago	1.46.0mago 1.46.0	Partly enforced (2/5)	arrays_open_shapes.php:33: Possible argument type mismatch for argument #1 of `Conformance\Tests\ArraysOpenShapes\inspectOpenArrayShape`: expected `array{'name': string, ...}`, but possibly received `array{'extra': int(123)}`. [possibly-invalid-argument] arrays_open_shapes.php:51: Possible argument type mismatch for argument #1 of `Conformance\Tests\ArraysOpenShapes\inspectOpenListShape`: expected `list{string, int, ...<mixed>}`, but possibly received `list{int(1), string('demo'), true}`. [possibly-invalid-argument] Recognition: spelling resolved Enforcement: 2/5 of the expected violations reported
mir	0.70.1mir 0.70.1	Partly enforced (2/5)	arrays_open_shapes.php:33: InvalidArgument: Argument $options of inspectOpenArrayShape() expects 'array{'name': string}', got 'array{'extra': 123}' [MIR0201] arrays_open_shapes.php:51: InvalidArgument: Argument $values of inspectOpenListShape() expects 'array{0: string, 1: int}', got 'array{0: 1, 1: "demo", 2: true}' [MIR0201] Recognition: spelling resolved Enforcement: 2/5 of the expected violations reported
phpantom	0.9.0phpantom_lsp 0.9.0	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/5 of the expected violations reported
intelephense	1.18.5intelephense 1.18.5	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/5 of the expected violations reported
phpy	0.2.0phpy 0.2.0	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/5 of the expected violations reported
qodana	262.8665.325Qodana 262.8665.325	Unrecognized	arrays_open_shapes.php:32: Value should be one of: "name" [PhpArrayKeyDoesNotMatchArrayShapeInspection] arrays_open_shapes.php:33: Incomplete array according to shape declaration. Missing key(s): name [PhpMissingArrayKeyInspection] arrays_open_shapes.php:33: Value should be one of: "name" [PhpArrayKeyDoesNotMatchArrayShapeInspection] arrays_open_shapes.php:36: Argument type does not match the declared [PhpDocSignatureInspection] Recognition: spelling not resolved — reported on declaration line(s) 36 Enforcement: 1/5 of the expected violations reported — incidental, since the spelling was not resolved Expectation diff Line 32: Expected valid value to be accepted, got ["Value should be one of: \"name\" [PhpArrayKeyDoesNotMatchArrayShapeInspection]"]
noverify	0.5.5NoVerify, version 0.5.5: built on: 2025.04.22 14:36:46 OS: r-kuchinskas arm64 Commit: 4774b82f8adc53fbef38f95e97af4b953b4d1529	Unrecognized	arrays_open_shapes.php:26: param $options miss matched with phpdoc type <<array{name: string, ...}>> [funcParamTypeMissMatch] arrays_open_shapes.php:28: potential null array access in parameter value of function Conformance\Tests\ArraysOpenShapes\takesString [notNullSafetyFunctionArgumentArrayDimFetch] arrays_open_shapes.php:38: param $values miss matched with phpdoc type <<list{string, int, ...}>> [funcParamTypeMissMatch] arrays_open_shapes.php:45: potential null array access in parameter value of function Conformance\Tests\ArraysOpenShapes\takesString [notNullSafetyFunctionArgumentArrayDimFetch] arrays_open_shapes.php:46: potential null array access in parameter value of function Conformance\Tests\ArraysOpenShapes\takesInt [notNullSafetyFunctionArgumentArrayDimFetch] Recognition: spelling not resolved — reported on declaration line(s) 26, 38 Enforcement: 3/5 of the expected violations reported — incidental, since the spelling was not resolved
steins	0.1.5steins 0.1.5 (2026-08-12 revision 39b4cc1)	Partly enforced (2/5)	arrays_open_shapes.php:33: argument ['extra' => 123] to inspectOpenArrayShape() violates declared @param array{name: string, ...} $options — declared contract violation [phpdoc.param-mismatch] arrays_open_shapes.php:51: argument [1, 'demo', true] to inspectOpenListShape() violates declared @param list{string, int, ...} $values — declared contract violation [phpdoc.param-mismatch] Recognition: spelling resolved Enforcement: 2/5 of the expected violations reported
phpstan-strict	2.2.8PHPStan - PHP Static Analysis Tool 2.2.8	Partly enforced (2/5)	arrays_open_shapes.php:33: Parameter #1 $options of function Conformance\Tests\ArraysOpenShapes\inspectOpenArrayShape expects array{name: string, ...}, array{extra: 123} given. [identifier=argument.type] arrays_open_shapes.php:51: Parameter #1 $values of function Conformance\Tests\ArraysOpenShapes\inspectOpenListShape expects array{string, int, ...}, array{1, 'demo', true} given. [identifier=argument.type] Recognition: spelling resolved Enforcement: 2/5 of the expected violations reported
psalm-next	7.0.0-beta19Psalm 7.0.0-beta19@7e751c06a756fa64dc4c759c09fe4a173afcb433	Partly enforced (2/5)	arrays_open_shapes.php:33: Argument 1 of Conformance\Tests\ArraysOpenShapes\inspectOpenArrayShape expects array{name: string, ...<array-key, mixed>}, but array{extra: 123} provided [InvalidArgument] arrays_open_shapes.php:51: Argument 1 of Conformance\Tests\ArraysOpenShapes\inspectOpenListShape expects list{string, int, ...<mixed>}, but list{1, 'demo', true} provided [InvalidArgument] Recognition: spelling resolved Enforcement: 2/5 of the expected violations reported

Source

<?php

declare(strict_types=1);

namespace Conformance\Tests\ArraysOpenShapes;

/**
 * Open array and list shape support.
 *
 * References:
 * - Psalm unsealed array and list shapes
 * - python-typing tuple-style prefix compatibility inspiration
 */

function takesString(string $value): void
{
}

function takesInt(int $value): void
{
}

/**
 * @param array{name: string, ...} $options
 */
function inspectOpenArrayShape(array $options): void // T: array{name: string, ...}
{
    takesString($options['name']); // E?: some tools do not preserve open array shape required keys precisely
}

inspectOpenArrayShape(['name' => 'demo']); // V
inspectOpenArrayShape(['name' => 'demo', 'extra' => 123]); // V
inspectOpenArrayShape(['extra' => 123]); // E?: open array shapes should still require declared keys

/**
 * @param list{string, int, ...} $values
 */
function inspectOpenListShape(array $values): void // T: list{string, int, ...}
{
    [$name, $count] = $values;

    takesString($name);
    takesInt($count);

    takesString($values[0]); // E?: some tools do not preserve open list shape indexed access precisely
    takesInt($values[1]); // E?: some tools do not preserve open list shape indexed access precisely
}

inspectOpenListShape(['demo', 1]); // V
inspectOpenListShape(['demo', 1, true]); // V
inspectOpenListShape([1, 'demo', true]); // E?: open list shapes should still enforce the declared prefix element types