Getting Started

Minimal Setup

Installation:
```
composer require spatie/laravel-authorize
```
No additional configuration is required—it leverages Laravel’s built-in can() authorization.
First Use Case: Protect a route by adding the middleware to its definition:
```
Route::get('/admin/dashboard', [
    'middleware' => 'can:access-admin-dashboard',
    'uses' => 'AdminController@dashboard',
]);
```
Ensure your User model (or relevant model) implements Laravel’s Authorizable contract (e.g., via Spatie\Permission\Traits\HasRoles).

Define Policies: Create a policy for the model/resource you’re protecting (e.g., app/Policies/PostPolicy.php):

use Illuminate\Auth\Access\HandlesAuthorization;

class PostPolicy
{
    use HandlesAuthorization;

    public function viewTopSecretPage(User $user)
    {
        return $user->isAdmin(); // Custom logic
    }
}

protected $policies = [
    Post::class => PostPolicy::class,
];

Test Authorization: Use Tinker or tests to verify:

php artisan tinker
>>> $user = App\Models\User::first();
>>> $user->can('access-admin-dashboard'); // Returns bool

Implementation Patterns

Core Workflows

Route-Level Protection:
- Apply middleware directly in route definitions (as shown above).
- Useful for high-level access control (e.g., admin-only routes).

Controller-Level Checks:

Use the authorize() helper or can() method in controllers:

public function edit(Post $post)
{
    $this->authorize('update', $post); // Policy-based
    // OR
    if (!auth()->user()->can('edit-post')) {
        abort(403);
    }
}

Combine with Gate definitions for dynamic checks:

Gate::define('edit-post', function (User $user, Post $post) {
    return $user->id === $post->user_id;
});

Policy Composition:

Reuse policies across controllers/models. Example:

// PostPolicy.php
public function delete(User $user, Post $post)
{
    return $user->isSuperAdmin() || $post->user_id === $user->id;
}

Call in controllers:
```
$this->authorize('delete', $post);
```

Middleware Groups:

Group middleware for role-based access:

Route::middleware(['can:manage-users'])->group(function () {
    Route::resource('users', UserController::class);
});

API Resource Protection:

Protect API endpoints with can middleware:

Route::get('/api/posts/{post}', function (Post $post) {
    return $this->authorize('view', $post) ? $post : abort(403);
})->middleware('can:view-post');

Integration Tips

Laravel Mix: Use the middleware in frontend routes (e.g., Vue/React) by checking auth state via API.

Blade Templates: Conditionally render UI based on authorization:

@can('access-admin-dashboard')
    <a href="/admin">Admin Panel</a>
@endcan

Event Listeners: Trigger actions post-authorization (e.g., log access):

Event::listen('authorized:can:viewTopSecretPage', function ($user) {
    Log::info("User {$user->id} accessed top-secret page.");
});

Gotchas and Tips

Pitfalls

Policy Registration:
- Issue: Forgetting to register policies in AuthServiceProvider causes Gate not defined errors.
- Fix: Always declare policies in $policies array or use Gate::define() for ad-hoc rules.
Middleware Caching:
- Issue: Middleware may not update if cached (e.g., php artisan optimize). Clear cache after policy changes:
```
php artisan cache:clear
php artisan route:clear
```
Model Binding Conflicts:
- Issue: Route model binding (e.g., {post}) may interfere with policy resolution if the model lacks a resolveRouteBinding method.
- Fix: Ensure models are properly bound or use explicit IDs:
```
Route::get('/posts/{post}', function (Post $post) {
    $this->authorize('view', $post);
})->middleware('can:view-post,{post}'); // Pass model via middleware params
```
Permission Logic Errors:
- Issue: Overly complex policy logic (e.g., nested conditions) can lead to hard-to-debug authorization failures.
- Tip: Break down policies into smaller methods or use traits for shared logic.
Deprecated Laravel Features:
- Issue: The package relies on Laravel 5.1+ authorization. Upgrading Laravel may require adjustments (e.g., Gate vs. Policy changes).
- Tip: Test thoroughly after major Laravel updates.

Debugging

Enable Debugging: Set APP_DEBUG=true in .env to see authorization failure messages (e.g., User does not have permission to perform action).

Log Authorization Attempts: Use Laravel’s authorizing event:

Event::listen('authorizing', function ($user, $ability) {
    Log::debug("Authorization check for {$ability} by user {$user->id}");
});

Test Policies: Write unit tests for policies:

public function test_user_can_access_admin_dashboard()
{
    $user = User::factory()->admin()->create();
    $this->assertTrue($user->can('access-admin-dashboard'));
}

Extension Points

Custom Middleware Parameters: Extend the middleware to accept additional parameters:

// app/Http/Middleware/AuthorizeWithParams.php
public function handle($request, Closure $next, $ability, $model = null)
{
    if (!$request->user()->can($ability, $model)) {
        abort(403);
    }
    return $next($request);
}

'can.param' => \App\Http\Middleware\AuthorizeWithParams::class,

Use in routes:

Route::get('/posts/{post}', [
    'middleware' => ['can.param:view-post,{post}'],
    'uses' => 'PostController@show',
]);

Policy Caching: Cache policy results for performance (e.g., using Spatie\CacheablePolicy):

use Spatie\CacheablePolicy\CacheablePolicy;

class PostPolicy
{
    use CacheablePolicy;

    public function view(User $user, Post $post)
    {
        return $user->isAdmin();
    }
}

Role-Based Middleware: Create a role-specific middleware:

// app/Http/Middleware/RoleMiddleware.php
public function handle($request, Closure $next, $role)
{
    if (!auth()->user()->hasRole($role)) {
        abort(403);
    }
    return $next($request);
}

Use with spatie/laravel-permission:

Route::middleware(['role:admin'])->group(...);

Fallback Policies: Define fallback policies for unregistered gates:

Gate::before(function (User $user) {
    if ($user->isSuperAdmin()) {
        return true; // Allow all actions
    }
});

Laravel Authorize Laravel Package