Laravel Middleware Annotations

Documantation

• Installation
• Usage
• Middleware Annotations
• Integration With Laratrust
• Future Features

Installation

Via Composer

$ composer require m3assy/laravelannotation

If you are developing your application using Laravel 5.5+, the service providers and facades are registered automatically. If you are using lower versions add those lines to config/app.php

'providers' => [
    // Service Providers
    M3assy\LaravelAnnotations\LaravelAnnotationServiceProvider::class,
],
'aliases' => [
    // Facade Aliases
    'Annotation' => M3assy\LaravelAnnotations\Facades\Annotation::class,
],

Usage

Now, You don't need to add any trait, the package register a custom controller dispatcher which register middlewares under the hood

Example:

<?php

namespace App\Http\Controllers\Modules;

use App\Http\Controllers\Controller;

/**
 * Example For Middleware Class Annotation
 * @Auth
 */
class UserController extends Controller
{
    /**
     * Example For Middleware Method Annotation
     * @Auth
     * @ExampleAnnotationWithParameter("values") 
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        return response();
    }
}

This package built-in auth middleware annotation so all what you need is to use annotation like so: If you need to apply middleware over all controller then add you doc block over controller class, and if you need to specify a controller method with middleware then you can add your annotation above the method in its DocBlock.

if you have a middleware with parameters, so you can use the annotation with parentheses and the values syntax.

Creating Middleware Annotation is pretty easy, all what you need is to call our artisan make:annotation command like so:

  $ php artisan make:annotation Guest

This will generate a file like the following:

<?php

namespace App\Foundation\Annotations;

use M3assy\LaravelAnnotations\Foundation\Types\MiddlewareAnnotation;

/**
 * @Annotation
 */
class Guest extends MiddlewareAnnotation
{

}

If you have middleware parameters that required kind of validation then you can override the following method:

<?php

namespace App\Foundation\Annotations;

use M3assy\LaravelAnnotations\Foundation\Types\MiddlewareAnnotation;

/**
 * @Annotation
 */
class Guest extends MiddlewareAnnotation
{
    /**
    * @return bool
    */
    public function validateGivenValue()
    {
        // Your Validation Logic Goes Here
    }
}

Notice: If the given value is invalid the engine will neglect this annotation.

You can also access internal controller properties and methods dynamically like so:

<?php

namespace App\Http\Controllers\Modules;

use App\Http\Controllers\Controller;

/**
 * Example For Middleware Class Annotation
 * @Auth
 */
class UserController extends Controller
{
    public $value;
    /**
     * Example For Middleware Method Annotation
     * @Auth
     * @ExampleAnnotationWithParameter("{$this->value}") 
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        return response();
    }
}

Laratrust Integration

This package is delivered with Implementation For Laratrust ACL Annotations System.

To start using roles and permissions all what you need is to use the magic annotations in your controllers like so:

<?php

namespace App\Http\Controllers\Modules;

use App\Http\Controllers\Controller;

/**
 * @Role("superadmin")
 */
class UserController extends Controller
{
    /**
     * @Permission("list-users|create-users") 
     * @return \Illuminate\Http\Response
     */
    public function index()
    {
        return response();
    }
}

Feel free to use Role and Permission annotations on the class level and methods level like previous instructions.

Scanning New Roles And Permissions

If you have used any role or permission in its annotation and it does not exist in the acl tables and you need to add them, no need to use any ui or tinker or any type code. Just use our artisan scan:acl Command and it will identify automatically what is new in your roles and permissions and detects its type and create new instance for it. To start scan fire your command like following:

  $ php artisan scan:acl

and voila!, We finished :)

If you refreshed any route to a controller contains non-existing role or permission, you will find that it is created and applied.

Future Features

• Implement middleware options.
• Implement Laratrust Teams Feature Annotation.
• Adding more built-in laravel middlewares.
• Implementing magic middleware features for developers to use.

Contributing

Please see contributing.md for details and a todolist.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Mohamed Mostafa
• All Contributors

License

MIT. Please see the license file for more information.