← All results

key-of<T> over a template parameter

Group: Advanced PHPDoc types · Category: ecosystem · File: phpdoc_advanced_fallback_key_of_template.php

The operand is neither a shape nor a constant but a template parameter: a generic function takes T of array and returns one of its keys. Evaluating the return type now happens at the *call site*, after T has been inferred from the argument — two features composed, and the composition is what the probes separate. A tool can evaluate key-of over a written-out shape and still return array-key here, and a tool that infers T but widens the argument's keys to string loses the literal union the caller relied on. References: - PHPStan phpdoc-types: key-of over template parameters - Psalm utility_types.md: key-of with templates

Analyzer results

AnalyzerVersionResultDiagnostics
phan 6.0.7Phan 6.0.7 php-ast version 1.1.3 PHP version used to run Phan: 8.5.9 Enforced 
phpdoc_advanced_fallback_key_of_template.php:63: Argument 1 ($value) is firstKey(['debug'=>false,'verbose'=>true]) of type string|string but \Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\acceptsInt() takes int defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_advanced_fallback_key_of_template.php:44 [PhanTypeMismatchArgument]
  • Recognition: spelling resolved
  • Enforcement: 1/1 of the expected violations reported
phpstan 2.2.8PHPStan - PHP Static Analysis Tool 2.2.8 Enforced reported Lv.5+ 
phpdoc_advanced_fallback_key_of_template.php:63: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\acceptsInt expects int, string given. [identifier=argument.type] [reported-from-level=5]
With strict-rules
phpdoc_advanced_fallback_key_of_template.php:63: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\acceptsInt expects int, string given. [identifier=argument.type]
  • Recognition: spelling resolved
  • Enforcement: 1/1 of the expected violations reported
psalm 6.16.1Psalm 6.16.1@f1f5de594dc76faf8784e02d3dc4716c91c6f6ac
next: 7.0.0-beta19		 Unrecognized (pzoom≠) 
phpdoc_advanced_fallback_key_of_template.php:26: The declared return type 'key-of<T:fn-conformance\tests\phpdocadvancedfallbackkeyoftemplate\firstkey as array<array-key, mixed>>' for Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\firstKey is incorrect, got 'array-key' [InvalidReturnType]
phpdoc_advanced_fallback_key_of_template.php:34: The inferred type 'array-key' does not match the declared return type 'key-of<T:fn-conformance\tests\phpdocadvancedfallbackkeyoftemplate\firstkey as array<array-key, mixed>>' for Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\firstKey [InvalidReturnStatement]
phpdoc_advanced_fallback_key_of_template.php:63: Argument 1 of Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\acceptsInt expects int, but 'debug'|'verbose' provided [InvalidScalarArgument]
pzoom (Psalm port)
phpdoc_advanced_fallback_key_of_template.php:34: The type array-key does not match the declared return type key-of<T> [InvalidReturnStatement]
phpdoc_advanced_fallback_key_of_template.php:63: Argument 1 of acceptsInt expects int, but 'debug'|'verbose' provided [InvalidArgument]
  • Recognition: spelling not resolved — reported on declaration line(s) 26
  • Enforcement: 1/1 of the expected violations reported — incidental, since the spelling was not resolved
Expectation diff
Line 34: Expected valid value to be accepted, got ["The inferred type 'array-key' does not match the declared return type 'key-of<T:fn-conformance\\tests\\phpdocadvancedfallbackkeyoftemplate\\firstkey as array<array-key, mixed>>' for Conformance\\Tests\\PhpdocAdvancedFallbackKeyOfTemplate\\firstKey [InvalidReturnStatement]"]
mago 1.46.0mago 1.46.0 Enforced 
phpdoc_advanced_fallback_key_of_template.php:63: Invalid argument type for argument #1 of `Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\acceptsInt`: expected `int`, but found `string('debug')|string('verbose')`. [invalid-argument]
  • Recognition: spelling resolved
  • Enforcement: 1/1 of the expected violations reported
mir 0.70.1mir 0.70.1 Not enforced

No diagnostics reported.

  • Recognition: spelling resolved
  • Enforcement: 0/1 of the expected violations reported
phpantom 0.9.0phpantom_lsp 0.9.0 Incidental (1/1) 
phpdoc_advanced_fallback_key_of_template.php:34: Return type array-key is incompatible with declared return type key-of<T> [type_mismatch_return]
phpdoc_advanced_fallback_key_of_template.php:56: Argument 1 ($value) expects string, got key-of<array> [type_mismatch_argument]
phpdoc_advanced_fallback_key_of_template.php:60: Argument 1 ($flag) expects 'debug'|'verbose', got key-of<array> [type_mismatch_argument]
phpdoc_advanced_fallback_key_of_template.php:63: Argument 1 ($value) expects int, got key-of<array> [type_mismatch_argument]
  • Recognition: spelling resolved
  • Enforcement: 1/1 of the expected violations reported — incidental, since values the type admits were also rejected on line(s) 34, 56, 60
Expectation diff
Line 34: Expected valid value to be accepted, got ["Return type array-key is incompatible with declared return type key-of<T> [type_mismatch_return]"]
Line 56: Expected valid value to be accepted, got ["Argument 1 ($value) expects string, got key-of<array> [type_mismatch_argument]"]
Line 60: Expected valid value to be accepted, got ["Argument 1 ($flag) expects 'debug'|'verbose', got key-of<array> [type_mismatch_argument]"]
intelephense 1.18.5intelephense 1.18.5 Enforced 
phpdoc_advanced_fallback_key_of_template.php:63: Expected type 'int'. Found ''debug'|'verbose''. [P1006]
  • Recognition: spelling resolved
  • Enforcement: 1/1 of the expected violations reported
phpy 0.2.0phpy 0.2.0 Not enforced

No diagnostics reported.

  • Recognition: spelling resolved
  • Enforcement: 0/1 of the expected violations reported
qodana 262.8665.325Qodana 262.8665.325 Not enforced

No diagnostics reported.

  • Recognition: spelling resolved
  • Enforcement: 0/1 of the expected violations reported
noverify 0.5.5NoVerify, version 0.5.5: built on: 2025.04.22 14:36:46 OS: r-kuchinskas arm64 Commit: 4774b82f8adc53fbef38f95e97af4b953b4d1529 Unrecognized ⚠ 1 false positive 
phpdoc_advanced_fallback_key_of_template.php:28: param $items miss matched with phpdoc type <<T>> [funcParamTypeMissMatch]
phpdoc_advanced_fallback_key_of_template.php:51: param $flag miss matched with phpdoc type <<'debug'|'verbose'>> [funcParamTypeMissMatch]
  • Recognition: spelling not resolved — reported on declaration line(s) 28
  • Enforcement: 0/1 of the expected violations reported — incidental, since the spelling was not resolved
  • False positives: line(s) 51
Expectation diff
Line 51: Unexpected errors ["param $flag miss matched with phpdoc type <<'debug'|'verbose'>> [funcParamTypeMissMatch]"]
steins 0.1.5steins 0.1.5 (2026-08-12 revision 39b4cc1) Widened to mixed

No diagnostics reported.

  • Recognition: spelling resolved
  • Enforcement: 0/1 of the expected violations reported

Notes: key-of<T> projects over the lowered operand (project_key_of, steins-contract/src/lib.rs); a @template T type variable lowers to ContractTy::Class("t"), which isn't a Shape/ListOf/MapOf/ArrayAny, so the projection's catch-all floors to Opaque — the key type is never narrowed from a template parameter.

phpstan-strict 2.2.8PHPStan - PHP Static Analysis Tool 2.2.8 Enforced 
phpdoc_advanced_fallback_key_of_template.php:63: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\acceptsInt expects int, string given. [identifier=argument.type]
  • Recognition: spelling resolved
  • Enforcement: 1/1 of the expected violations reported
psalm-next 7.0.0-beta19Psalm 7.0.0-beta19@7e751c06a756fa64dc4c759c09fe4a173afcb433 Unrecognized 
phpdoc_advanced_fallback_key_of_template.php:26: The declared return type 'key-of<T:fn-conformance\tests\phpdocadvancedfallbackkeyoftemplate\firstkey as array<array-key, mixed>>' for Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\firstKey is incorrect, got 'array-key' [InvalidReturnType]
phpdoc_advanced_fallback_key_of_template.php:34: The inferred type 'array-key' does not match the declared return type 'key-of<T:fn-conformance\tests\phpdocadvancedfallbackkeyoftemplate\firstkey as array<array-key, mixed>>' for Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\firstKey [InvalidReturnStatement]
phpdoc_advanced_fallback_key_of_template.php:63: Argument 1 of Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate\acceptsInt expects int, but 'debug'|'verbose' provided [InvalidScalarArgument]
  • Recognition: spelling not resolved — reported on declaration line(s) 26
  • Enforcement: 1/1 of the expected violations reported — incidental, since the spelling was not resolved
Expectation diff
Line 34: Expected valid value to be accepted, got ["The inferred type 'array-key' does not match the declared return type 'key-of<T:fn-conformance\\tests\\phpdocadvancedfallbackkeyoftemplate\\firstkey as array<array-key, mixed>>' for Conformance\\Tests\\PhpdocAdvancedFallbackKeyOfTemplate\\firstKey [InvalidReturnStatement]"]

Source

<?php

declare(strict_types=1);

namespace Conformance\Tests\PhpdocAdvancedFallbackKeyOfTemplate;

/**
 * `key-of<T>` over a template parameter
 *
 * The operand is neither a shape nor a constant but a template parameter: a
 * generic function takes `T of array` and returns one of its keys. Evaluating
 * the return type now happens at the *call site*, after T has been inferred
 * from the argument — two features composed, and the composition is what the
 * probes separate. A tool can evaluate `key-of` over a written-out shape and
 * still return `array-key` here, and a tool that infers T but widens the
 * argument's keys to `string` loses the literal union the caller relied on.
 *
 * References:
 * - PHPStan phpdoc-types: key-of over template parameters
 * - Psalm utility_types.md: key-of with templates
 */

/**
 * @template T of array<array-key, mixed>
 * @param T $items
 * @return key-of<T>
 */
function firstKey(array $items) // T: key-of<T>
{
    foreach ($items as $key => $_) {
        // A tool can evaluate the projection at call sites and still be unable
        // to prove this body produces key-of<T>; that limitation surfaces as a
        // false positive here, not as an expectation of the test.
        return $key; // V
    }

    throw new \InvalidArgumentException('empty array');
}

function acceptsString(string $value): void
{
}

function acceptsInt(int $value): void
{
}

/**
 * @param 'debug'|'verbose' $flag
 */
function acceptsFlagName(string $flag): void
{
}

// With string keys, the returned key is a string.
acceptsString(firstKey(['debug' => false, 'verbose' => true])); // V

// More precisely, it is the union of this argument's keys: a tool that infers
// T but widens the keys to `string` reports a false positive right here.
acceptsFlagName(firstKey(['debug' => false, 'verbose' => true])); // V

// A key of this argument is never an int.
acceptsInt(firstKey(['debug' => false, 'verbose' => true])); // E?: the keys of this argument are strings