← All results

Conditional return type combined with a template parameter

Group: Conditional types · Category: ecosystem · File: conditionals_template_return.php

When $id is an int, the return is a single Item; when $id is a list of ints, the return is a list of Item. Analyzers that expand the conditional after template inference reject a list return used as a single Item. References: - PHPStan phpdoc-types: Conditional return types + generics - Psalm conditional_types.md

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 Pass 
conditionals_template_return.php:31: Saw unextractable annotation for comment '* @return (T is int ? Item : list<Item>) // E<phan>: Phan cannot extract template-conditional return annotations' [PhanUnextractableAnnotation]
conditionals_template_return.php:33: Template type T not used in return value of function/method fetch() [PhanTemplateTypeNotUsedInFunctionReturn]
phpstan 2.2.8PHPStan - PHP Static Analysis Tool 2.2.8 Pass reported Lv.5+ 
conditionals_template_return.php:52: Parameter #1 $item of function Conformance\Tests\ConditionalsTemplateReturn\takesItem expects Conformance\Tests\ConditionalsTemplateReturn\Item, list<Conformance\Tests\ConditionalsTemplateReturn\Item> given. [identifier=argument.type] [reported-from-level=5]
With strict-rules
conditionals_template_return.php:52: Parameter #1 $item of function Conformance\Tests\ConditionalsTemplateReturn\takesItem expects Conformance\Tests\ConditionalsTemplateReturn\Item, list<Conformance\Tests\ConditionalsTemplateReturn\Item> given. [identifier=argument.type]
psalm 6.16.1Psalm 6.16.1@f1f5de594dc76faf8784e02d3dc4716c91c6f6ac
next: 7.0.0-beta19		 Pass 
conditionals_template_return.php:52: Argument 1 of Conformance\Tests\ConditionalsTemplateReturn\takesItem expects Conformance\Tests\ConditionalsTemplateReturn\Item, but list<Conformance\Tests\ConditionalsTemplateReturn\Item> provided [InvalidArgument]
mago 1.46.0mago 1.46.0 Pass 
conditionals_template_return.php:52: Invalid argument type for argument #1 of `Conformance\Tests\ConditionalsTemplateReturn\takesItem`: expected `Conformance\Tests\ConditionalsTemplateReturn\Item`, but found `list<Conformance\Tests\ConditionalsTemplateReturn\Item>`. [invalid-argument]
mir 0.70.1mir 0.70.1 Pass 
conditionals_template_return.php:52: InvalidArgument: Argument $item of takesItem() expects 'Conformance\Tests\ConditionalsTemplateReturn\Item', got 'list<Conformance\Tests\ConditionalsTemplateReturn\Item>' [MIR0201]
phpantom 0.9.0phpantom_lsp 0.9.0 Pass 
conditionals_template_return.php:52: Argument 1 ($item) expects Conformance\Tests\ConditionalsTemplateReturn\Item, got list<Conformance\Tests\ConditionalsTemplateReturn\Item> [type_mismatch_argument]
intelephense 1.18.5intelephense 1.18.5 Pass 
conditionals_template_return.php:52: Expected type 'Conformance\Tests\ConditionalsTemplateReturn\Item'. Found 'array<int, Conformance\Tests\ConditionalsTemplateReturn\Item>'. [P1006]
phpy 0.2.0phpy 0.2.0 Pass

No diagnostics reported.

qodana 262.8665.325Qodana 262.8665.325 Pass

No diagnostics reported.

noverify 0.5.5NoVerify, version 0.5.5: built on: 2025.04.22 14:36:46 OS: r-kuchinskas arm64 Commit: 4774b82f8adc53fbef38f95e97af4b953b4d1529 Pass

No diagnostics reported.

steins 0.1.5steins 0.1.5 (2026-08-12 revision 39b4cc1) Pass

No diagnostics reported.

phpstan-strict 2.2.8PHPStan - PHP Static Analysis Tool 2.2.8 Pass 
conditionals_template_return.php:52: Parameter #1 $item of function Conformance\Tests\ConditionalsTemplateReturn\takesItem expects Conformance\Tests\ConditionalsTemplateReturn\Item, list<Conformance\Tests\ConditionalsTemplateReturn\Item> given. [identifier=argument.type]
psalm-next 7.0.0-beta19Psalm 7.0.0-beta19@7e751c06a756fa64dc4c759c09fe4a173afcb433 Pass 
conditionals_template_return.php:52: Argument 1 of Conformance\Tests\ConditionalsTemplateReturn\takesItem expects Conformance\Tests\ConditionalsTemplateReturn\Item, but list<Conformance\Tests\ConditionalsTemplateReturn\Item> provided [InvalidArgument]

Source

<?php

declare(strict_types=1);

namespace Conformance\Tests\ConditionalsTemplateReturn;

/**
 * Conditional return type combined with a template parameter.
 *
 * When `$id` is an int, the return is a single `Item`; when `$id` is a list
 * of ints, the return is a list of `Item`. Analyzers that expand the
 * conditional after template inference reject a list return used as a single
 * Item.
 *
 * References:
 * - PHPStan phpdoc-types: Conditional return types + generics
 * - Psalm conditional_types.md
 */

final class Item
{
    public function __construct(
        public int $id,
    ) {
    }
}

/**
 * @template T of int|list<int>
 * @param T $id
 * @return (T is int ? Item : list<Item>) // E<phan>: Phan cannot extract template-conditional return annotations
 */
function fetch(int|array $id): Item|array // E<phan>: without conditional expansion Phan reports template unused in return
{
    // Body is intentionally trivial so control-flow analysis does not dominate
    // the comparison; the conformance question is the annotated return form.
    if (is_int($id)) {
        return new Item($id);
    }

    return [new Item(0)];
}

function takesItem(Item $item): void
{
}

// Scalar id → single Item.
takesItem(fetch(1));

// List id → list<Item>, not a single Item.
takesItem(fetch([1, 2])); // E?: list branch of conditional return should not satisfy Item