Annotations

The purpose

The parser MUST extract any docblock, and make them available into the AST.

An docblock is a META definition of an element, so it MUST be attached to the corresponding node, and should not be an standalone element :

<?php
/**
 * @return boolean
 */
function foo() {
  /**
   * Some extra documentation
   */
  return true;
}

In the example bellow, the docblock is not giving extra information about the function like the type of return value, but not the docblock inside the function.

Attached to AST nodes

We will analyse docblocks for the following elements :

• function
• class
• interface
• trait
• assign statements

If the docblock is before any other element, it will be ignored.

How the docBlocks are attached

To be retro-compatible and to avoid extra informations (and extra processing) if not required, the grammar parser will have an option to enable or not the parsing of these docBlocks.

var reader = require('php-parser');
reader.parser.docBlocks = true;
var ast = reader.parseEval('/** @var int */ $x = 1 + 2;');
console.log(ast);

The docBlocks property on the parser object will by default be disabled. When it's disabled, docBlocks are simply ignored.

When enabling the docBlocks parsing, they will surround the AST node with annotation informations.

['program', [
  ['doc', [
    ['var', 'int']
  ], ['assign',
    ['var', ...],
    ['op', ...]
  ]]
]]

The DOC node will contains at offset 1 an array of childs parsed from the docblock contents, and at offset 2 the surrounding AST node that should be concerned by the doc block.

The Syntax

The valid annotations syntax are :

<?php 
  /**
   * @params boolean $name Some information text
   * @return array<string>
   * @return map<string, SomeClass>
   * @throws Exception
   * @deprecated
   * @table('tableName', true)
   * @table(
   *   name='tableName', 
   *   primary=true
   * )
   * @annotation1 @annotation2
   * @Target(["METHOD", "PROPERTY"])
   * @Attributes([
   *   @Attribute("stringProperty", type = "string"),
   *   @Attribute("annotProperty",  type = "SomeAnnotationClass"),
   * ])
   * @json({
   *   "key": "value",
   *   "object": { "inner": true },
   *   "list": [1, 2, 3]
   * })
   */

Doctrine support

Doctrine had made a terribly bad choice by using { ... } for arrays, because thats removes the possibility use into annotation structures based on json. For this reason, the support of doctrine will not be proposed by default, and maybe? an option will be available for parsing them (and also disabling the json parsing features)

<php 
 /**
* @Annotation
* @Target({"METHOD","PROPERTY"})
* @Attributes({
*   @Attribute("stringProperty", type = "string"),
*   @Attribute("annotProperty",  type = "SomeAnnotationClass"),
* })
*/
class Foo { }

Handling parse errors

When a parse error occurs, there is 2 options, ignore them, or trigger an error. The doc blocks are used for annotation, but also for descriptions. We can not trigger an error on a bad formed comment, but if the '@' is found in the tokens, it will automatically expect a valid syntax.

If the syntax is good, an AST node will be added, if it's not, then the annotation will be considered as text.

<?php // @todo add some samples / use cases here

Readings :

• https://wiki.php.net/rfc/annotations-in-docblock
• http://doctrine-common.readthedocs.org/en/latest/reference/annotations.html
• https://wiki.php.net/rfc/annotations