PHPdoc - 为 stdClass 对象定义对象属性

Question

我正在尝试弄清楚是否可以使用 PHPdoc 来定义由函数或对象方法返回的对象属性。

假设我有以下类(class):

class SomeClass {
    public function staffDetails($id){

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

        return $object;
    }
}

现在，很容易定义输入参数。

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

问题是是否有类似的事情来定义相关方法返回的(stdClass 的)输出对象的属性。这样另一个程序员就不必打开这个类并手动查看方法来查看返回对象返回了什么？

Answer 1

现在是 4 年之后，似乎仍然没有办法像您的问题中最初描述的那样注释 stdClass 对象的属性。

集合已在 PSR-5 中提出，但似乎已被否决:https://github.com/php-fig/fig-standards/blob/211063eed7f4d9b4514b728d7b1810d9b3379dd1/proposed/phpdoc.md#collections

似乎只有两个选项可用:

选项 1:

创建一个代表您的数据对象的普通类并注释属性。

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

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

选项 2:

按照 Gordon 的建议创建一个通用的 Struct 类型类并将其扩展为您的数据对象，使用 @property用于定义可以使用 __get 和 __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
}