← All results

Docblock-typed properties are invariant under inheritance

Group: Properties · Category: language · File: properties_docblock_type_invariance.php

PHP checks invariance only for native property types. An untyped property whose type lives in @var gets no runtime check, so a child that widens or narrows it breaks code written against the parent: widening lets a read return a value the parent never promised, narrowing lets a write through the parent store a value the child does not admit. Source: vimeo/psalm#5131 (4.5.0), NonInvariantDocblockPropertyType. References: - psalm#5131 - Psalm docs: running_psalm/issues/NonInvariantDocblockPropertyType.md

Analyzer results

AnalyzerVersionResultDiagnostics
phan 6.0.11Phan 6.0.11 php-ast version 1.1.3 PHP version used to run Phan: 8.5.11 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
phpstan 2.3.5PHPStan - PHP Static Analysis Tool 2.3.5 Pass reported Lv.3+ 
properties_docblock_type_invariance.php:46: PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null of property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$widened is not the same as PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null of overridden property Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$widened. [reported-from-level=3]
properties_docblock_type_invariance.php:49: PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null of property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$narrowed is not the same as PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null of overridden property Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$narrowed. [reported-from-level=3]
With strict-rules
properties_docblock_type_invariance.php:46: PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null of property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$widened is not the same as PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null of overridden property Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$widened.
properties_docblock_type_invariance.php:49: PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null of property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$narrowed is not the same as PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null of overridden property Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$narrowed.
psalm 6.20.9Psalm 6.20.9@f67170ac3c3b931f5088681e21d6c8babc601c08
next: 7.0.4		 Pass 
properties_docblock_type_invariance.php:46: Property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$widened has type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null, not invariant with Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$widened of type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null [NonInvariantDocblockPropertyType]
properties_docblock_type_invariance.php:49: Property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$narrowed has type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null, not invariant with Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$narrowed of type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null [NonInvariantDocblockPropertyType]
mago 1.59.0mago 1.59.0 Pass 
properties_docblock_type_invariance.php:45: Property `Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$widened` has an incompatible type declaration from docblock. [incompatible-property-type]
properties_docblock_type_invariance.php:48: Property `Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$narrowed` has an incompatible type declaration from docblock. [incompatible-property-type]
mir 0.91.0mir 0.91.0 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
phpantom 0.11.1phpantom_lsp 0.11.1 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
intelephense 1.18.5intelephense 1.18.5 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
phpactor 2026.10.07.0Phpactor 2026.10.07.0 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
phpy 1.0.19490phpy 1.0.19490 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
qodana 262.11879.104PhpStorm 262.11879.104 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
noverify 0.5.5NoVerify, version 0.5.5: built on: 2025.04.22 14:36:46 OS: r-kuchinskas arm64 Commit: 4774b82f8adc53fbef38f95e97af4b953b4d1529 Fail

No diagnostics reported.

Expectation diff
Lines 45, 46: Expected error (tag widened)
Lines 48, 49: Expected error (tag narrowed)
steins 0.1.8steins 0.1.8 (2026-09-21 revision 76306a9) Pass 
properties_docblock_type_invariance.php:46: property Child::$widened has no type — no native type and no `@var` [untyped.property]
properties_docblock_type_invariance.php:49: property Child::$narrowed has no type — no native type and no `@var` [untyped.property]
phpstan-strict 2.3.5PHPStan - PHP Static Analysis Tool 2.3.5 Pass 
properties_docblock_type_invariance.php:46: PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null of property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$widened is not the same as PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null of overridden property Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$widened.
properties_docblock_type_invariance.php:49: PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null of property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$narrowed is not the same as PHPDoc type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null of overridden property Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$narrowed.
psalm-next 7.0.4Psalm 7.0.4@fa5b1f6e665cb743838ffd865b8fc96207f9409f Pass 
properties_docblock_type_invariance.php:46: Property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$widened has type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null, not invariant with Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$widened of type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null [NonInvariantDocblockPropertyType]
properties_docblock_type_invariance.php:49: Property Conformance\Tests\PropertiesDocblockTypeInvariance\Child::$narrowed has type Conformance\Tests\PropertiesDocblockTypeInvariance\ChildInterface|null, not invariant with Conformance\Tests\PropertiesDocblockTypeInvariance\Base::$narrowed of type Conformance\Tests\PropertiesDocblockTypeInvariance\ParentInterface|null [NonInvariantDocblockPropertyType]

Source

<?php

declare(strict_types=1);

namespace Conformance\Tests\PropertiesDocblockTypeInvariance;

/**
 * Docblock-typed properties are invariant under inheritance.
 *
 * PHP checks invariance only for native property types. An untyped property
 * whose type lives in `@var` gets no runtime check, so a child that widens or
 * narrows it breaks code written against the parent: widening lets a read
 * return a value the parent never promised, narrowing lets a write through
 * the parent store a value the child does not admit.
 *
 * Source: vimeo/psalm#5131 (4.5.0), NonInvariantDocblockPropertyType.
 *
 * References:
 * - https://github.com/vimeo/psalm/pull/5131
 * - Psalm docs: running_psalm/issues/NonInvariantDocblockPropertyType.md
 */

interface ParentInterface
{
}

interface ChildInterface extends ParentInterface
{
}

class Base
{
    /** @var ChildInterface|null */
    public $widened = null;

    /** @var ParentInterface|null */
    public $narrowed = null;

    /** @var ChildInterface|null */
    public $matching = null;
}

final class Child extends Base
{
    /** @var ParentInterface|null */ // E[widened]: widening the parent's ChildInterface is unsound for reads
    public $widened = null; // E[widened]

    /** @var ChildInterface|null */ // E[narrowed]: narrowing the parent's ParentInterface is unsound for writes
    public $narrowed = null; // E[narrowed]

    /** @var ChildInterface|null */
    public $matching = null; // V: the same docblock type is invariant
}