Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/LaravelCollective/annotations
Route and Event Annotations for the Laravel Framework
https://github.com/LaravelCollective/annotations
Last synced: 13 days ago
JSON representation
Route and Event Annotations for the Laravel Framework
- Host: GitHub
- URL: https://github.com/LaravelCollective/annotations
- Owner: LaravelCollective
- License: mit
- Created: 2015-02-04T20:29:28.000Z (almost 10 years ago)
- Default Branch: 6.0
- Last Pushed: 2023-04-25T02:43:33.000Z (over 1 year ago)
- Last Synced: 2024-04-04T07:46:33.919Z (8 months ago)
- Language: PHP
- Size: 173 KB
- Stars: 365
- Watchers: 18
- Forks: 74
- Open Issues: 14
-
Metadata Files:
- Readme: readme.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.txt
Awesome Lists containing this project
README
## Annotations for The Laravel Framework
[](https://travis-ci.org/LaravelCollective/annotations)
[](https://packagist.org/packages/laravelcollective/annotations)
[](https://packagist.org/packages/laravelcollective/annotations)
[](https://packagist.org/packages/laravelcollective/annotations)
[](https://packagist.org/packages/laravelcollective/annotations)
# Annotations
- [Installation](#installation)
- [Scanning](#scanning)
- [Event Annotations](#events)
- [Route Annotations](#routes)
- [Scanning Controllers](#controllers)
- [Model Annotations](#models)
- [Custom Annotations](#custom-annotations)
> 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`.
```php
[
// ...
App\Providers\AnnotationsServiceProvider::class
// ...
];
```
This doesn't replace the `RouteServiceProvider`, this is still required as this handles loading of the route cache etc.
Add event handler classes to the `protected $scanEvents` array to scan for event annotations.
```php
/**
* The classes to scan for event annotations.
*
* @var array
*/
protected $scanEvents = [
App\Handlers\Events\MailHandler::class,
];
```
Add controllers to the `protected $scanRoutes` array to scan for route annotations.
```php
/**
* The classes to scan for route annotations.
*
* @var array
*/
protected $scanRoutes = [
App\Http\Controllers\HomeController::class,
];
```
Add models to the `protected $scanModels` array to scan for model annotations.
```php
/**
* The classes to scan for model annotations.
*
* @var array
*/
protected $scanModels = [
'App\User',
];
```
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`.
### @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.
```php
## 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.
```php
auth->logout();
return redirect( route('login') );
}
}
```
### @Resource
Using the `@Resource` annotation on a controller allows you to easily set up a Resource Controller.
```php
## 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.
```php
$scanControllers = true;
```
### 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`:
```php
public function routeScans() {
$classes = parent::routeScans();
if ( $this->app->environment('local') ) {
$classes = array_merge($classes, [App\Http\Controllers\LocalOnlyController::class]);
}
return $classes;
}
```
#### 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.
```php
public function routeScans() {
$classes = parent::routeScans();
if ( $this->app->environment('local') ) {
$classes = array_merge(
$classes,
$this->getClassesFromNamespace( App\Http\Controllers\Local::class )
);
}
return $classes;
}
```
You can use annotations to automatically bind your models to route parameters, using [Route Model Binding](http://laravel.com/docs/5.8/routing#route-model-binding). To do this, use the `@Bind` annotation.
```php
/**
* @Bind("users")
*/
class User extends Eloquent {
//
}
```
This is the equivalent of calling `Route::model('users', 'App\Users')`.
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:
```php
addAnnotationNamespace( 'App\Http\Annotations' );
}
```
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`:
```php
hasPaths())
{
foreach ($endpoint->getPaths() as $path)
{
$path->middleware = array_merge($path->middleware, (array) 'auth');
}
}
else
{
$endpoint->middleware = array_merge($endpoint->middleware, (array) 'auth');
}
}
}
```