如何在 PHPDoc 中弃用 PHP 的神奇属性？

php phpdoc

2022-08-30 15:20:28

有没有办法将魔术属性标记为已弃用？请考虑以下简化代码：

/**
 * Example class
 *
 * @property string $foo A foo variable.
 */
class Example {
    /**
     * Magic getter
     */
    public function __get($var) {
        if('foo' === $var) {
            // do & return something
        }
    } 
}

现在，如何指示其他开发人员，他们不应该再使用？我想到的唯一可行的解决方案是：Example::$foo

/**
 * Example class
 */
class Example {
    /**
     * A foo variable.
     *
     * @var string
     * @deprecated
     */
    public $foo;

    /**
     * Magic getter
     */
    public function __get($var) {
        if('foo' === $var) {
            // do & return something
        }
    } 
}

但这既破坏了我的代码（不调用getter），又感觉不是很优雅。

答案 1

@mixin方法至少适用于PhpStorm：

/**
 * class or trait for the {@mixin} annotation
 */
trait DeprecatedExampleTrait {

    /**
     * Declare it as private to increase the warning level
     * @deprecated
     * @var string
     */
    public $foo;
}

/**
 * Example class
 *
 * @mixin DeprecatedExampleTrait
 *
 * @property string $newFoo A foo variable.
 */
class Example {
    /**
     * Magic getter
     */
    public function __get($var) {
        if (in_array($var, ['foo', 'newFoo'])) {
            // do & return something
        }
    }
}

$example = new Example;
$example->foo;

截图：

答案 2

这在 PHPDoc 中是不可能的，因为只能与结构元素（文档）相关联。@deprecated

如果开发人员知道他们不应该再使用此神奇属性非常重要，则可能会触发错误：E_USER_DEPRECATED

/**
 * Example class
 *
 * @property string $foo A foo variable.
 */
class Example {

    public function __get($name)
    {
        if ($name === 'foo') {
            trigger_error('Property $foo is deprecated and should no longer be used', E_USER_DEPRECATED);
        }
        // ...
    }
}