在PHPDoc中声明局部变量的属性

Question

我有一个带有一些属性的stdClass实例。在PHPDoc中声明这些属性的正确方法是什么？ 我想这一点，但现在看来，这是不正常：

/** 
    * @var $requestParams stdClass 
    * @property string cancelUrl 
    */ 
    $requestParams = $someObj->getSomething(); 

Answer 1

与new stdClass()的问题是，你可以在飞行中声明属性，所以这将是很难的任何记录器通过所有代码解析，找到所有的您可以添加新特性的地方，这样，而不是你需要创建一个类为它和文档类：

所以不是这样：

/** 
* ... doc block here 
*/ 
class SomeObj { 
    /** 
    * ... doc block here 
    * @return stdClass 
    */ 
    function getSomething() { 
     return new stdClass(); 
    } 
} 

你这样做：

/** 
* ... doc block here 
*/ 
class SomeObj { 
    /** 
    * ... doc block here 
    * @return Something 
    */ 
    function getSomething() { 
     return new Something(); 
    } 
} 

/** 
* ... doc block here 
*/ 
class Something { 
    /** 
    * @var string 
    */ 
    public $cancelUrl; 
} 

Answer 2

鉴于你的代码示例，你能做的最好的是表示这个$requestParams通过@var是stdClass型。您使用@property不会为您做任何事情，因为该标签仅针对某个类中存在的魔术属性进行了专门定义...因此，只有在类 docblock中才会读取并解释@property。

如果你只需要显示$ requestParams是stdClass的一个实例，那么@var就是你所需要的。但是，如果您还想表示$ requestParams-> cancelUrl是一个已知的字符串属性，而不更改为实际定义的类，则必须以与$ requestParams是本地变量相同的方式使用另一个局部变量：

/** @var stdClass $requestParams */ 
$requestParams = $someObj->getSomething(); 

/** @var string $cancelUrl */ 
$cancelUrl = $requestParams->cancelUrl; 

除了回答您的直接问题 - 如果您向读者展示此$ requestParams元素具有某些定义的属性非常重要，我会选择为其编写一个正式的类。当然，该类中的实现仍然只是一个内部的stdClass来存放值。