← 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.10Phan 6.0.10 php-ast version 1.1.3 PHP version used to run Phan: 8.5.11 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.3.1PHPStan - PHP Static Analysis Tool 2.3.1 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. [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.
psalm 6.20.0Psalm 6.20.0@804f03c0c183d149fcd4b8c7c0c9b3fbf836d34c
next: 7.0.0-rc2		 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.57.0mago 1.57.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.87.0mir 0.87.0 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.11.1phpantom_lsp 0.11.1 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]
phpactor 2026.10.07.0Phpactor 2026.10.07.0 Pass

No diagnostics reported.

phpy 1.0.19409phpy 1.0.19409 Pass

No diagnostics reported.

qodana 262.10968.76PhpStorm 262.10968.76 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.8steins 0.1.8 (2026-09-21 revision 76306a9) Pass

No diagnostics reported.

phpstan-strict 2.3.1PHPStan - PHP Static Analysis Tool 2.3.1 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.
psalm-next 7.0.0-rc2Psalm 7.0.0-rc2@20339e3fe5b8d03bcd8061030eb2a83ad50e5783 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