| commit | author | age | ||
| 2207d6 | 1 | The ReflectionDocBlock Component [](https://travis-ci.org/phpDocumentor/ReflectionDocBlock) |
| W | 2 | ================================ |
| 3 | ||
| 4 | Introduction | |
| 5 | ------------ | |
| 6 | ||
| 7 | The ReflectionDocBlock component of phpDocumentor provides a DocBlock parser | |
| 8 | that is 100% compatible with the [PHPDoc standard](http://phpdoc.org/docs/latest). | |
| 9 | ||
| 10 | With this component, a library can provide support for annotations via DocBlocks | |
| 11 | or otherwise retrieve information that is embedded in a DocBlock. | |
| 12 | ||
| 13 | Installation | |
| 14 | ------------ | |
| 15 | ||
| 16 | ```bash | |
| 17 | composer require phpdocumentor/reflection-docblock | |
| 18 | ``` | |
| 19 | ||
| 20 | Usage | |
| 21 | ----- | |
| 22 | ||
| 23 | In order to parse the DocBlock one needs a DocBlockFactory that can be | |
| 24 | instantiated using its `createInstance` factory method like this: | |
| 25 | ||
| 26 | ```php | |
| 27 | $factory = \phpDocumentor\Reflection\DocBlockFactory::createInstance(); | |
| 28 | ``` | |
| 29 | ||
| 30 | Then we can use the `create` method of the factory to interpret the DocBlock. | |
| 31 | Please note that it is also possible to provide a class that has the | |
| 32 | `getDocComment()` method, such as an object of type `ReflectionClass`, the | |
| 33 | create method will read that if it exists. | |
| 34 | ||
| 35 | ```php | |
| 36 | $docComment = <<<DOCCOMMENT | |
| 37 | /** | |
| 38 | * This is an example of a summary. | |
| 39 | * | |
| 40 | * This is a Description. A Summary and Description are separated by either | |
| 41 | * two subsequent newlines (thus a whiteline in between as can be seen in this | |
| 42 | * example), or when the Summary ends with a dot (`.`) and some form of | |
| 43 | * whitespace. | |
| 44 | */ | |
| 45 | DOCCOMMENT; | |
| 46 | ||
| 47 | $docblock = $factory->create($docComment); | |
| 48 | ``` | |
| 49 | ||
| 50 | The `create` method will yield an object of type `\phpDocumentor\Reflection\DocBlock` | |
| 51 | whose methods can be queried: | |
| 52 | ||
| 53 | ```php | |
| 54 | // Contains the summary for this DocBlock | |
| 55 | $summary = $docblock->getSummary(); | |
| 56 | ||
| 57 | // Contains \phpDocumentor\Reflection\DocBlock\Description object | |
| 58 | $description = $docblock->getDescription(); | |
| 59 | ||
| 60 | // You can either cast it to string | |
| 61 | $description = (string) $docblock->getDescription(); | |
| 62 | ||
| 63 | // Or use the render method to get a string representation of the Description. | |
| 64 | $description = $docblock->getDescription()->render(); | |
| 65 | ``` | |
| 66 | ||
| 67 | > For more examples it would be best to review the scripts in the [`/examples` folder](/examples). | |
