Phpdoc - defining return object variables for a method

Question

I have been looking for this for a while, and either I am not using the correct search terms or something is missing.

I am trying to figure out if PHPdoc can be used to determine the variables returned by an object.

Let's say I have the following class:

class SomeClass { public function staffDetails($id){ $object = new stdClass(); $object->type = "person"; $object->name = "dave"; $object->age = "46"; return $object; } } 

Now it’s easy enough to determine the input parameters.

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

The question is whether there is a similar thing to determine the output variables of the object returned by the method in question, so that another programmer does not have to open this class and manually look into the method to see that the returned object is returned

Answer 1

Here 4 years later, and there seems to be no way to annotate the properties of the stdClass object, as described in your question.

Collections were offered in PSR-5, but it seems they were shot down: https://github.com/php-fig/fig-standards/blob/211063eed7f4d9b4514b728d7b1810d9b3379dd1/proposed/phpdoc.md#collections

Only two options seem to be available:

Option 1:

Create a normal class that represents your data object and annotate it.

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

Option 2:

Create a generic Struct type proposed by Gordon and extend it as your data object using the @property annotation to determine what common values ​​are accessible by __get and __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

You have only two ways to document the structure of the result class.

1. One can describe the structure in the comment text. For example:

 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. One can create a data type that stdClass will inherit, and it will have an annotation of the result object. For example:

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

In my opinion, this method is better than the description in a text comment, because it makes the code more obvious

Answer 3

For example, using json_decode more difficult to use native classes instead of stdClass , but in my case I just created a dummy file with class definitions that really is not loaded, and I add my own classes like @return (works for intelephense in vscode),

PHPdocObjects.php

 /** * class only for PHPdoc (do not include) */ class Member { /** @var string */ public $type; /** @var string */ public $name; /** @var string */ public $age; } /** * Other format * * @property string $type; * @property string $name; * @property string $age; */ class MemberAlt {} 

SomeClass.php

  /** * Get Staff Member Details * * @param string $id staff id number * * @return Member I'm in fact stdClass */ class SomeClass { public function staffDetails($id){ $object = json_decode('{"type":"person","name":"dave","age":"46"}'); return $object; } }