在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來存放值。