phpdoc - definición de variables de objeto de retorno para un método

Question

He estado buscando en esto por un tiempo y o bien no estoy usando los términos de búsqueda correctos o me falta algo.

Estoy tratando de averiguar si es posible usar PHPdoc para definir las variables que devuelve el objeto.

Decir que tengo la clase siguiente:

class SomeClass { 
    public function staffDetails($id){ 

     $object = new stdClass(); 
     $object->type = "person"; 
     $object->name = "dave"; 
     $object->age = "46";   

     return $object; 
    } 
} 

Ahora bien, es bastante fácil de definir los parámetros de entrada.

/** 
* Get Staff Member Details 
* 
* @param string $id staff id number 
* 
* @return object 
*/ 

class SomeClass { 
    public function staffDetails($id){ 
     $object = new stdClass(); 
     $object->type = "person"; 
     $object->name = "dave"; 
     $object->age = "46";   

     return $object; 
    } 
} 

La pregunta es ¿existe algo similar para la definición de las variables de salida del objeto devuelto por el método en cuestión para que otro programador no tiene que abrir esta clase y manualmente mirar en el método de ver lo que el ¿El objeto de retorno está volviendo?

Answer 1

Aquí están 4 años después, y todavía no parece haber una manera de anotar las propiedades de un objeto stdClass como se describió originalmente en su pregunta.

Colecciones habían propuesto en PSR-5, pero que parece haber sido derribado: https://github.com/php-fig/fig-standards/blob/211063eed7f4d9b4514b728d7b1810d9b3379dd1/proposed/phpdoc.md#collections

Parece que sólo hay dos opciones disponibles:

Opción 1:

Crear una clase normal que representa su objeto de datos y anota las propiedades.

class MyData 
{ 
    /** 
    * This is the name attribute. 
    * @var string 
    */ 
    public $name; 

    /** 
    * This is the age attribute. 
    * @var integer 
    */ 
    public $age; 
} 

Opción 2:

Crear una clase Struct tipo genérico según lo sugerido por Gordon y extenderlo como su objeto de datos, utilizando la anotación @property para definir lo que es posible acceder con __get valores genéricos y __set.

class Struct 
{ 
    /** 
    * Private internal struct attributes 
    * @var array 
    */ 
    private $attributes = []; 

    /** 
    * Set a value 
    * @param string $key 
    * @param mixed $value 
    */ 
    public function __set($key, $value) 
    { 
     $this->attributes[$key] = $value; 
    } 

    /** 
    * Get a value 
    * @param string $key 
    * @return mixed 
    */ 
    public function __get($key) 
    { 
     return isset($this->attributes[$key]) ? $this->attributes[$key] : null; 
    } 

    /** 
    * Check if a key is set 
    * @param string $key 
    * @return boolean 
    */ 
    public function __isset($key) 
    { 
     return isset($this->attributes[$key]) ? true : false; 
    } 
} 

---

/** 
* @property string $name 
* @property integer $age 
*/ 
class MyData extends Struct 
{ 
    // Can optionally add data mutators or utility methods here 
}