annotations

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.

 [
    // ...
    App\Providers\AnnotationsServiceProvider::class
    // ...
  ];

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.

    /**
     * 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.

    /**
     * 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.

    /**
     * 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.

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.

auth->logout();

    return redirect( route('login') );
  }

}

@Resource

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

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.

public function routeScans() {
    $classes = parent::routeScans();

    if ( $this->app->environment('local') ) {
        $classes = array_merge(
            $classes,
            $this->getClassesFromNamespace( App\Http\Controllers\Local::class )
        );
    }

    return $classes;
}

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.

/**
 * @Bind("users")
 */
class User extends Eloquent {
  //
}

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:

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:

hasPaths())
    {
      foreach ($endpoint->getPaths() as $path)
      {
        $path->middleware = array_merge($path->middleware, (array) 'auth');
      }
    }
    else
    {
      $endpoint->middleware = array_merge($endpoint->middleware, (array) 'auth');
    }
  }

}