Native type wins when PHPDoc names a different kind

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

@return bool on a function whose native return is Query is not a narrowing. Runtime still returns a Query. A sound checker keeps the native class for call sites: load()->execute() is valid, and takesBool(load()) is not. A checker that substitutes the PHPDoc type rejects the method call and accepts the bool parameter. The nullable-doc-vs-native gap (@param string on ?string $name) is phpdoc_advanced_param_typehint_nullable_mismatch and is style. This file is the contradictory-kind case. References: - mago#2494

Analyzer results

Analyzer	Version	Result	Diagnostics
phan	6.0.10Phan 6.0.10 php-ast version 1.1.3 PHP version used to run Phan: 8.5.11	Pass	phpdoc_advanced_native_overrides_contradictory_docblock.php:33: Doc-block of load contains declared return type bool which is incompatible with the return type \Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query declared in the signature [PhanTypeMismatchDeclaredReturn] phpdoc_advanced_native_overrides_contradictory_docblock.php:60: Argument 1 ($value) is load() of type \Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query\|bool (real type \Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query) but \Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\takesBool() takes bool defined at /Users/megurine/repo/php/php-typing-conformance/conformance/tests/phpdoc_advanced_native_overrides_contradictory_docblock.php:40 [PhanTypeMismatchArgumentReal]
phpstan	2.3.1PHPStan - PHP Static Analysis Tool 2.3.1	Pass reported Lv.2+	phpdoc_advanced_native_overrides_contradictory_docblock.php:35: PHPDoc tag @return with type bool is incompatible with native type Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query. [reported-from-level=2] phpdoc_advanced_native_overrides_contradictory_docblock.php:60: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\takesBool expects bool, Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query given. [reported-from-level=5] With strict-rules phpdoc_advanced_native_overrides_contradictory_docblock.php:35: PHPDoc tag @return with type bool is incompatible with native type Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query. phpdoc_advanced_native_overrides_contradictory_docblock.php:60: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\takesBool expects bool, Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query given.
psalm	6.20.0Psalm 6.20.0@804f03c0c183d149fcd4b8c7c0c9b3fbf836d34c next: 7.0.0-rc2	Fail (pzoom≠)	phpdoc_advanced_native_overrides_contradictory_docblock.php:33: Docblock has incorrect return type 'bool', should be 'Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query' [MismatchingDocblockReturnType] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Argument 1 of echo cannot be mixed, expecting string [MixedArgument] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Cannot call method on bool variable [InvalidMethodCall] phpdoc_advanced_native_overrides_contradictory_docblock.php:55: Argument 1 of Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\takesQuery expects Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query, but bool provided [InvalidArgument] pzoom (Psalm port) phpdoc_advanced_native_overrides_contradictory_docblock.php:35: Docblock has incorrect return type 'bool', should be 'Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query' [MismatchingDocblockReturnType] phpdoc_advanced_native_overrides_contradictory_docblock.php:37: The type Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query does not match the declared return type bool [InvalidReturnStatement] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Cannot call method execute on bool [InvalidMethodCall] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Argument 1 of echo cannot be mixed, expecting string [MixedArgument] phpdoc_advanced_native_overrides_contradictory_docblock.php:55: Argument 1 of takesQuery expects Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query, but bool provided [InvalidArgument] Expectation diff Line 60: Expected 1 error(s) Line 50: Expected valid value to be accepted, got ["Argument 1 of echo cannot be mixed, expecting string [MixedArgument]","Cannot call method on bool variable [InvalidMethodCall]"] Line 55: Expected valid value to be accepted, got ["Argument 1 of Conformance\\Tests\\PhpdocAdvancedNativeOverridesContradictoryDocblock\\takesQuery expects Conformance\\Tests\\PhpdocAdvancedNativeOverridesContradictoryDocblock\\Query, but bool provided [InvalidArgument]"]
mago	1.57.0mago 1.57.0	Pass	phpdoc_advanced_native_overrides_contradictory_docblock.php:35: Docblock return type `bool` is incompatible with native return type `Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query`. [docblock-type-mismatch] phpdoc_advanced_native_overrides_contradictory_docblock.php:37: Invalid return type for function `Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\load`: expected `bool`, but found `Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query`. [invalid-return-statement] phpdoc_advanced_native_overrides_contradictory_docblock.php:60: Invalid argument type for argument #1 of `Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\takesBool`: expected `bool`, but found `Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query`. [invalid-argument]
mir	0.87.0mir 0.87.0	Fail	phpdoc_advanced_native_overrides_contradictory_docblock.php:35: MismatchingDocblockReturnType: Docblock return type 'bool' does not match inferred 'Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query' [MIR0209] phpdoc_advanced_native_overrides_contradictory_docblock.php:37: InvalidReturnType: Return type 'Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query' is not compatible with declared 'bool' [MIR0200] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: InvalidMethodCall: Cannot call method execute() on non-object type 'bool' [MIR0230] phpdoc_advanced_native_overrides_contradictory_docblock.php:55: InvalidArgument: Argument $value of takesQuery() expects 'Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query', got 'bool' [MIR0201] Expectation diff Line 60: Expected 1 error(s) Line 50: Expected valid value to be accepted, got ["InvalidMethodCall: Cannot call method execute() on non-object type 'bool' [MIR0230]"] Line 55: Expected valid value to be accepted, got ["InvalidArgument: Argument $value of takesQuery() expects 'Conformance\\Tests\\PhpdocAdvancedNativeOverridesContradictoryDocblock\\Query', got 'bool' [MIR0201]"]
phpantom	0.11.1phpantom_lsp 0.11.1	Pass	phpdoc_advanced_native_overrides_contradictory_docblock.php:60: Argument 1 ($value) expects bool, got Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query [type_mismatch_argument]
intelephense	1.18.5intelephense 1.18.5	Fail	phpdoc_advanced_native_overrides_contradictory_docblock.php:33: Documented type is not compatible with the declared type. [P1131] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Expected type 'string\|Stringable\|null'. Found 'mixed'. [P1006] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Expected type 'object'. Found 'bool'. [P1006] phpdoc_advanced_native_overrides_contradictory_docblock.php:55: Expected type 'Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query'. Found 'bool'. [P1006] Expectation diff Line 60: Expected 1 error(s) Line 50: Expected valid value to be accepted, got ["Expected type 'string\|Stringable\|null'. Found 'mixed'. [P1006]","Expected type 'object'. Found 'bool'. [P1006]"] Line 55: Expected valid value to be accepted, got ["Expected type 'Conformance\\Tests\\PhpdocAdvancedNativeOverridesContradictoryDocblock\\Query'. Found 'bool'. [P1006]"]
phpactor	2026.10.07.0Phpactor 2026.10.07.0	Fail	No diagnostics reported. Expectation diff Line 60: Expected 1 error(s)
phpy	1.0.19409phpy 1.0.19409	Fail	No diagnostics reported. Expectation diff Line 60: Expected 1 error(s)
qodana	262.10968.76PhpStorm 262.10968.76	Fail	phpdoc_advanced_native_overrides_contradictory_docblock.php:33: Return type does not match the declared [PhpDocSignatureInspection] Expectation diff Line 60: Expected 1 error(s)
noverify	0.5.5NoVerify, version 0.5.5: built on: 2025.04.22 14:36:46 OS: r-kuchinskas arm64 Commit: 4774b82f8adc53fbef38f95e97af4b953b4d1529	Fail	phpdoc_advanced_native_overrides_contradictory_docblock.php:50: potentially not safe call in \Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\load when accessing method [notSafeCall] Expectation diff Line 60: Expected 1 error(s) Line 50: Expected valid value to be accepted, got ["potentially not safe call in \\Conformance\\Tests\\PhpdocAdvancedNativeOverridesContradictoryDocblock\\load when accessing method [notSafeCall]"]
steins	0.1.8steins 0.1.8 (2026-09-21 revision 76306a9)	Fail	phpdoc_advanced_native_overrides_contradictory_docblock.php:37: return value new Query() violates declared @return bool of load() — declared contract violation [phpdoc.return-mismatch] Expectation diff Line 60: Expected 1 error(s)
phpstan-strict	2.3.1PHPStan - PHP Static Analysis Tool 2.3.1	Pass	phpdoc_advanced_native_overrides_contradictory_docblock.php:35: PHPDoc tag @return with type bool is incompatible with native type Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query. phpdoc_advanced_native_overrides_contradictory_docblock.php:60: Parameter #1 $value of function Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\takesBool expects bool, Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query given.
psalm-next	7.0.0-rc2Psalm 7.0.0-rc2@20339e3fe5b8d03bcd8061030eb2a83ad50e5783	Fail	phpdoc_advanced_native_overrides_contradictory_docblock.php:33: Docblock has incorrect return type 'bool', should be 'Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query' [MismatchingDocblockReturnType] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Argument 1 of echo cannot be mixed, expecting string [MixedArgument] phpdoc_advanced_native_overrides_contradictory_docblock.php:50: Cannot call method on bool variable [InvalidMethodCall] phpdoc_advanced_native_overrides_contradictory_docblock.php:55: Argument 1 of Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\takesQuery expects Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock\Query, but bool provided [InvalidArgument] Expectation diff Line 60: Expected 1 error(s) Line 50: Expected valid value to be accepted, got ["Argument 1 of echo cannot be mixed, expecting string [MixedArgument]","Cannot call method on bool variable [InvalidMethodCall]"] Line 55: Expected valid value to be accepted, got ["Argument 1 of Conformance\\Tests\\PhpdocAdvancedNativeOverridesContradictoryDocblock\\takesQuery expects Conformance\\Tests\\PhpdocAdvancedNativeOverridesContradictoryDocblock\\Query, but bool provided [InvalidArgument]"]

Source

<?php

declare(strict_types=1);

namespace Conformance\Tests\PhpdocAdvancedNativeOverridesContradictoryDocblock;

/**
 * Native type wins when PHPDoc names a different kind.
 *
 * `@return bool` on a function whose native return is `Query` is not a
 * narrowing. Runtime still returns a `Query`. A sound checker keeps the
 * native class for call sites: `load()->execute()` is valid, and
 * `takesBool(load())` is not. A checker that substitutes the PHPDoc type
 * rejects the method call and accepts the bool parameter.
 *
 * The nullable-doc-vs-native gap (`@param string` on `?string $name`) is
 * `phpdoc_advanced_param_typehint_nullable_mismatch` and is style. This
 * file is the contradictory-kind case.
 *
 * References:
 * - https://github.com/carthage-software/mago/pull/2494
 */

final class Query
{
    public function execute(): string
    {
        return 'ok';
    }
}

/**
 * @return bool // E?[doc_mismatch+]: PHPDoc bool contradicts native Query
 */
function load(): Query // E?[doc_mismatch+]: PHPDoc bool contradicts native Query
{
    return new Query(); // E?[doc_mismatch+]: body is Query; PHPDoc says bool
}

function takesBool(bool $value): void
{
}

function takesQuery(Query $value): void
{
}

function callExecute(): void
{
    echo load()->execute(); // V: native Query has execute()
}

function passAsQuery(): void
{
    takesQuery(load()); // V: native return is Query
}

function passAsBool(): void
{
    takesBool(load()); // E: Query is not bool
}