Как отказаться от свойства PHP magic в PHPDoc?

Есть ли способ отметить магическое свойство как устаревшее? Рассмотрим следующий, упрощенный код:

/**
 * 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

Это невозможно в 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);
        }
        // ...
    }
}

Ответ 2

Я думаю, что ваш лучший выбор здесь - явно определить свойство $foo, чтобы вы могли документировать его с помощью @deprecated. Чтобы сохранить поведение // do & return something, которое в настоящее время возникает из-за использования $myExample->foo, вы можете назначить анонимную функцию $this->foo в конструкторе. Таким образом, эта логика больше не живет в __get(), которая выпала из пути выполнения, как только $foo был явно определен.

/**
 * Example class
 */
class Example {

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

    /**
     * constructor
     */
    public function __construct() {
        $this->foo = function() {
            // do & return something
        };
    }

    /**
     * Magic getter
     */
    public function __get($var) {
        // no longer handles calls to $this->foo
    } 
}