Policy on ララジャパン

【Policy】Gate::inspect()で不認可の理由を取得する

Wed, 13 Mar 2024 11:21:52 +0900

前回の記事でPolicyを使った認可チェックの実装方法について紹介しました。その中でGateファサードのメソッドを使うことで色々応用が効く点に触れました。今回はその辺を少し掘り下げてどんなケースで応用が効くのか紹介したいと思います。

不認可の理由を表示したい

時としてユーザの操作が制限されている（つまり特定のアクションが不認可である）場合にその理由を表示したいケースがあります。例えば以下の様な商品一覧ページがあったとして、何かしらの理由で商品が購入不可の場合に購入ボタンを無効とし、その理由を赤字で表示したい場合など。もちろん、このケースでもPolicyが適用できます。

こちらのページのPolicyの実装は以下のようになります。認可がdenyされるケースが複数あり、それぞれ異なるメッセージが返されます。

app/Policies/ProductPolicy.php

namespace App\Policies;

use App\Models\User;
use App\Models\Product;
use Illuminate\Auth\Access\Response;

class ProductPolicy
{
    public function available(?User $user, Product $product): Response
    {
        $err = match (true) {
            ($product->vip_only === 'Y' && $user?->vip_flag !== 'Y') => 'VIPのみ購入可能な商品です',
            $user?->balance < $product->price => '残高が不足しています',
            default => '',
        };

        return empty($err)
            ? Response::allow()
            : Response::deny($err);
    }
}

さて、これらのメッセージを先の画面のように表示するにはどうすればよいでしょうか？

前回の記事において、Policyを使った判別処理の実装方法をblade側、controller側、middleware側に分けて紹介しました。それらの中でcontroller側のauthorize()やmiddleware側のcan()ではdenyの時にResponse::deny()に指定したエラー文言を表示する事ができます。しかし、403ページへ強制的にリダイレクトされてからの表示です。403ページへのリダイレクト無しにエラー文言だけ取得して表示に利用することができないでしょうか？

Gate::inspect()を使ってエラー表示

Gate::inspect()を使うとPolicyを介して認可チェックを行った際に返されるレスポンスを取得する事ができます。そちらからResponse::deny()に指定したエラー文言を以下のように取得する事ができます。

> $response = Gate::inspect('available', Product::first())
= Illuminate\Auth\Access\Response {#6114}

// allowか判別
> $response->allowed()
= false

// denyか判別
> $response->denied()
= true

// denyのメッセージ取得
> $response->message();
= "残高が不足しています"

// Response自体を文字列にキャストしてもメッセージが取得できる
> (string) $response
= "残高が不足しています"

ということで、以下のようにbladeにGate::inspect()を埋め込むと、PolicyがResponse::deny()を返した場合に冒頭の商品ページのエラー表示とすることができます。（購入ボタンの部分のみ抜粋しています）

resources/views/product_index.blade.php

...
<div class="mt-2">
    @can('available', $product)
        <button class="button is-small is-success">
            購入する
        </button>
    @else
        <button class="button is-small is-success" disabled>
            購入する
        </button>
        <p class="has-text-weight-bold has-text-danger">{{ Gate::inspect('available', $product)->message() }}</p>
    @endcan
</div>
...

@reason

先のようなエラー表示のケースは良く使われそうですがパッと見て何を表示しているのか分かりづらいと思いませんか？そんな時こんな記事を見つけました。@reasonというディレクティブを追加するというものです。AppServiceProviderのboot()に以下を追加してみましょう。

app/Providers/AppServiceProvider.php

...
    public function boot(): void
    {
        // @reason を追加
        Blade::directive('reason', function ($expression) {
            return "<?php echo Gate::inspect($expression)->message() ?>";
        });
    }
...

すると先ほどのblade側でGate::inspect()をcallしていた部分を次のように書き換えられます。

resources/views/product_index.blade.php

...
<div class="mt-2">
    @can('available', $product)
        <button class="button is-small is-success">
            購入する
        </button>
    @else
        <button class="button is-small is-success" disabled>
            購入する
        </button>
        <p class="has-text-weight-bold has-text-danger">@reason('available', $product)</p>
    @endcan
</div>
...

より分かりやすくなりましたね。

Policyで認可チェック

Wed, 28 Feb 2024 13:12:19 +0900

認証済みのユーザが持つ権限に応じて実行可能な操作を制限したいケースがよくあります。例えば、ブログアプリにおいて記事の編集・削除が可能なのは投稿者に限定するなど。所謂、アクセス権の制御が必要となるケースです。Laravelではそれら「認可」の実装方法としてPolicyが提供されています。

認証済みユーザに応じて表示を出し分ける

冒頭で紹介したブログアプリの例について考えてみましょう。以下のように会員が投稿した記事が一覧で表示されているページがあるとします。

現在、「ひかる」というユーザでログインしており、自身の投稿した記事については編集のアクションが認可されているの編集ボタンが表示されています。Policyを使わない場合は@ifなどで以下の様に表示を出し分けるかと思います。

resources/views/article_index.blade.php

...
@if (auth()->user()?->id == $article->author_id)
    <div class="buttons mt-2">
        <a class="button is-small is-success" href="{{ route('article.edit', $article) }}">
            編集
        </a>
    </div>
@endif
...

しかし、大抵この様な表示の出し分けは１箇所に留まらず、あちこちで必要となるケースが多いです。そして都度この様な条件式を記述するとコードの見通しが悪くなるし、また判別式の条件に変更があった場合にそれら全てを更新するのは面倒です。更に他にも記事に関する権限（例えば閲覧、作成、削除など）をコントロールしたい、となるかもしれません。よって関連する認可処理をどこか適切な場所にまとめておきたいです。そうです、その適切な場所というのがPolicyという訳です。

Policyで実装してみよう

先の例をPolicyを使って書き換えてみましょう。実装の流れとしては３ステップです。

Policyクラスの作成
Policyクラスを登録
Policyを使った判別処理を実装

Policyクラスの作成

Policyクラスの作成は以下のコマンドで実行できます。

php artisan make:policy ArticlePolicy

すると app/Policies/ArticlePolicy.php が作成されます。デフォルトでは以下の通り、何の変哲もない只のクラスです。

app/Policies/ArticlePolicy.php

namespace App\Policies;

use App\Models\User;

class ArticlePolicy
{
    /**
     * Create a new policy instance.
     */
    public function __construct()
    {
        //
    }
}

ここにArticleの編集や削除が可能か判別するupdateメソッドを追加します。以下のように

app/Policies/ArticlePolicy.php

namespace App\Policies;

use App\Models\User;
use App\Models\Article;

class ArticlePolicy
{
    public function update(?User $user, Article $article): bool
    {
        return $user?->id == $article->author_id;
    }
}

追加したupdate()を見てみましょう、第一引数には認証済みのUserモデルインスタンスが渡されます。ユーザがログインしていないゲストユーザの場合はnullとなる為、’?‘を付けてnullableとしています。

Policyクラスを登録する

作成したPolicyクラスを使う為にはAuthServiceProviderの$policiesに登録する必要があります。そうする事でLaravelがどのModelクラスにどのPolicyクラスが紐づいているのか判別できるようになります。

（修正：2024-03-24）作成したPolicyクラスがLaravel標準の命名規則に則っている場合は自動でモデルに紐づくポリシークラスを見つけてくれるので登録する必要はありません。例えば次の条件を満たす場合は自動で解決されます。

モデル名がArticle、かつ、ポリシークラス名がArticlePolicy
Articleモデルがapp/Models配下にある
ArticlePolicyがapp/Policies or app/Models/Policies配下にある

上記の条件を満たさない場合、つまり、標準の命名規則外である場合や独自のディレクトリ構造で運用している場合などはAuthServiceProviderの$policiesに手動で登録しましょう。以下の例では本来は登録せずとも自動解決されますが、説明の為に敢えて$policiesにてArticleとArticlePolicyの紐付けを行っています。

app/Providers/AuthServiceProvider.php

namespace App\Providers;

use App\Models\Article;
use App\Policies\ArticlePolicy;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;

class AuthServiceProvider extends ServiceProvider
{
    /**
     * The model to policy mappings for the application.
     *
     * @var array<class-string, class-string>
     */
    protected $policies = [
        Article::class => ArticlePolicy::class,    // ←追加
    ];

    /**
     * Register any authentication / authorization services.
     */
    public function boot(): void
    {
        //
    }
}

Policyを使った判別処理を実装

作成したArticlePolicyを使って冒頭の編集ボタンの出し分け処理を実装してみましょう。前述した通り、こうした認可の判別処理というのはアプリの至る箇所で必要となり、それぞれの呼び出し元において適した実装方法が提供されています。以下にblade側、controller側、middleware側における例を掲載します

blade側で表示の出し分け

blade側では@canディレクティブを使用する事ができます。冒頭の@ifで表示を出し分けていた処理を@canで書き換えると以下のようになります。

resources/views/article_index.blade.php

...
@can('update', $article)
    <div class="buttons mt-2">
        <a class="button is-small is-success" href="{{ route('article.edit', $article) }}">
            編集
        </a>
    </div>
@endcan
...

@canは第一引数にPolicyクラスのメソッド名、第二引数に判別対象のモデルを指定します。するとLaravelは指定されたモデルを元にAuthServiceProviderで指定した$policiesを見てどのポリシークラスを参照すべきか判断します。そして、紐づくポリシークラス内から第一引数で指定されたメソッドを見つけて実行してくれます。因みに、@canは@if同様に@can…@else…@canとする事もできます。また、@cannotというディレクティブもあるので適宜使い分けてみてください。

controller側で判別する

続いて、controller側でPolicyを使った判別処理の書き方を紹介します。blade側で編集ボタンが非表示となっていても、悪質なユーザがURLを直接参照して編集画面を開いてしまうかもしれません。記事の編集画面のcontroller側にも判別処理を実装してそれを防ぎましょう。３つ方法があります。

can()/cannot()
authorize()
Gate::allow()/Gate::denies()

１つずつみていきましょう。まずcan()から。こちらはUserモデルのcan()をコールして判別する方法です。もしUser以外の認証モデルで使用する場合はAuthorizableトレイトがuseされている必要があるのでご注意を。ArticleControllerのedit()にて以下のように実装しました。

app/Http/Controllers/ArticleController.php

...
    public function edit(Article $article)
    {
        $user = auth()->user();

        if ($user->cannot('update', $article)) {
            abort(403, '他人の記事は編集できません！');
        }

        return $user->name.'の記事の編集ページ';
    }
...

ユーザが記事をupdateできるなら「○○の記事の編集ページ」と表示され、不可なら「他人の記事は編集できません！」と表示されます。口語的なコードで分かりやすいですね。因みに上記ではcannot()を使用していますが、cant()としてもOKです。

次にcontrollerクラスのauthorize()を使用する方法です。認可されない場合は403ページが返されます。こちらはcan()の様に細かい指定ができませんが、短く書くことができます。

app/Http/Controllers/ArticleController.php

...
    public function edit(Article $article)
    {
        $this->authorize('update', $article);

        return auth()->user()->name.'の記事の編集ページ';
    }
...

もし、can()の時の様にエラー文言を指定したい場合はArticlePolicyのupdate()にてResponseクラスを返却するようにします。

app/Policies/ArticlePolicy.php

...
    public function update(?User $user, Article $article): Response
    {
        return ($user?->id == $article->author_id)
            ? Response::allow()
            : Response::deny('他の人の記事は編集できません！');
    }
...

最後にGateファサードを使用する例です。実はPolicyにおけるコアな処理はGateが担っています。can()やauthorize()も内部的にはGateのメソッドをcallしています。その為、Gateのallows()やdenies()を直接呼び出して判別する事もできます。以下の様に。

app/Http/Controllers/ArticleController.php

...
    public function edit(Article $article)
    {
        if (Gate::denies('update', $article)) {
            abort(403, '他の人の記事は編集できません！');
        }

        return auth()->user()->name.'の記事の編集ページ';
    }
...

allows(),denies()以外にもGateには様々なメソッドが用意されていて応用が効きます。それらについては長くなってしまうので次回に紹介したいと思います。

middlewareで判別する

Controller側で判別する方法を紹介しましたが、middlewareで判別する方法もあります。そちらの実装はRouteを定義する際にメソッドチェーンでcan()が使用できます。以下の様に。

routes/web.php

...
Route::get('article/{article}/edit', [ArticleController::class, 'edit'])
    ->can('update', 'article')
    ->name('article.edit');
...

こちらもController側の判別処理で紹介したauthorize()と同様に、不認可であれば403ページを返します。