crodas/notoj

Annotation parser. Uses reflection and provides cache out of the box.

Thursday, March 22, 2018
by crodas
Repository
5 Watchers
38 Stars
15,431 Installations

PHP
19 Dependents
0 Suggesters
4 Forks
0 Open issues
52 Versions
9 % Grown

The README.md

Notoj

Yet another annotation parser (DocBlocks). It's designed to be simple and intuitive. It extends the Reflection methods inside the Notoj namespace (ReflectionClass, RefletionProperties, ReflectionMethod so far), and adds the getAnnotations() method., _(*1)

<?php
use Notoj\ReflectionClass;

/** @foo @bar */
class Foo {
}

$reflection = new ReflectionClass('Foo');
var_dump($reflection->getAnnotations());
 ```

The `getAnnotations()` returns an array, with a very simple array structure (`array("method" => "Foo", "args" 
=> NULL)`)

How to use it
-------------

Notoj supports works under two scenearios, `offline` and `online` parsing.

### Online

Online parsing means that you want to retrieve annotations from an object, class or function that exists at run time. To use you'd need to use Reflection classes from the Notoj namespace.

### Offline

Offline parsing means that you want to get annotations from a file or directory and you rather not include them to use the `online` API. Notoj provides the `Notoj\File` and `\Notoj\Dir` classes to do that. They both return `Annotations` object which behaves as an array of `Annotation` (the output the `online` API), plus with a few extra things such as the `file`, `line`.


#### File
```php
<?php
$parser = new \Notoj\File("/foo.php");
$parser->getAnnotations();

Dir

<?php
$parser = new \Notoj\Dir("/foo"); // The parser is recursive
$parser->setFilter(function($file) {
 return true;
});
$annotations = $parser->getAnnotations();
foreach ($annotations->get('Foo\Bar') as $annotations) {
   foreach ($annotations as $annotation) {
      var_dump(
          "found @Foo\Bar at " . $annotation['file'] 
          . ($annotation->isClass() ? ' on a class ' : ' on something else other than a class')
      );
   }
}

Annotation object

It is the output object that represents an annotation. It is important that you notice that it does represents the annotations in a object, class or function and not a single annotation., _(*2)

It provides ->get($tag) and ->has($tag) filters that helps processing the object., _(*3)

<?php
// check if there is a @Foo
if (!$annotation->has('Foo')) {
  throw new \RuntimeException("We were expecting a Foo annotation tag");
}

// ensure that *every* @Foo has at least some argument
foreach ($annotation->get('Foo') as $ann) {
   if (empty($ann['args'])) {
      throw new \RuntimeException("we were expecting arguments");
   }
}

foreach ($annotation as $ann) {
    // get *All* iterations
}

Annotations object

It is an object that behaves like an array of Annotation object. Provides a very simple filter ->get($name) and ->has($name)., _(*4)

Format

<?php
/** @Foo */
/** @Foo("some") */
/** @Foo some other strings */
/** @Foo(some_label="something here") */
/** @Foo({some: "array here", arr:[1,2,3]}) */
/** @Foo(some_label={some: "array here", arr:[1,2,3]}) */

Warning: Notoj will do its best effort to parse broken annotations, but if there is an error it will fail silently. Also, in the @foo bar foobar format whitespaces are ignored., _(*5)

Caching support

Notoj supports caching that will help the Notoj's engine to avoid parsing over and over the same string. The cache will be invalidated automatically., _(*6)

To enable this feature you need to specify which file should be used to save the cache, Notoj will do the rest :-)., _(*7)

Notoj::enableCache("/tmp/annotations.php");

Todo

Cache for offline parsing

Feel free to email fork and submit pull requests or write me crodas@php.net, _(*8)

The Versions

22/03 2018

dev-develop

Annotation parser. Uses reflection and provides cache out of the box.

library notoj

Annotation parser. Uses reflection and provides cache out of the box.

crodas/notoj

The README.md

Notoj

Dir

Annotation object

Annotations object

Format

Caching support

Todo

The Versions

dev-develop

The Requires

The Development Requires

by César D. Rodas

dev-master

The Requires

The Development Requires

by César D. Rodas

v1.6.1

The Requires

The Development Requires

by César D. Rodas

v1.6.0

The Requires

The Development Requires

by César D. Rodas

v1.5.2

The Requires

by César D. Rodas

v1.5.1

The Requires

by César D. Rodas

v1.4.2

The Requires

The Development Requires

by César D. Rodas

v1.4.1

The Requires

The Development Requires

by César D. Rodas

dev-feature/better-cache

The Requires

The Development Requires

by César D. Rodas

v1.3.3

The Requires

by César D. Rodas

v1.3.2

The Requires

by César D. Rodas

v1.3.1

The Requires

by César D. Rodas

v1.2.2

The Requires

by César D. Rodas

v1.2.1

The Requires

by César D. Rodas

v1.1.1

The Requires

by César D. Rodas

v1.0.9

The Requires

by César D. Rodas

v1.0.8

The Requires

by César D. Rodas

v1.0.7

The Requires

by César D. Rodas

v1.0.6

The Requires

by César D. Rodas

v1.0.5

The Requires

by César D. Rodas

v1.0.4