phpdoc - 为方法定义返回对象变量

Question

我一直在搜索这个问题,要么我没有使用正确的搜索条件,要么我错过了一些东西.

我试图弄清楚是否可以使用PHPdoc来定义对象返回的变量.

说我有以下课程:

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

问题是是否有类似的事情来定义相关方法返回的对象的输出变量,以便另一个程序员不必打开这个类并手动查看方法以查看返回对象返回的内容？

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:

Struct根据Gordon的建议创建泛型类,并将其扩展为数据对象,使用@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
}

Answer 2

如果您使用 PHP 7，您可以定义匿名类。

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

它适用于我的 IDE（在 NetBeans 中测试）

Answer 3

您只有两种方法来记录结果类的结构。

1.可以在评论文本中描述结构。例如：

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.可以创建一个继承stdClass的数据类型，它会有一个结果对象的注解。例如：

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

在我看来，这种方式比文本注释中的描述要好，因为它使代码更明显