The example of annotation usage shown in the previous Behat example is rather interesting, as it places the annotation inside the DocBlock. The DocBlock begins with a forward slash and two asterisks:
/**
It contains n lines beginning with an asterisk.
The DocBlock ends with a single asterisk and forward slash:
*/
This syntax tells the parser that something useful is inside the DocBlock in addition to the normal comments.
When Laravel 5 was being developed, support for routing and event listeners via DocBlock annotations was originally added. Its syntax was similar to Symfony and Zend.
The syntax for Symfony is as follows:
/**
* @Route("/accommodations/search")
* @Method({"GET"})
*/
public function searchAction($id)
{The syntax for Zend is as follows:
/**
* @Route(route="/accommodations/search")
*/
public function searchAction()
{The syntax for Laravel is as follows:
/**
* @Get("/hotels/search")
*/
public function search()
{What type of problem does the DocBlock annotation try to solve though?
One use of doc-annotations would be to add them to controllers, thus moving the control of the routing and middleware to the controller. This would make the controller more portable and even framework-agnostic, since the routes.php file would play a lesser role, if not be totally absent. As shown in the following example, the routes.php file can grow quite large, and this would lead to complexity and even cause the file to be unmanageable:
Route::patch('hotel/{hid}/room/{rid}','AccommodationsController@editRoom'),
Route::post('hotel/{hid}/room/{rid}','AccommodationsController@reserve'),
Route::get('hotel/stats,HotelController@Stats'),
Route::resource('country', 'CountryController'),
Route::resource(city', 'CityController'),
Route::resource('state', 'StateController'),
Route::resource('amenity', 'AmenitiyController'),
Route::resource('country', 'CountryController'),
Route::resource(city', 'CityController'),
Route::resource('country', 'CountryController'),
Route::resource('city', 'CityController'),
Route::resource('horse', 'HorseController'),
Route::resource('cow', 'CowController'),
Route::resource('zebra', 'ZebraController'),
Route::get('dragon/{id}', 'DragonController@show'),
Route::resource('giraffe', 'GiraffeController'),
Route::resource('zebrafish', 'ZebrafishController'),The idea of DocBlock annotations would be to tame this complexity, as the routing would be moved to the controllers.
Shortly before the release of Laravel 5.0, due to community disapproval, the feature was removed. Also, since some developers may not want to use this approach, it would be proper to move this package from the core of Laravel and into a package. The method to install the package is similar to the way in which the HTML package was added. This package is also supported by the Laravel Collective. It is easy to add annotations by typing the following composer command:
$ composer require laravelcollective/annotations
This will install the annotations package, while composer.json will show the package added in the require section, as follows:
"require": {
"laravel/framework": "5.0.*",
"laravelcollective/annotations": "~5.0",
},The next step would be to create a file named AnnotationsServiceProvider.php and add the following code:
<?php namespace AppProviders;
use CollectiveAnnotationsAnnotationsServiceProvider as ServiceProvider;
class AnnotationsServiceProvider extends ServiceProvider {
/**
* The classes to scan for event annotations.
*
* @var array
*/
protected $scanEvents = [];
/**
* The classes to scan for route annotations.
*
* @var array
*/
protected $scanRoutes = [];
/**
* The classes to scan for model annotations.
*
* @var array
*/
protected $scanModels = [];
/**
* Determines if we will auto-scan in the local environment.
*
* @var bool
*/
protected $scanWhenLocal = false;
/**
* Determines whether or not to automatically scan the controllers
* directory (AppHttpControllers) for routes
*
* @var bool
*/
protected $scanControllers = false;
/**
* Determines whether or not to automatically scan all namespaced
* classes for event, route, and model annotations.
*
* @var bool
*/
protected $scanEverything = false;
}Next, the AnnotationsServiceProvider.php file will need to be added to the config/app.php file. The class, which needs to be added with the namespace, should be added to the providers array as follows:
'providers' => [
// ...
'AppProvidersAnnotationsServiceProvider'
];