Come deprecare la proprietà magica di PHP in PHPDoc?

Question

C'è un modo per contrassegnare uno magic property come deprecato? Considerate seguente, il codice semplificato:

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

Ora, come per indicare altri sviluppatori, che non dovrebbero più usare Example::$foo? L'unica soluzione di lavoro che mi viene in mente è:

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

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

Ma questa sia spezza il codice (getter non è chiamato) e non si sente molto elegante.

Answer 1

Questo non è possibile con PHPDoc poiché lo @deprecated può essere associato solo a elementi strutturali (documentation).

Se è veramente importante per gli sviluppatori di sapere che essi non dovrebbero più utilizzare questa proprietà magica, si potrebbe attivare un errore 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

penso che la soluzione migliore sarebbe di definire esplicitamente il $foo proprietà, in modo da poterlo documentare con @deprecated. Per mantenere il comportamento di // do & return something che attualmente risulta dall'utilizzo di $myExample->foo, è possibile assegnare una funzione anonima a $this->foo nel costruttore. Pertanto, tale logica non risiede più in __get(), che è caduto fuori dal percorso di esecuzione non appena $foo è stato definito in modo esplicito.

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