Deprecated Function

ID

php.deprecated_function

Severity

low

Remediation Complexity

medium

Remediation Risk

low

Remediation Effort

medium

Resource

Code Smell

Language

Php

Tags

code_smell, deprecation

Description

Reports calls to a free function declared in the same file whose declaration is annotated with a @deprecated tag in the documentation block immediately preceding it. The check is limited to the current file: a function counts as deprecated only when its own declaration in that file is tagged, so no cross-file resolution is required. This is distinct from the rule that flags calls to PHP standard-library functions removed by the language; here the author of the code has marked the function obsolete.

Rationale

A @deprecated tag is a contract between the author and callers: the function still works today but is scheduled for removal, and a replacement usually exists. Continuing to call it spreads dependence on code that will disappear and postpones the migration. Surfacing each call site makes the cost of the deprecation visible and guides the move to the supported alternative.

<?php
/**
 * @deprecated 2.0 use computeTotal() instead
 */
function legacyTotal(array $items): int
{
    return array_sum($items);
}

function computeTotal(array $items): int
{
    return array_sum($items);
}

$a = legacyTotal($items);   // FLAW - calls a function marked @deprecated
$b = computeTotal($items);  // OK - uses the supported replacement

Remediation

Replace the call with the supported alternative named in the @deprecated tag. When no replacement is documented, inline the function’s behaviour or define a maintained equivalent, then remove the dependence on the deprecated function.

References