Declare local variable properties in PHPDoc

Question

I have an instance of stdClass with some properties. What is the correct way to declare these properties in PHPDoc? I tried this, but it seems like this is not normal:

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

Answer 1

Based on your sample code, it is best to use the $requestParams type stdClass via @var . Your use of @property will not do anything for you, because this tag is defined only for magic properties existing in the class ... therefore, @property will be read and interpreted only when it is in the docblock class.

If you only need to show that $ requestParams is an instance of stdClass, then @var is all you need. However, if you want to point out once again that $ requestParams-> cancelUrl is a known string property, without changing it to the actual specific class, you will have to use another local variable in the same way that $ requestParams is a local variable:

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

Besides the answer to your direct question - if it is really important for you to show your readers that this element of $ requestParams has certain specific properties, I would choose a formal class for it. An implementation in this class can still be just an internal stdClass for storing values, of course.

Answer 2

The problem with new stdClass() is that you can declare properties on the fly, so for any documenter it would be difficult to analyze all your code to find all the places where you add new properties, instead you need to create a class for him and document this class:

So instead:

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

You do it:

 /** * ... doc block here */ class SomeObj { /** * ... doc block here * @return Something */ function getSomething() { return new Something(); } } /** * ... doc block here */ class Something { /** * @var string */ public $cancelUrl; }