`value-of<T>` over a template parameter bound to a backed enum

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

The generic spelling of ->value: the function takes T of Suit and declares value-of<T> as its return, so the backing-scalar projection is evaluated from whatever case type T is inferred as. Passing a single known case is the precision probe — an exact tool returns 'hearts' for Suit::Hearts, one that stops at the bound returns every backing value, and one that never evaluates the projection returns mixed and satisfies the int probe in silence. References: - PHPStan phpdoc-types: value-of<BackedEnum> over templates - Psalm utility_types.md: value-of on backed enums

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	Incidental (1/1)	phpdoc_advanced_fallback_value_of_template_enum.php:34: Template type T not used in return value of function/method backingValue() [PhanTemplateTypeNotUsedInFunctionReturn] phpdoc_advanced_fallback_value_of_template_enum.php:58: Argument 1 ($value) is backingValue(Suit::Hearts) of type value-of<T> but \Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsString() takes string defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_advanced_fallback_value_of_template_enum.php:42 [PhanTypeMismatchArgument] phpdoc_advanced_fallback_value_of_template_enum.php:62: Argument 1 ($value) is backingValue(Suit::Hearts) of type value-of<T> but \Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsHearts() takes string defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_advanced_fallback_value_of_template_enum.php:53 [PhanTypeMismatchArgument] phpdoc_advanced_fallback_value_of_template_enum.php:65: Argument 1 ($value) is backingValue(Suit::Spades) of type value-of<T> but \Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsInt() takes int defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_advanced_fallback_value_of_template_enum.php:46 [PhanTypeMismatchArgument] Recognition: spelling resolved Enforcement: 1/1 of the expected violations reported — incidental, since values the type admits were also rejected on line(s) 58, 62 Expectation diff Line 58: Expected valid value to be accepted, got ["Argument 1 ($value) is backingValue(Suit::Hearts) of type value-of<T> but \\Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\acceptsString() takes string defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_advanced_fallback_value_of_template_enum.php:42 [PhanTypeMismatchArgument]"] Line 62: Expected valid value to be accepted, got ["Argument 1 ($value) is backingValue(Suit::Hearts) of type value-of<T> but \\Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\acceptsHearts() takes string defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_advanced_fallback_value_of_template_enum.php:53 [PhanTypeMismatchArgument]"]
phpstan	2.2.8PHPStan - PHP Static Analysis Tool 2.2.8	Enforced reported Lv.5+	phpdoc_advanced_fallback_value_of_template_enum.php:65: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsInt expects int, string given. [identifier=argument.type] [reported-from-level=5] With strict-rules phpdoc_advanced_fallback_value_of_template_enum.php:65: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\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_value_of_template_enum.php:32: The declared return type 'value-of<T:fn-conformance\tests\phpdocadvancedfallbackvalueoftemplateenum\backingvalue as Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit>' for Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\backingValue is incorrect, got ''hearts'\|'spades'' [InvalidReturnType] phpdoc_advanced_fallback_value_of_template_enum.php:39: The inferred type ''hearts'\|'spades'' does not match the declared return type 'value-of<T:fn-conformance\tests\phpdocadvancedfallbackvalueoftemplateenum\backingvalue as Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit>' for Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\backingValue [InvalidReturnStatement] phpdoc_advanced_fallback_value_of_template_enum.php:65: Argument 1 of Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsInt expects int, but 'spades' provided [InvalidScalarArgument] pzoom (Psalm port) phpdoc_advanced_fallback_value_of_template_enum.php:39: The type 'hearts'\|'spades' does not match the declared return type value-of<T> [InvalidReturnStatement] phpdoc_advanced_fallback_value_of_template_enum.php:58: Argument 1 of acceptsString cannot be mixed, expecting string [MixedArgument] phpdoc_advanced_fallback_value_of_template_enum.php:62: Argument 1 of acceptsHearts cannot be mixed, expecting 'hearts' [MixedArgument] phpdoc_advanced_fallback_value_of_template_enum.php:65: Argument 1 of acceptsInt cannot be mixed, expecting int [MixedArgument] Recognition: spelling not resolved — reported on declaration line(s) 32 Enforcement: 1/1 of the expected violations reported — incidental, since the spelling was not resolved Expectation diff Line 39: Expected valid value to be accepted, got ["The inferred type ''hearts'\|'spades'' does not match the declared return type 'value-of<T:fn-conformance\\tests\\phpdocadvancedfallbackvalueoftemplateenum\\backingvalue as Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\Suit>' for Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\backingValue [InvalidReturnStatement]"]
mago	1.46.0mago 1.46.0	Enforced	phpdoc_advanced_fallback_value_of_template_enum.php:65: Invalid argument type for argument #1 of `Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsInt`: expected `int`, but found `string('spades')`. [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_value_of_template_enum.php:39: Return type string is incompatible with declared return type value-of<T> [type_mismatch_return] phpdoc_advanced_fallback_value_of_template_enum.php:58: Argument 1 ($value) expects string, got value-of<Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit> [type_mismatch_argument] phpdoc_advanced_fallback_value_of_template_enum.php:62: Argument 1 ($value) expects 'hearts', got value-of<Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit> [type_mismatch_argument] phpdoc_advanced_fallback_value_of_template_enum.php:65: Argument 1 ($value) expects int, got value-of<Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit> [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) 39, 58, 62 Expectation diff Line 39: Expected valid value to be accepted, got ["Return type string is incompatible with declared return type value-of<T> [type_mismatch_return]"] Line 58: Expected valid value to be accepted, got ["Argument 1 ($value) expects string, got value-of<Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\Suit> [type_mismatch_argument]"] Line 62: Expected valid value to be accepted, got ["Argument 1 ($value) expects 'hearts', got value-of<Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\Suit> [type_mismatch_argument]"]
intelephense	1.18.5intelephense 1.18.5	Enforced	phpdoc_advanced_fallback_value_of_template_enum.php:65: Expected type 'int'. Found ''hearts'\|'spades''. [P1006] Recognition: spelling resolved Enforcement: 1/1 of the expected violations reported
phpy	0.2.0phpy 0.2.0	Enforced	phpdoc_advanced_fallback_value_of_template_enum.php:65: Argument '1' passed to Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsInt() is expected to be of type int, string given Recognition: spelling resolved Enforcement: 1/1 of the expected violations reported
qodana	262.8665.325Qodana 262.8665.325	Enforced	phpdoc_advanced_fallback_value_of_template_enum.php:65: Parameter 'backingValue(Suit::Spades)' type is not compatible with declaration when using strict type matching [PhpParamsInspection] phpdoc_advanced_fallback_value_of_template_enum.php:65: Parameter 'backingValue(Suit::Spades)' type is not compatible with declaration [PhpStrictTypeCheckingInspection] Recognition: spelling resolved Enforcement: 1/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_value_of_template_enum.php:34: Class or interface named \Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit does not exist [undefinedClass] phpdoc_advanced_fallback_value_of_template_enum.php:34: param $case miss matched with phpdoc type <<T>> [funcParamTypeMissMatch] phpdoc_advanced_fallback_value_of_template_enum.php:39: Property {\Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit\|\Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\T}->value does not exist [undefinedProperty] phpdoc_advanced_fallback_value_of_template_enum.php:53: param $value miss matched with phpdoc type <<'hearts'>> [funcParamTypeMissMatch] phpdoc_advanced_fallback_value_of_template_enum.php:58: Class constant \Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit::Hearts does not exist [undefinedConstant] phpdoc_advanced_fallback_value_of_template_enum.php:62: Class constant \Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit::Hearts does not exist [undefinedConstant] phpdoc_advanced_fallback_value_of_template_enum.php:65: Class constant \Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit::Spades does not exist [undefinedConstant] Recognition: spelling not resolved — reported on declaration line(s) 34 Enforcement: 1/1 of the expected violations reported — incidental, since the spelling was not resolved False positives: line(s) 53 Expectation diff Line 39: Expected valid value to be accepted, got ["Property {\\Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\Suit\|\\Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\T}->value does not exist [undefinedProperty]"] Line 58: Expected valid value to be accepted, got ["Class constant \\Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\Suit::Hearts does not exist [undefinedConstant]"] Line 62: Expected valid value to be accepted, got ["Class constant \\Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\Suit::Hearts does not exist [undefinedConstant]"] Line 53: Unexpected errors ["param $value miss matched with phpdoc type <<'hearts'>> [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: Same mechanism as value-of<T> on a plain template: @template T of Suit still lowers T to ContractTy::Class("t") (the enum bound is not consulted), so project_value_of floors to Opaque and the backing-value type is never narrowed.
phpstan-strict	2.2.8PHPStan - PHP Static Analysis Tool 2.2.8	Enforced	phpdoc_advanced_fallback_value_of_template_enum.php:65: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\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_value_of_template_enum.php:32: The declared return type 'value-of<T:fn-conformance\tests\phpdocadvancedfallbackvalueoftemplateenum\backingvalue as Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit>' for Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\backingValue is incorrect, got ''hearts'\|'spades'' [InvalidReturnType] phpdoc_advanced_fallback_value_of_template_enum.php:39: The inferred type ''hearts'\|'spades'' does not match the declared return type 'value-of<T:fn-conformance\tests\phpdocadvancedfallbackvalueoftemplateenum\backingvalue as Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\Suit>' for Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\backingValue [InvalidReturnStatement] phpdoc_advanced_fallback_value_of_template_enum.php:65: Argument 1 of Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum\acceptsInt expects int, but 'spades' provided [InvalidScalarArgument] Recognition: spelling not resolved — reported on declaration line(s) 32 Enforcement: 1/1 of the expected violations reported — incidental, since the spelling was not resolved Expectation diff Line 39: Expected valid value to be accepted, got ["The inferred type ''hearts'\|'spades'' does not match the declared return type 'value-of<T:fn-conformance\\tests\\phpdocadvancedfallbackvalueoftemplateenum\\backingvalue as Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\Suit>' for Conformance\\Tests\\PhpdocAdvancedFallbackValueOfTemplateEnum\\backingValue [InvalidReturnStatement]"]

Source

<?php

declare(strict_types=1);

namespace Conformance\Tests\PhpdocAdvancedFallbackValueOfTemplateEnum;

/**
 * `value-of<T>` over a template parameter bound to a backed enum
 *
 * The generic spelling of `->value`: the function takes `T of Suit` and
 * declares `value-of<T>` as its return, so the backing-scalar projection is
 * evaluated from whatever case type T is inferred as. Passing a single known
 * case is the precision probe — an exact tool returns `'hearts'` for
 * `Suit::Hearts`, one that stops at the bound returns every backing value,
 * and one that never evaluates the projection returns `mixed` and satisfies
 * the int probe in silence.
 *
 * References:
 * - PHPStan phpdoc-types: value-of<BackedEnum> over templates
 * - Psalm utility_types.md: value-of on backed enums
 */

enum Suit: string
{
    case Hearts = 'hearts';
    case Spades = 'spades';
}

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

function acceptsString(string $value): void
{
}

function acceptsInt(int $value): void
{
}

/**
 * @param 'hearts' $value
 */
function acceptsHearts(string $value): void
{
}

// The backing value of any Suit case is a string.
acceptsString(backingValue(Suit::Hearts)); // V

// With T inferred as the single case, the projection is that case's literal
// backing value: a tool that only reaches the bound reports a false positive.
acceptsHearts(backingValue(Suit::Hearts)); // V

// The backing values of Suit are strings, never ints.
acceptsInt(backingValue(Suit::Spades)); // E?: Suit backs its cases with strings, not ints

value-of<T> over a template parameter bound to a backed enum

Analyzer results

Source

`value-of<T>` over a template parameter bound to a backed enum