授權（Gate 與 Policy） - Knowledge of Laravel

認證與授權的差異

認證（Authentication） 用來確認使用者「是誰」，登入處理就是代表性例子。 授權（Authorization） 用來判斷該使用者「能做什麼」。例如：只能編輯自己的貼文、只有管理員能修改設定等控制。在認證實作完登入功能後，下一步就是授權。

Laravel 的授權功能提供 Gates 與 Policies 兩種方式。使用哪一種取決於實際情境。

選用的判斷基準

情境	建議
不綁定特定模型的簡易判斷	Gate
針對模型的 CRUD 操作權限管理	Policy
管理員儀表板的存取控制	Gate
部落格文章的建立、編輯、刪除權限	Policy

Gate

Gate 是以 Closure 為基礎、簡單的授權檢查。適合用在不綁定特定模型的權限判定。

透過 Gate 的授權流程

定義 Gate

Gate 於 App\Providers\AppServiceProvider 的 boot 方法中使用 Gate::define() 定義。

// app/Providers/AppServiceProvider.php

use App\Models\Post;
use App\Models\User;
use Illuminate\Support\Facades\Gate;

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

Gate 的 Closure 第 1 個參數固定為目前已認證的使用者。第 2 個之後的參數可以傳入對應的模型等額外資訊。

用 Gate 檢查權限

在 Controller 中使用 Gate 檢查權限，可使用 Gate::allows() 或 Gate::denies()。

use Illuminate\Support\Facades\Gate;

public function update(Request $request, Post $post): RedirectResponse
{
    if (! Gate::allows('update-post', $post)) {
        abort(403);
    }

    // 更新貼文的處理...

    return redirect('/posts');
}

用 Gate::authorize() 拋出例外

若希望在無權限時自動回傳 403，可使用 Gate::authorize()，可省下寫 abort(403) 的功夫。

public function update(Request $request, Post $post): RedirectResponse
{
    Gate::authorize('update-post', $post);

    // 有權限才會抵達此處
    // 更新貼文的處理...

    return redirect('/posts');
}

Gate::authorize() 於無權限時會拋出 Illuminate\Auth\Access\AuthorizationException。Laravel 會自動將其轉為 403 HTTP 回應。

管理員繞過（before 方法）

若想賦予管理員所有權限，可使用 Gate::before()。

use App\Models\User;
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    // $ability 會是即將執行的 Gate 名稱（例如 'update-post'）
    Gate::before(function (User $user, string $ability) {
        if ($user->isAdministrator()) {
            return true;
        }
    });

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

當 before Closure 回傳非 null 的值時，該結果即為最終權限判定。若回傳 null 或不回傳任何值，則進入一般的 Gate 判定。

Blade 模板中的 @can / @cannot

在模板中使用 Gate 判定時，可用 @can 與 @cannot 指令。

@can('update-post', $post)
    <a href="{{ route('posts.edit', $post) }}">編輯</a>
@endcan

@cannot('update-post', $post)
    <p>你沒有編輯此貼文的權限。</p>
@endcannot

Policy

Policy 是把與特定模型相關的授權邏輯整理成類別。對 Post 模型的建立、瀏覽、編輯、刪除權限管理，Policy 比 Gate 更合適。

透過 Policy 的授權流程

產生 Policy

使用 make:policy Artisan 指令產生 Policy 類別。

php artisan make:policy PostPolicy

若要產生包含對應模型所有 CRUD 方法的骨架，使用 --model 選項。

php artisan make:policy PostPolicy --model=Post

會產生 app/Policies/PostPolicy.php。

模型與 Policy 的自動探索

Laravel 預設會依命名慣例自動發現 Policy。

模型：app/Models/Post.php
Policy：app/Policies/PostPolicy.php

遵循此命名慣例的話，就不需要註冊 Policy。

若不遵循命名慣例或想手動註冊，可在 AppServiceProvider 的 boot 方法中使用 Gate::policy()。

use App\Models\Post;
use App\Policies\PostPolicy;
use Illuminate\Support\Facades\Gate;

Gate::policy(Post::class, PostPolicy::class);

在 Laravel 13 中，也可在模型上加上 #[UsePolicy] 屬性以宣告式方式註冊。

use App\Policies\PostPolicy;
use Illuminate\Database\Eloquent\Attributes\UsePolicy;

#[UsePolicy(PostPolicy::class)]
class Post extends Model {}

實作 Policy 方法

使用 --model 選項產生的 Policy 已包含對應標準 CRUD 動作的方法。

<?php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    /**
     * 是否可瀏覽貼文列表
     */
    public function viewAny(User $user): bool
    {
        return true; // 已認證使用者皆可瀏覽
    }

    /**
     * 是否可瀏覽特定貼文
     */
    public function view(User $user, Post $post): bool
    {
        return true; // 已認證使用者皆可瀏覽
    }

    /**
     * 是否可建立貼文
     */
    public function create(User $user): bool
    {
        return true; // 已認證使用者皆可發文
    }

    /**
     * 是否可更新貼文
     */
    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id; // 僅可編輯自己的貼文
    }

    /**
     * 是否可刪除貼文
     */
    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id; // 僅可刪除自己的貼文
    }
}

管理員繞過（before 方法）

在 Policy 內也可定義 before 方法，賦予管理員所有權限。

/**
 * 會先於其他 Policy 方法執行的預先檢查
 * $ability 會是 Policy 方法名稱（如 'update'、'delete'）
 */
public function before(User $user, string $ability): bool|null
{
    if ($user->isAdministrator()) {
        return true; // 管理員允許所有操作
    }

    return null; // 回傳 null 時進入一般的 Policy 方法
}

before 方法只有在 Policy 類別上存在對應方法時才會被呼叫。例如若不存在 update 方法，before 也不會被呼叫。

before Callback 的執行順序

在 Controller 中使用 Policy

authorize() 方法

Laravel 的 Controller 具備 authorize() 輔助方法（若不使用 base Controller，則改用 Gate::authorize()）。

Gate::authorize()
User::can() / cannot()

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;

class PostController extends Controller
{
    public function update(Request $request, Post $post): RedirectResponse
    {
        Gate::authorize('update', $post);

        // 更新貼文的處理...

        return redirect()->route('posts.index');
    }

    public function store(Request $request): RedirectResponse
    {
        Gate::authorize('create', Post::class);

        // 建立貼文的處理...

        return redirect()->route('posts.index');
    }

    public function destroy(Post $post): RedirectResponse
    {
        Gate::authorize('delete', $post);

        $post->delete();

        return redirect()->route('posts.index');
    }
}

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class PostController extends Controller
{
    public function update(Request $request, Post $post): RedirectResponse
    {
        if ($request->user()->cannot('update', $post)) {
            abort(403);
        }

        // 更新貼文的處理...

        return redirect()->route('posts.index');
    }
}

用 authorizeResource() 一次註冊 RESTful Policy

在建構子中呼叫 authorizeResource()，會自動將 Controller 各動作對應到 Policy 方法。

<?php

namespace App\Http\Controllers;

use App\Models\Post;

class PostController extends Controller
{
    public function __construct()
    {
        $this->authorizeResource(Post::class, 'post');
    }

    // index(), show(), create(), store(), edit(), update(), destroy() 對應的
    // Policy 方法會自動套用
}

Controller 動作與 Policy 方法的對應關係：

Controller 動作	Policy 方法
`index`	`viewAny`
`show`	`view`
`create` / `store`	`create`
`edit` / `update`	`update`
`destroy`	`delete`

使用 authorizeResource() 後，就不需要在每個動作分別呼叫 authorize()。與 RESTful Resource Controller 搭配特別方便。

在 Middleware 中授權

要在路由層級進行授權檢查，可使用 can middleware。

use App\Models\Post;

// 只有具備更新貼文權限的使用者可存取
Route::put('/posts/{post}', [PostController::class, 'update'])
    ->middleware('can:update,post');

// 只有具備建立貼文權限的使用者可存取
Route::post('/posts', [PostController::class, 'store'])
    ->middleware('can:create,App\Models\Post');

使用 can 方法的更簡潔寫法：

Route::put('/posts/{post}', [PostController::class, 'update'])
    ->can('update', 'post');

在 Blade 模板使用 Policy

註冊 Policy 後，Blade 的 @can / @cannot 指令也會自動使用 Policy。

{{-- 只對有權限的使用者顯示編輯按鈕 --}}
@can('update', $post)
    <a href="{{ route('posts.edit', $post) }}" class="btn">編輯</a>
@endcan

{{-- 刪除按鈕也一樣 --}}
@can('delete', $post)
    <form method="POST" action="{{ route('posts.destroy', $post) }}">
        @csrf
        @method('DELETE')
        <button type="submit">刪除</button>
    </form>
@endcan

{{-- 新增貼文按鈕 --}}
@can('create', App\Models\Post::class)
    <a href="{{ route('posts.create') }}">新增貼文</a>
@endcan

實務範例：部落格文章的權限管理

在部落格應用中實作「只有作者能編輯或刪除自己的文章」權限的範例。

產生 Policy

php artisan make:policy PostPolicy --model=Post

實作 Policy 方法

<?php

namespace App\Policies;

use App\Models\Post;
use App\Models\User;

class PostPolicy
{
    /**
     * 賦予管理員所有權限
     */
    public function before(User $user, string $ability): bool|null
    {
        if ($user->is_admin) {
            return true;
        }

        return null;
    }

    public function viewAny(User $user): bool
    {
        return true;
    }

    public function view(User $user, Post $post): bool
    {
        return true;
    }

    public function create(User $user): bool
    {
        return true;
    }

    public function update(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }

    public function delete(User $user, Post $post): bool
    {
        return $user->id === $post->user_id;
    }
}

在 Controller 加入 authorizeResource()

<?php

namespace App\Http\Controllers;

use App\Models\Post;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\View\View;

class PostController extends Controller
{
    public function __construct()
    {
        $this->authorizeResource(Post::class, 'post');
    }

    public function index(): View
    {
        $posts = Post::latest()->paginate(10);
        return view('posts.index', compact('posts'));
    }

    public function store(Request $request): RedirectResponse
    {
        $post = $request->user()->posts()->create(
            $request->validate([
                'title' => ['required', 'string', 'max:255'],
                'body'  => ['required', 'string'],
            ])
        );

        return redirect()->route('posts.show', $post);
    }

    public function update(Request $request, Post $post): RedirectResponse
    {
        $post->update(
            $request->validate([
                'title' => ['required', 'string', 'max:255'],
                'body'  => ['required', 'string'],
            ])
        );

        return redirect()->route('posts.show', $post);
    }

    public function destroy(Post $post): RedirectResponse
    {
        $post->delete();

        return redirect()->route('posts.index');
    }
}

在 Blade 模板加入權限檢查

{{-- resources/views/posts/show.blade.php --}}
<h1>{{ $post->title }}</h1>
<p>{{ $post->body }}</p>
<p>作者：{{ $post->user->name }}</p>

@can('update', $post)
    <a href="{{ route('posts.edit', $post) }}">編輯</a>
@endcan

@can('delete', $post)
    <form method="POST" action="{{ route('posts.destroy', $post) }}">
        @csrf
        @method('DELETE')
        <button type="submit">刪除</button>
    </form>
@endcan

總結

Gate 與 Policy 的選用

Gate：不綁定特定模型的簡易權限判定。像是管理員儀表板的存取或全域設定的修改權限。
Policy：針對模型的 CRUD 操作權限管理。可依 Post、Order、Comment 等資源分別建立 Policy 類別。

常用 API 總覽

// 用 Gate 檢查
Gate::allows('update-post', $post);      // true/false
Gate::denies('update-post', $post);      // true/false
Gate::authorize('update-post', $post);   // 失敗時拋例外

// 用 User Model 檢查
$user->can('update', $post);     // true/false
$user->cannot('update', $post);  // true/false

// 於 Controller 檢查
Gate::authorize('update', $post);        // 失敗時 403

// 於 Blade 檢查
@can('update', $post) ... @endcan
@cannot('update', $post) ... @endcannot

常用 Artisan 指令

# 產生空的 Policy
php artisan make:policy PostPolicy

# 產生包含對應模型 CRUD 方法的 Policy
php artisan make:policy PostPolicy --model=Post

​認證與授權的差異

​Gate

​透過 Gate 的授權流程

​定義 Gate

​用 Gate 檢查權限

​用 Gate::authorize() 拋出例外

​管理員繞過（before 方法）

​Blade 模板中的 @can / @cannot

​Policy

​透過 Policy 的授權流程

​產生 Policy

​模型與 Policy 的自動探索

​實作 Policy 方法

​管理員繞過（before 方法）

​before Callback 的執行順序

​在 Controller 中使用 Policy

​authorize() 方法

​用 authorizeResource() 一次註冊 RESTful Policy

​在 Middleware 中授權

​在 Blade 模板使用 Policy

​實務範例：部落格文章的權限管理

​總結

認證與授權的差異

Gate

透過 Gate 的授權流程

定義 Gate

用 Gate 檢查權限

用 Gate::authorize() 拋出例外

管理員繞過（before 方法）

Blade 模板中的 @can / @cannot

Policy

透過 Policy 的授權流程

產生 Policy

模型與 Policy 的自動探索

實作 Policy 方法

管理員繞過（before 方法）

before Callback 的執行順序

在 Controller 中使用 Policy

authorize() 方法

用 authorizeResource() 一次註冊 RESTful Policy

在 Middleware 中授權

在 Blade 模板使用 Policy

實務範例：部落格文章的權限管理

總結