PHPdoc: definición de propiedades de objeto para un objeto de stdClass

Estoy tratando de averiguar si es posible usar PHPdoc para definir las propiedades del objeto que devuelve una función o un método de 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 si existe algo similar para definir las propiedades del objeto de salida (de un stdClass) devuelto por el método en cuestión. ¿Para que otro programador no tenga que abrir esta clase y buscar manualmente en el método para ver qué está devolviendo el objeto de retorno?

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

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

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:

Crear un genérico Struct escriba la clase como sugiere Gordon y extiéndala como su objeto de datos, usando el @propiedad anotación para definir qué valores genéricos son posibles de 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
}

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

1.Se 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
{}

Y utilízalo en tus otras clases.

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.

Si está utilizando PHP 7, puede definir una clase anónima.

class SomeClass {
    public function staffDetails($id){
        $object = (new class() extends stdClass {
                public /** @var string  */ $type;
                public /** @var string  */ $name;
                public /** @var int     */ $age;
            });

        $object->type = "person";
        $object->name = "dave";
        $object->age  = 46;        

        return $object;
    }
}

Está funcionando para mi IDE (probado en NetBeans)

con por ejemplo json_decode es más difícil usar clases propias en lugar de stdClasspero en mi caso acabo de crear un archivo ficticio con definiciones de clase, que en realidad no está cargado y estoy agregando clases propias como @return (funciona para intelephense en vscode).

PHPdocObjetos.php

/**
 * class only for PHPdoc (do not include)
 */
class Member {
    /** @var string */
    public $type;
    /** @var string */
    public $name;
    /** @var string */
    public $age;
}

/**
 * Other format
 *
 * @property string $type;
 * @property string $name;
 * @property string $age;
 */
class MemberAlt {}

AlgunaClase.php

 /**
 * Get Staff Member Details
 * 
 * @param   string  $id    staff id number
 * 
 * @return  Member  I'm in fact stdClass
 */

class SomeClass {
    public function staffDetails($id){
        $object = json_decode('{"type":"person","name":"dave","age":"46"}');
        return $object;
    }
}

El truco que uso para autocompletar en PhpStorm:

1. Cree algún metaarchivo que contenga algunas clases para describir sus estructuras. El archivo nunca se incluye y las estructuras tienen sus propias reglas de nombres para no confundirlas con las clases reales existentes:

<?php
/*
meta.php
never included
*/

/**
 * @property string $type
 * @property string $name
 * @property string $age
 */
class StaffDetails_meta {}

2. Use la metaclase como valor de retorno en su código real PHPDoc:

<?php
/*
SomeClass.php
eventually included
*/

class SomeClass
{
    
    /**
     * Get Staff Member Details
     * 
     * @param   string  $id    staff id number
     * 
     * @return StaffDetails_meta
     */
    public function staffDetails($id)
    {
        $object = new stdClass();
        $object->type = "person";
        $object->name = "dave";
        $object->age = "46";        

        return $object;
    }
}

3. Felicitaciones, esto hará que su IDE complete automáticamente su código cuando escriba algo como (new SomeClass)->staffDetails('staff_id')->

PD: Lo se, pasaron casi 10 años pero sigue vigente