Deprecated Property

ID

php.deprecated_property

Severity

low

Remediation Complexity

medium

Remediation Risk

low

Remediation Effort

medium

Resource

Code Smell

Language

Php

Tags

code_smell, deprecation

Description

Reports accesses to a property declared in the same file and marked deprecated — either through a @deprecated docblock tag or a PHP 8 #[Deprecated] attribute. Both instance accesses ($obj→legacy) and static accesses (Class::$legacy) are inspected; class constants (Class::CONST) are not properties and are ignored.

Because the receiver type is not statically known in PHP, the rule matches by simple property name and only reports a name when every declaration of that name in the file is deprecated, so a same-named non-deprecated property in another class is never flagged. Detection is limited to the current file.

Rationale

A property marked deprecated is scheduled for removal or replacement. Reading or writing it keeps a soon-to-disappear field in use, so the access will break when the property is removed. Flagging the access keeps the migration visible and lets it be redirected to the supported field while the change is still small.

<?php
class Config
{
    /** @deprecated use $timeout */
    public $maxWait = 30;

    #[Deprecated]
    public static $globalFlag = false;

    public $timeout = 10;
}

function run(Config $cfg): void
{
    $a = $cfg->maxWait;         // FLAW - reads a deprecated property
    $b = Config::$globalFlag;   // FLAW - deprecated through an attribute
    $c = $cfg->timeout;         // OK - the supported replacement
}

Remediation

Switch to the supported property named in the deprecation notice. If no replacement exists, raise the gap with the API owner before the property is removed.

References