Generic iterable syntax in PHPDoc

Group: PHPDoc basics · Category: phpdoc · File: phpdoc_basics_iterable_generic_syntax.php

References: - PHPStan iterable types - Psalm iterable types

Analyzer results

Analyzer	Version	Result	Diagnostics
phan	6.0.10Phan 6.0.10 php-ast version 1.1.3 PHP version used to run Phan: 8.5.11	Enforced	phpdoc_basics_iterable_generic_syntax.php:32: Argument 1 ($values) is [1] of type array{0:1} but \Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesStringIterable() takes iterable<string> defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_basics_iterable_generic_syntax.php:18 [PhanTypeMismatchArgument] phpdoc_basics_iterable_generic_syntax.php:33: Argument 1 ($values) is ['one'=>'one'] of type array{one:'one'} but \Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesIntegerStringIterable() takes iterable<int,string> defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_basics_iterable_generic_syntax.php:25 [PhanTypeMismatchArgument] Recognition: spelling resolved Enforcement: 2/2 of the expected violations reported
phpstan	2.3.1PHPStan - PHP Static Analysis Tool 2.3.1	Enforced reported Lv.5+	phpdoc_basics_iterable_generic_syntax.php:32: Parameter #1 $values of function Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesStringIterable expects iterable<string>, array<int, int> given. [reported-from-level=5] phpdoc_basics_iterable_generic_syntax.php:33: Parameter #1 $values of function Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesIntegerStringIterable expects iterable<int, string>, array<string, string> given. [reported-from-level=5] With strict-rules phpdoc_basics_iterable_generic_syntax.php:32: Parameter #1 $values of function Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesStringIterable expects iterable<string>, array<int, int> given. phpdoc_basics_iterable_generic_syntax.php:33: Parameter #1 $values of function Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesIntegerStringIterable expects iterable<int, string>, array<string, string> given. Recognition: spelling resolved Enforcement: 2/2 of the expected violations reported
psalm	6.20.0Psalm 6.20.0@804f03c0c183d149fcd4b8c7c0c9b3fbf836d34c next: 7.0.0-rc2	Enforced	phpdoc_basics_iterable_generic_syntax.php:32: Argument 1 of Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesStringIterable expects iterable<mixed, string>, but list{1} provided [InvalidArgument] phpdoc_basics_iterable_generic_syntax.php:33: Argument 1 of Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesIntegerStringIterable expects iterable<int, string>, but array{one: 'one'} provided [InvalidArgument] Recognition: spelling resolved Enforcement: 2/2 of the expected violations reported
mago	1.57.0mago 1.57.0	Enforced	phpdoc_basics_iterable_generic_syntax.php:32: Possible argument type mismatch for argument #1 of `Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesStringIterable`: expected `iterable<mixed, string>`, but possibly received `list{int(1)}`. [possibly-invalid-argument] phpdoc_basics_iterable_generic_syntax.php:33: Possible argument type mismatch for argument #1 of `Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesIntegerStringIterable`: expected `iterable<int, string>`, but possibly received `array{'one': string('one')}`. [possibly-invalid-argument] Recognition: spelling resolved Enforcement: 2/2 of the expected violations reported
mir	0.87.0mir 0.87.0	Partly enforced (1/2)	phpdoc_basics_iterable_generic_syntax.php:32: InvalidArgument: Argument $values of takesStringIterable() expects 'iterable<int\|string, string>', got 'array{0: 1}' [MIR0201] Recognition: spelling resolved Enforcement: 1/2 of the expected violations reported
phpantom	0.11.1phpantom_lsp 0.11.1	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/2 of the expected violations reported
intelephense	1.18.5intelephense 1.18.5	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/2 of the expected violations reported
phpactor	2026.10.07.0Phpactor 2026.10.07.0	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/2 of the expected violations reported
phpy	1.0.19409phpy 1.0.19409	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/2 of the expected violations reported
qodana	262.10968.76PhpStorm 262.10968.76	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/2 of the expected violations reported Notes: PhpStorm reads `iterable<string>` as `string[]` — an array, not an iterable — and then checks arrayness only: `[1]` passes, and declared through PHPDoc alone the parameter rejects an `ArrayIterator`, which the type admits. That is a different reading, not a widening.
noverify	0.5.5NoVerify, version 0.5.5: built on: 2025.04.22 14:36:46 OS: r-kuchinskas arm64 Commit: 4774b82f8adc53fbef38f95e97af4b953b4d1529	Unrecognized	phpdoc_basics_iterable_generic_syntax.php:18: param $values miss matched with phpdoc type <<iterable<string>>> [funcParamTypeMissMatch] phpdoc_basics_iterable_generic_syntax.php:25: param $values miss matched with phpdoc type <<iterable<int, string>>> [funcParamTypeMissMatch] Recognition: spelling not resolved — reported on declaration line(s) 18, 25 Enforcement: 0/2 of the expected violations reported — incidental, since the spelling was not resolved
steins	0.1.8steins 0.1.8 (2026-09-21 revision 76306a9)	Not enforced	No diagnostics reported. Recognition: spelling resolved Enforcement: 0/2 of the expected violations reported
phpstan-strict	2.3.1PHPStan - PHP Static Analysis Tool 2.3.1	Enforced	phpdoc_basics_iterable_generic_syntax.php:32: Parameter #1 $values of function Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesStringIterable expects iterable<string>, array<int, int> given. phpdoc_basics_iterable_generic_syntax.php:33: Parameter #1 $values of function Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesIntegerStringIterable expects iterable<int, string>, array<string, string> given. Recognition: spelling resolved Enforcement: 2/2 of the expected violations reported
psalm-next	7.0.0-rc2Psalm 7.0.0-rc2@20339e3fe5b8d03bcd8061030eb2a83ad50e5783	Enforced	phpdoc_basics_iterable_generic_syntax.php:32: Argument 1 of Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesStringIterable expects iterable<mixed, string>, but list{1} provided [InvalidArgument] phpdoc_basics_iterable_generic_syntax.php:33: Argument 1 of Conformance\Tests\PhpdocBasicsIterableGenericSyntax\takesIntegerStringIterable expects iterable<int, string>, but array{one: 'one'} provided [InvalidArgument] Recognition: spelling resolved Enforcement: 2/2 of the expected violations reported

Source

<?php

declare(strict_types=1);

namespace Conformance\Tests\PhpdocBasicsIterableGenericSyntax;

/**
 * Generic iterable syntax in PHPDoc.
 *
 * References:
 * - PHPStan iterable types
 * - Psalm iterable types
 */

/**
 * @param iterable<string> $values
 */
function takesStringIterable(iterable $values): void // T: iterable<string>
{
}

/**
 * @param iterable<int, string> $values
 */
function takesIntegerStringIterable(iterable $values): void // T: iterable<int, string>
{
}

takesStringIterable(['one', 'two']); // V
takesIntegerStringIterable([1 => 'one', 2 => 'two']); // V

takesStringIterable([1]); // E?: an iterable of integers is not an iterable of strings
takesIntegerStringIterable(['one' => 'one']); // E?: the iterable key type is int