larachimp / pine-annotations
Easing annotations reading in Laravel
Installs: 7 256
Dependents: 1
Suggesters: 0
Security: 0
Stars: 8
Watchers: 2
Forks: 4
Open Issues: 0
Requires
- php: ^7.3|^8.0
- doctrine/annotations: ^1.13
- doctrine/cache: ^2.1
- illuminate/support: ^8.0
- symfony/finder: ^5.0
Requires (Dev)
- mockery/mockery: ^1.4.2
- orchestra/testbench: ^6.0
- phpunit/phpunit: ^9.3.3
This package is auto-updated.
Last update: 2024-10-16 04:01:34 UTC
README
Pine Annotations
Introduction
Pine Annotations package makes creating and reading annotations seamlessly in any laravel 5 project. Behind the scenes Pine Annotations make use of the doctrine-annotations project, but tries to simplify its integration with Laravel 5.
License
Pine Annotations is open-sourced software licensed under the MIT license.
Version Compatibility
Installation
$ composer require larachimp/pine-annotations
Configuration
If you are using Laravel >= 5.5, you can skip service registration thanks to Laravel auto package discovery feature.
After installation all you need is to register the LaraChimp\PineAnnotations\PineAnnotationsServiceProvider
in your config/app.php
configuration file:
'providers' => [ ... LaraChimp\PineAnnotations\PineAnnotationsServiceProvider::class, ],
You can also register the Reader
alias which helps in reading object's annotations.
'aliases' => [ ... 'AnnotationsReader' => LaraChimp\PineAnnotations\Facades\Reader::class, ]
You can now publish config using the command:
$ php artisan vendor:publish
This will create the file pine-annotations.php
in your config directory.
Registering your annotations in the AnnotationRegistry
The config file pine-annotations.php
has two sections autoload_files
and autoload_namespaces
.
autoload_files
'autoload_files' => [ app_path('Annotations/FooAnnotation.php'), ],
In this array you may include the file paths of all your annotations classes. These will get registered in the AnnotationRegistry
. You
can include as many files as you need.
autoload_namespaces
'autoload_namespaces' => [ 'App\Annotations', ],
This array contains the namespaces of your annotations classes. This is useful if you want to register all annotations classes of a whole namespace in a single go.
Using the Reader to manually add entries to the Registry.
Alternatively you may use the methods addFilesToRegistry()
and addNamespacesToRegistry()
to perform manual entries of
files and namespaces to the annotation registry.
// Adding files manually to the Registry. AnnotationsReader::addFilesToRegistry($filesPaths);
// Adding namespaces manually to the Registry. AnnotationsReader::addNamespacesToRegistry($namespaces);
It is imperative that you register your annotations classes in one way or the other with the Reader. Otherwise AnnotationsReader won't be able to parse them.
The AnnotationsReader
To create an instance of the AnnotationsReader
, use the Laravel's IOC to either inject or create it via the
app()
method or App
facade:
<?php use LaraChimp\PineAnnotations\Support\Reader\AnnotationsReader; class MyService { /** * AnnotationsReader instance. * * @var AnnotationsReader */ protected $annotationsReader; /** * Constructor. * * @var AnnotationsReader $annotationsReader */ public function __construct(AnnotationsReader $annotationsReader) { $this->annotationsReader = $annotationsReader; } }
or:
$annotationsReader = app(\LaraChimp\PineAnnotations\Support\Reader\AnnotationsReader::class);
Alternatively can also use the AnnotationsReader
facade LaraChimp\PineAnnotations\Facades\Reader::class
for all
annotations reading.
Reading all annotations of a class
Consider the following class which is annotated with the FooAnnotation
:
<?php /** * Class Baz. * * @FooAnnotation(bar="Percy") */ class Baz { // }
To read this class' annotations, simply create an instance of the AnnotationsReader
with target as class :
// Read all class annotations on class. $annotations = AnnotationsReader::target('class')->read(Baz::class);
The AnnotationsReader
will return a Collection
of the class' annotations with their values filled in
the correct attributes :
Illuminate\Support\Collection { #items: array:1 [ 0 => FooAnnotation { +bar: "Percy" } ] }
Note that all annotations are cached by default for convinience. Hence the AnnotationsReader does not have to parse doc blocks each time it reads annotations from a target, which would be rather costly operation otherwise. The AnnotationsReader uses the default cache which you define in your Laravel App.
Reading a specific annotation of a class
Consider the following class which is annotated with the FooAnnotation
and FooDoubleAnnotation
:
<?php /** * Class Baz. * * @FooAnnotation(bar="Percy") * @FooDoubleAnnotation(bar="Mamedy") */ class Baz { // }
Now we may want to only parse or read the @FooDoubleAnnotation(bar="Mamedy")
doc block. To do so, we can use the only()
method on our AnnotationsReader
instance. The only()
method takes as a single argument the annotation's class name :
// Read specific class annotations on class. $annotations = AnnotationsReader::target('class')->only(FooDoubleAnnotation::class)->read(Baz::class);
This will return Collection
with the keys and values of the targetted annotation:
Illuminate\Support\Collection { #items: array:1 [ "bar" => "Mamedy" ] }
Reading all annotations of a property on a class
Consider the following class with the given annotations blocks on the name
property:
<?php class Baz { /** * Name. * * @PropertyAnnotation(bar="Jeffrey") * @PropertyDoubleAnnotation(bar="Way") * * @var string */ protected $name = ''; // }
To read the annotations of the name
property, we will use the target as property
and the property's name
on the AnnotationsReader
:
// Read all class annotations on property. $annotations = AnnotationsReader::target('property', 'name')->read(Baz::class);
The result is a Collection
with all Annotations objects and theirs properties values filled in :
Illuminate\Support\Collection { #items: array:2 [ 0 => PropertyAnnotation { +bar: "Jeffrey" } 1 => PropertyDoubleAnnotation { +bar: "Way" } ] }
Reading specific annotation of a property on a class
Consider the following class with the given annotations blocks on the name
property:
<?php class Baz { /** * Name. * * @PropertyAnnotation(bar="Jeffrey") * @PropertyDoubleAnnotation(bar="Way") * * @var string */ protected $name = ''; // }
Now we may want to only parse or read the @PropertyDoubleAnnotation(bar="Way")
doc block. To do so, we will use the target as property
together
with the property's name and the only()
method on our AnnotationsReader
instance. The only()
method takes as a single argument
the annotation's class name :
// Read all class annotations on property. $annotations = AnnotationsReader::target('property', 'name')->only(PropertyDoubleAnnotation::class) ->read(Baz::class);
This will return Collection
with the keys and values of the targetted annotation:
Illuminate\Support\Collection { #items: array:1 [ "bar" => "Way" ] }
Reading all annotations of a method on a class
Consider the following class with the given annotations blocks on the someMethod()
method :
<?php class Baz { /** * Some method that does somethin. * * @MethodAnnotation(bar="Way") * @MethodDoubleAnnotation(bar="Otwell") * * @return string */ public function someMethod() { return 'I did something.'; } }
To read all the annotations of the someMethod()
method, we will use target as method
and the method's name
on our AnnotationsReader
instance :
// Read all class annotations on property. $annotations = AnnotationsReader::target('method', 'someMethod')->read(Baz::class);
The result is a Collection
with all Annotations objects and theirs properties values filled in :
Illuminate\Support\Collection { #items: array:2 [ 0 => MethodAnnotation { +bar: "Way" } 1 => MethodDoubleAnnotation { +bar: "Otwell" } ] }
Reading a specific annotation of a method on a class
Consider the following class with the given annotations blocks on the someMethod()
method :
<?php class Baz { /** * Some method that does somethin. * * @MethodAnnotation(bar="Way") * @MethodDoubleAnnotation(bar="Otwell") * * @return string */ public function someMethod() { return 'I did something.'; } }
Now we may want to only parse or read the @MethodDoubleAnnotation(bar="Otwell")
doc block. To do so, we will use the target as method
together
with the method's name and the only()
method on our AnnotationsReader
instance. The only()
method takes as a single argument
the annotation's class name :
// Read all class annotations on property. $annotations = AnnotationsReader::target('method', 'someMethod')->only(MethodDoubleAnnotation::class) ->read(Baz::class);
This will return Collection
with the keys and values of the targetted annotation:
Illuminate\Support\Collection { #items: array:1 [ "bar" => "Otwell" ] }
Credits
Big Thanks to all developers who worked hard to create something amazing!
Creator
Twitter: @PercyMamedy
GitHub: percymamedy