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