phpdocs - phpdoc-definiendo variables de objeto de retorno para un método

phpdoc function

Question

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

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

Digamos que tengo la siguiente clase:

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

Ahora, es bastante fácil definir 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: ¿hay algo similar para definir las variables de salida del objeto devuelto por el método en cuestión de modo que otro programador no tenga que abrir esta clase y mirar manualmente el método para ver qué está devolviendo el objeto devuelto?

Answer 1

Aquí es 4 años más tarde, y todavía no parece haber una forma de anotar las propiedades de un objeto stdClass como se describió originalmente en su pregunta.

Las colecciones se habían propuesto en PSR-5, pero eso parece haberse derribado: https://github.com/php-fig/fig-standards/blob/211063eed7f4d9b4514b728d7b1810d9b3379dd1/proposed/phpdoc.md#collections

Parece que solo hay dos opciones disponibles:

Opción 1:

Cree una clase normal que represente su objeto de datos y anote las propiedades.

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

Opcion 2:

Cree una clase de tipo Struct genérica como lo sugiere y Struct como su objeto de datos, utilizando la anotación @property para definir a qué valores genéricos es posible acceder con __get 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
}

Answer 2

Solo tiene dos formas de documentar la estructura de la clase de resultado.

1. Uno puede describir la estructura en un texto de comentario. Por ejemplo:

class SomeClass
{
/**
* Getting staff detail.
* Result object has following structure:
* <code>
* $type - person type
* $name - person name
* $age - person age
* </code>
* @param string $id staff id number
*
* @return stdClass
*
*/
public function staffDetails($id){
$object = new stdClass();
$object->type = "person";
$object->name = "dave";
$object->age = "46";
return $object;
}
}

2. Uno puede crear un tipo de datos que heredará stdClass y tendrá una anotación de un objeto de resultado. Por ejemplo:

/**
* @property string $type Person type
* @property string $name Person name
* @property integer $age Person age
*/
class DTO extends stdClass
{}
class SomeClass {
/**
* Getting staff detail.
*
* @param string $id staff id number
*
* @return DTO
*
*/
public function staffDetails($id){
$object = new DTO();
$object->type = "person";
$object->name = "dave";
$object->age = "46";
return $object;
}
}

En mi opinión, esta forma es mejor que una descripción en el comentario de texto porque hace que el código sea más obvio