Download the PHP package laravelcollective/annotations without Composer

Annotations for The Laravel Framework

Annotations

• Installation
• Scanning
• Event Annotations
• Route Annotations
• Scanning Controllers
• Model Annotations
• Custom Annotations

Installation

If you have changed the top-level namespace to something like 'MyCompany', then you would use the new namespace instead of 'App'.

Begin by installing this package through Composer. Edit your project's composer.json file to require laravelcollective/annotations.

"require": {
    "laravelcollective/annotations": "6.0.\*"
}

Next, update Composer from the Terminal:

composer update

Once composer is done, you'll need to create a Service Provider in app/Providers/AnnotationsServiceProvider.php.

Finally, add your new provider to the providers array of config/app.php:

This doesn't replace the RouteServiceProvider, this is still required as this handles loading of the route cache etc.

Setting up Scanning

Add event handler classes to the protected $scanEvents array to scan for event annotations.

Add controllers to the protected $scanRoutes array to scan for route annotations.

Add models to the protected $scanModels array to scan for model annotations.

Alternatively, you can set protected $scanEverything to true to automatically scan all classes within your application's namespace. Note: This may increase the time required to execute the scanners, depending on the size of your application.

Scanning your event handlers, controllers, and models can be done manually by using php artisan event:scan, php artisan route:scan, or php artisan model:scan respectively. In the local environment, you can scan them automatically by setting protected $scanWhenLocal = true.

Event Annotations

@Hears

The @Hears annotation registers an event listener for a particular event. Annotating any method with @Hears("SomeEventName") will register an event listener that will call that method when the SomeEventName event is fired.

Route Annotations

Route annotations can be incredibly powerful, however the order of your route definitions can impact how your application matches specific routes, specifically any wildcard routes. If protected $scanEverything is set to true, you will have no control over the order of your route definitions.

@Get

The @Get annotation registeres a route for an HTTP GET request.

You can also set up route names.

... or middlewares.

... or both.

Here's an example that uses all of the available parameters for a @Get annotation:

no_prefix allows any prefix added to the routes in that controller be ignored for this particular route.

@Post, @Options, @Put, @Patch, @Delete, @any

The @Post, @Options, @Put, @Patch, @Delete, and @Any annotations have the exact same syntax as the @Get annotation, except it will register a route for the respective HTTP verb, as opposed to the GET verb.

@Middleware

As well as defining middleware inline in the route definition tags (@Get, @Post, etc.), the @Middleware tag can be used on its own. It works both individual methods:

Or on a whole controller, with the same only/exclude filter syntax that you can use elsewhere in laravel:

@Resource

Using the @Resource annotation on a controller allows you to easily set up a Resource Controller.

You can specify the only and except arguments, just like you can with the regular Route::resource() command.

You can also specify the route names of each resource method.

@Controller

Using the @Controller annotation on a controller allows you to set various options for the routes contained in it:

Scan the Controllers Directory

To recursively scan the entire controllers namespace ( App\Http\Controllers ), you can set the $scanControllers flag to true.

It will automatically adjust App to your app's namespace.

Advanced

If you want to use any logic to add classes to the list to scan, you can override the routeScans() or eventScans() methods.

The following is an example of adding a controller to the scan list if the current environment is local:

Scanning Namespaces

You can use the getClassesFromNamespace( $namespace ) method to recursively add namespaces to the list. This will scan the given namespace. It only works for classes in the app directory, and relies on the PSR-4 namespacing standard.

This is what the $scanControllers flag uses with the controllers directory.

Here is an example that builds on the last one - adding a whole local-only namespace.

Model Annotations

You can use annotations to automatically bind your models to route parameters, using Route Model Binding. To do this, use the @Bind annotation.

This is the equivalent of calling Route::model('users', 'App\Users').

Custom Annotations

If you want to register your own annotations, create a namespace containing subclasses of Collective\Annotations\Routing\Annotations\Annotations\Annotation - let's say App\Http\Annotations.

Then, in your annotations service provider, override the addRoutingAnnotations( RouteScanner $scanner ) method, and register your routing annotations namespace:

Your annotation classes must must have the @Annotation class annotation (see the following example).

There is an equivalent method for event annotations: addEventAnnotations( EventScanner $scanner ).

Custom Annotation Example

Here is an example to make an @Auth annotation. It provides the same functionality as using the annotation @Middleware("auth").

In a namespace - in this example, App\Annotations: