PHPackages                             herrera-io/annotations - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. herrera-io/annotations

AbandonedArchivedLibrary[Database & ORM](/categories/database)

herrera-io/annotations
======================

A tokenizer for Doctrine annotations.

1.0.1(12y ago)22128.4k10MITPHPPHP >=5.3.3

Since Jul 29Pushed 12y agoCompare

[ Source](https://github.com/kherge-archive/php-annotations)[ Packagist](https://packagist.org/packages/herrera-io/annotations)[ Docs](https://github.com/herrera-io/php-annotations)[ RSS](/packages/herrera-io-annotations/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (7)Used By (10)

Annotations
===========

[](#annotations)

[![Build Status](https://camo.githubusercontent.com/62bd6be76a87262c1792170ba0888254fd682c9b0e0707cf87ba0c739059d2d3/68747470733a2f2f7472617669732d63692e6f72672f686572726572612d696f2f7068702d616e6e6f746174696f6e732e706e673f6272616e63683d6d6173746572)](https://travis-ci.org/herrera-io/php-annotations)

The Annotations library is for tokenizing and converting Doctrine-styled [annotations](http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/annotations.html). Unlike the Doctrine Annotations library, this one does not require that classes or constants exist, nor are they evaluated.

> The [`DocLexer`](https://github.com/doctrine/annotations/blob/master/lib/Doctrine/Common/Annotations/DocLexer.php) class from the Doctrine Annotations library is used to generate the tokens from the annotated docblocks. This library handles the filtering, validation, and conversion of those tokens.

Example
-------

[](#example)

```
use Herrera\Annotations\Tokenizer;

$tokenizer = new Tokenizer();

$tokens = $tokenizer->parse(
     'Doctrine\\ORM\\Mapping');

$parsed = $tokenizer->parse($docblock, $aliases);
```

The `ignore()` method allows you to specify a list of annotations to ignore. By default, none are ignored, so it may be beneficial to register the default list provided by Doctrine:

```
array(
  'Annotation', 'Attribute', 'Attributes', 'Required', 'SuppressWarnings',
  'TODO', 'Target', 'abstract', 'access', 'api', 'author', 'category', 'code',
  'codeCoverageIgnore', 'codeCoverageIgnoreEnd', 'codeCoverageIgnoreStart',
  'copyright', 'deprec', 'deprecated', 'endcode', 'example', 'exception',
  'filesource', 'final', 'fixme', 'global', 'ignore', 'ingroup', 'inheritDoc',
  'inheritdoc', 'internal', 'license', 'link', 'magic', 'method', 'name',
  'override', 'package', 'package_version', 'param', 'private', 'property',
  'return', 'see', 'since', 'static', 'staticVar', 'staticvar', 'subpackage',
  'throw', 'throws', 'todo', 'tutorial', 'usedby', 'uses', 'var', 'version',
)
```

The `$aliases` argument allows you to specify a list of aliases that may have been used for the name of the annotation. For example. it is common practice to shorten the name of Doctrine ORM annotations using the following:

```
use Doctrine\ORM\Mapping as ORM;
```

The `$aliases` example demonstrates how only the `ORM` namespace alias will be mapped to `Doctrine\ORM\Mapping`. Additional aliases can be specified at the same time:

```
$aliases = array(
    'Assert' => 'Symfony\Component\Validator\Constraints',
    'ORM' => 'Doctrine\ORM\Mapping',
    'Route' => 'Sensio\Bundle\FrameworkExtraBundle\Configuration\Route',
);
```

The value of `$parsed` is an array of tokens. Each token will contain the token's numeric identifier, followed by the value parsed from the docblock (if applicable).

> You can find a reference of the [token identifiers here](https://github.com/doctrine/annotations/blob/master/lib/Doctrine/Common/Annotations/DocLexer.php#L35).

This example docblock:

```
/**
 * @author Some Author
 *
 * @package MyPackage
 *
 * @ORM\Column(name="MyColumn")
 */
```

will yield the following tokens in `$tokens`:

```
$parsed = array(
    array(DocLexer::T_AT),
    array(DocLexer::T_IDENTIFIER, 'Doctrine\\ORM\\Mapping\\Column'),
    array(DocLexer::T_OPEN_PARENTHESIS),
    array(DocLexer::T_IDENTIFIER, 'name'),
    array(DocLexer::T_EQUALS),
    array(DocLexer::T_STRING, 'MyColumn'),
    array(DocLexer::T_CLOSE_PARENTHESIS)
);
```

Converting
----------

[](#converting)

Once you have parsed a docblock for its tokens, you may find the need to convert the list of tokens into another format. Before I cover the available converters, I need to show you how to create an instance of `Tokens` and `Sequence` which are consumed by the converters.

### Tokens and Sequence

[](#tokens-and-sequence)

Converters use either the `Tokens` or `Sequence` class when converting a list of tokens into an alternative format. The `Tokens` class acts like an array, but it will also validate the tokens as they are being used. The `Sequence`class is an extension of `Tokens`, but it also validates the order in which the tokens are used.

The converters only require that you use `Tokens`, but they are compatible with the `Sequence` class as well. The only time you may find need for the `Sequence` class is for debugging annotation issues, or if you are accepting tokens from anything besides the `Tokenizer` class.

Creating an instance of either class is very simple:

```
use Herrera\Annotations\Sequence;
use Herrera\Annotations\Tokens;

$tokens = new Tokens($parsed);
$sequence = new Sequence($parsed);
$sequence = new Sequence($tokens); // also accepts a Tokens object
```

### To Array

[](#to-array)

An instance of `ToArray` is used to convert tokens to a simple array.

```
use Herrera\Annotations\Convert\ToArray;

$toArray = new ToArray();

$array = $toArray->convert($tokens);
```

The value of `$array` is an array of objects. Each object represents a single annotation in the docblock. Each object will have two properties: `name` and `values`. Any values contained in `()` will be in `values`, including nested annotations.

The following example:

```
$array = $toArray->convert(
    new Tokens (
        $tokenizer->parse(
         'Annotation\\A',
        'values' => array(
            'Just a simple value.'
        )
    ),
    (object) array(
        'name' => 'Annotations\\B',
        'values' => array(
            'name' => 'SomeName',
            'nested' => (object) array(
                'name' => 'Annotation',
                'values' => array()
            ),
            array(
                'an array',
                array(
                    'within an array'
                )
            )
        )
    ),
);

echo $array[0]->name;  // "Annotation\A"
echo $array[0]->values[0]; // "Just a simple value."
echo $array[1]->values['nested']->name; // "Annotation"
```

### To String

[](#to-string)

An instance of `ToString` is used to convert tokens to their string representation.

```
use Herrera\Annotations\Convert\ToString;

$toString = new ToString();

$string = $toString->convert($tokens);
```

Using this example:

```
$string = $toString->convert(
    new Tokens(
        $tokenizer->parse(