crodas / notoj
Annotation parser. Uses reflection and provides cache out of the box.
Installs: 21 760
Dependents: 16
Suggesters: 0
Security: 0
Stars: 37
Watchers: 6
Forks: 5
Open Issues: 0
Requires
- php: >=5.3.0
- crodas/class-info: ^0.2
- crodas/file-util: ^0.2
- crodas/remember: >=0.4.2
- nikic/php-parser: ^2.0 | ^1.0
Requires (Dev)
- crodas/phpunit-compat: ^1.7
- dev-master
- v1.7.0
- v1.6.1
- v1.6.0
- v1.5.2
- v1.5.1
- v1.4.2
- v1.4.1
- v1.3.3
- v1.3.2
- v1.3.1
- v1.2.2
- v1.2.1
- v1.1.1
- v1.0.9
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- v1.0.0
- v0.2.0.x-dev
- v0.1.22
- v0.1.21
- v0.1.20
- v0.1.19
- v0.1.18
- v0.1.17
- v0.1.16
- v0.1.15
- v0.1.14
- v0.1.13
- v0.1.12
- v0.1.11
- v0.1.10
- v0.1.9
- v0.1.8
- v0.1.7
- v0.1.6
- v0.1.5
- v0.1.4
- v0.1.2
- v0.1.1
- v0.1.0
- dev-develop
- dev-php74-support
- dev-feature/better-cache
- dev-master-2-docs
- dev-feature/quick-annotation
- dev-feature/crodas/class-info
- dev-annotation-class-loader
This package is auto-updated.
Last update: 2024-10-15 16:32:00 UTC
README
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.
<?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 $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.
It provides ->get($tag)
and ->has($tag)
filters that helps processing the object.
<?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)
.
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.
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.
To enable this feature you need to specify which file should be used to save the cache, Notoj will do the rest :-).
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