int is dropped from a conditional return type branch typed int|false on PHP 8.3+ #15268

Bug report

When a function declares a conditional return type and one of its branches is the union int|false, the int member is silently dropped from the type a caller sees, but only when PHPStan itself is executed on PHP 8.3 or newer. Running the same PHPStan version on PHP 8.2 gives the correct result.

The condition itself resolves correctly when the argument type is known. The loss only shows up when the argument is not narrow enough to select a branch, so PHPStan has to combine both branches: the combined type comes back missing int.

Because the resulting type is wrong rather than absent, it produces confident false positives downstream. In our case return.unusedType fires and claims a function never returns int when it plainly does.

The Playground link below does not reproduce this, and that is the clearest evidence for it. The Playground returns the correct bool|int for every analysed phpVersion from 70200 to 80500, which suggests its own runtime is PHP 8.2 or older. Reproducing it needs PHPStan to be run locally on PHP 8.3 or newer.

Reproducer

<?php declare(strict_types=1);

/**
 * @param int|false $priority
 * @return ($priority is int ? bool : int|false)
 */
function leaf($priority = false)
{
    return is_int($priority) ? true : 5;
}

/**
 * @param int|false $priority
 */
function caller($priority): void
{
    \PHPStan\dumpType(leaf($priority)); // bool|int on PHP 8.2, bool on PHP 8.3+
}

Level 10, no bleeding edge, no strict rules, default configuration.

Adding a return makes the consequence visible:

/**
 * @param int|false $priority
 * @return ($priority is int ? bool : int|false)
 */
function wrapper($priority = false)
{
    return leaf($priority);
}

Function wrapper() never returns int so it can be removed from the return type.
    identifier: return.unusedType

wrapper() does return int, since leaf(false) returns 5. Reported from level 4 upward; below that the type is still wrong, only nothing reports it.

Which branch types are affected

Same reproducer throughout, varying only the two branch types, with the parameter int|false and the condition $p is int. PHP 8.3.33, 8.4.25 and 8.5.9 all produce the same results, so they are shown as one column:

Only branches typed exactly int|false lose a member, and what they lose is always int. The false survives. int|null, int|string, string|false and float|false are all unaffected, as is a plain (non-conditional) @return bool|int.

Environment matrix

PHPStan version makes no difference. The PHP version PHPStan runs on decides it:

The analysed phpVersion is not the trigger. Setting it to 70400, 80100, 80300, 80400 or 80500 makes no difference in either direction; only the runtime matters.

Ruled out: OPcache (enabled on all four runtimes), JIT (tracing on both 8.2 and 8.3, disabled on 8.4 and 8.5, so it does not track the split), the result cache (verified with cold, isolated tmpDir per run), bleeding edge, strict rules, and treatPhpDocTypesAsCertain.

• OS: macOS 15.6 (Darwin 24.6.0), arm64
• PHP builds: Homebrew php@8.2 8.2.33, php@8.3 8.3.33, php@8.4 8.4.25, php 8.5.9

Impact

Found in WordPress core while annotating has_filter(), whose return type is exactly this shape: a bool when called without a callback, the callback's priority as an int otherwise, and false when it is not attached:

 * @phpstan-return (
 *     $callback is false
 *         ? bool
 *         : ( $priority is int
 *             ? bool
 *             : int|false )
 * )

The annotation is correct and resolves correctly at every call site; the false positive lands on the delegating wrappers, because the type they receive from the callee has already lost its int.

A wrong type is worse here than a missing one. Callers that do the natural thing with a priority, such as $priority = has_filter( $hook, $cb ); add_filter( $hook, $cb, $priority + 1 );, are checked against a type that cannot represent what the function returns.

🤖 This report was authored with the assistance of Claude Opus 5 running in Claude Code.

Code snippet that reproduces the problem

https://phpstan.org/r/fbdbc4c7-f6cc-4452-ba47-33332f2a5aa2

Expected output

The issue is reported incorrectly. Two things are expected and only the second one holds today.

$priority is int|false, so the condition $priority is int is neither definitively true nor definitively false. Both branches apply, and \PHPStan\dumpType(leaf($priority)) should print the union of them:

Dumped type: bool|int

On PHP 8.3 and newer it prints bool instead.

Following from that, no return.unusedType error is expected for wrapper(), because int is part of what it returns. On PHP 8.3 and newer the error is reported.

Both outputs are already correct when PHPStan runs on PHP 8.2, so no change in behaviour is being asked for beyond making 8.3 and newer agree with it.

Did PHPStan help you today? Did it make you happy in any way?

Type security gives me all the feels!