如何在 PHPDoc 中弃用 PHP 的魔法属性？

Question

有没有办法将 magic property 标记为已弃用？考虑以下简化代码：

/**
 * 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 没有被调用）而且感觉不是很优雅。

Answer 1

这对于 PHPDoc 是不可能的，因为 @deprecated 只能与结构元素 (documentation) 关联。

如果让开发人员知道他们不应该再使用这个魔法真的很重要属性，您可能会触发 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);
        }
        // ...
    }
}

Answer 2

@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;

截图：

Answer 3

为了防止用户使用您已弃用的属性，您只需从 class header.

中删除此属性的 PHPDoc

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

通过这种方式，您可以让遗留代码继续工作，而属性将不再由 IDE 自动完成工具等显示。

如何在 PHPDoc 中弃用 PHP 的魔法属性？

How to deprecate PHP's magic property in PHPDoc?

php

phpdoc

如何在 PHPDoc 中弃用 PHP 的魔法 属性？

How to deprecate PHP's magic property in PHPDoc?

php

phpdoc

如何在 PHPDoc 中弃用 PHP 的魔法属性？