用户授权

简介
Gates
创建策略
- 生成策略
- 注册策略
编写策略
使用策略去授权动作

简介

除了提供开箱即用的用户认证服务外，Laravel还提供了一种简单的方法来处理用户的授权动作。与用户认证一样，Laravel的授权方法很简单，授权操作有两种主要方式：gates和策略。

可以把 gates 和策略比作路由和控制器。Gates提供了一种简单的基于闭包的授权方法，而策略和控制器类似，围绕特定模型或资源对其逻辑进行分组来实现授权认证。我们先探索gates，然后研究策略。

在构建一个应用的时候，不用再专门使用 gates 或者只使用策略之间进行选择。大部分应用很可能同时包含 gates 和策略，并且能够很好的进行工作。 Gates 大部分应用在模型和资源没有关系的地方，比如查看管理员的面板。与之相反，策略应该在特定的模型或者资源中使用。

Gates

编写 Gates

Gates 是用来决定用户是否授权执行给予动作的一个闭包函数，并且典型的做法就是在 App\Providers\AuthServiceProvider 中使用 Gate 来定义. Gates 总是接收一个用户实例作为第一个参数，并且可以接收可选参数，比如相关的 Eloquent 模型：

/**
 * 注册任意用户认证、用户授权服务。
 *
 * @return void
 */
public function boot()
{
    $this->registerPolicies();

    Gate::define('edit-settings', function ($user) {
        return $user->isAdmin;
    });

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

Gates 也可以使用类似控制器方法 Class@method 风格的回调字符串来定义：

/**
 * 注册任意用户认证、用户授权服务。
 *
 * @return void
 */
public function boot()
{
    $this->registerPolicies();

    Gate::define('update-post', 'App\Policies\PostPolicy@update');
}

授权动作

使用 Gate 来授权动作的时候，你应该使用 allows 或者 denies 方法。注意，不需要将当前已认证用户传递给这些方法。 Laravel 会自动处理好已经认证通过的用户，然后传递给 Gate 闭包函数：

if (Gate::allows('edit-settings')) {
    // 指定当前用户可以编辑设置
}

if (Gate::allows('update-post', $post)) {
    // 指定当前用户可以进行更新...
}

if (Gate::denies('update-post', $post)) {
    // 指定当前用户不能更新...
}

如果你想判断一个特定的用户是否已经被授权访问某个动作，你可以使用在 Gate 在facade的 forUser 方法:

if (Gate::forUser($user)->allows('update-post', $post)) {
    // 用户可以更新...
}

if (Gate::forUser($user)->denies('update-post', $post)) {
    // 用户不能更新...
}

您可以使用 any 或 none 方法一次授权多个操作：

if (Gate::any(['update-post', 'delete-post'], $post)) {
    // 用户可以更新或删除
}

if (Gate::none(['update-post', 'delete-post'], $post)) {
    // 用户不能更新或删除
}

授权或抛出异常

如果要尝试对某个操作进行授权，并在未授权用户进行该操作的情况下抛出 illuminate\auth\access\authorizationexception，则可以使用 gate::authorize方法。authorizationexception 的实例将自动转换为 403 http 响应：

Gate::authorize('update-post', $post);

// 当前行为已授权...

提供上下文

能够用于授权的 Gate 方法（allows，denies，check，any，none，authorize，can，cannot）和授权[blade directives]（@can，@cannot，@canany）可以接收一个数组作为第二个参数。这些数组元素作为参数传递给 gate ，在做出授权决策时可用于其他上下文：

Gate::define('create-post', function ($user, $category, $extraFlag) {
    return $category->group > 3 && $extraFlag === true;
});

if (Gate::check('create-post', [$category, $extraFlag])) {
    // The user can create the post...
}

Gate 响应

到目前为止，我们只检查了返回简单布尔值的 Gate 。但是，有时你可能希望返回更详细的响应，包括错误消息。为此，你可以从你的 Gate 返回illuminate\auth\access\response：

use Illuminate\Auth\Access\Response;
use Illuminate\Support\Facades\Gate;

Gate::define('edit-settings', function ($user) {
    return $user->isAdmin
                ? Response::allow()
                : Response::deny('You must be a super administrator.');
});

从 Gate 返回授权响应时，gate::allows 方法仍将返回一个简单的布尔值。但是可以使用 gate::inspect 方法获取 Gate 返回的完整授权响应：

$response = Gate::inspect('edit-settings', $post);

if ($response->allowed()) {
    // 当前行为已授权...
} else {
    echo $response->message();
}

当然，当使用 gate::authorize 方法抛出 authorizationexception 时，如果操作未经授权，则授权响应提供的错误消息将传播到 http 响应：

Gate::authorize('edit-settings', $post);

//  当前行为已授权...

Gate 拦截检查

有时，你可能希望将所有能力授予特定用户。所以你可以在所有其他授权检查之前使用 before 方法来定义运行的回调：

Gate::before(function ($user, $ability) {
    if ($user->isSuperAdmin()) {
        return true;
    }
});

如果 before 回调方法返回的是非 null 的结果，则结果将被视为检查结果。

在每次授权检查后你可以使用 after 方法定义要执行的回调。但是，你不能从 after 回调方法中修改授权检查的结果：

Gate::after(function ($user, $ability, $result, $arguments) {
    if ($user->isSuperAdmin()) {
        return true;
    }
});

与 before 检查类似，如果 after 回调返回非 null 结果，则结果将被视为检查结果。

创建策略

生成策略

策略是在特定模型或者资源中组织授权逻辑的类。例如，你的应用是一个博客，那么你在创建或者更新博客的时候，你可能会有一个 Post 模型和一个对应的 PostPolicy 来授权用户动作。

可以使用 make:policy artisan command 生成策略。生成的策略将放在 app/Policies 目录。如果您的应用程序中不存在此目录，Laravel 将为您创建它：

php artisan make:policy PostPolicy

make:policy 命令将生成一个空策略类。如果你想生成一个包含基本的 “CRUD” 策略方法的类，你可以在执行命令时指定一个 --model：

php artisan make:policy PostPolicy --model=Post

建议：所有策略都通过 Laravel 解析 service container，允许您在策略的构造函数中键入提示任何需要的依赖项，以便自动注入它们。

注册策略

一旦策略存在，就需要注册它。新 Laravel 应用程序中包含的 AuthServiceProvider 包含一个 policy 属性，它将您的 Eloquent 模型映射到它们相应的策略。注册一个策略将指导 Laravel 在授权针对给定模型的操作时使用哪个策略：

<?php

namespace App\Providers;

use App\Policies\PostPolicy;
use App\Post;
use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider;
use Illuminate\Support\Facades\Gate;

class AuthServiceProvider extends ServiceProvider
{
    /**
     * 应用程序的策略映射。
     *
     * @var array
     */
    protected $policies = [
        Post::class => PostPolicy::class,
    ];

    /**
     * 注册任何应用程序 authentication / authorization 服务。
     *
     * @return void
     */
    public function boot()
    {
        $this->registerPolicies();

        //
    }
}

策略自动发现

不需要手动注册模型策略，只要模型和策略遵循标准的 Laravel 命名约定，Laravel 就可以自动发现策略。具体来说，策略必须位于包含模型的目录下的 Policies 目录中。例如，模型可以放在 app 目录中，而策略可以放在 app/Policies 目录中。此外，策略名称必须与模型名称匹配，并具有 Policy 后缀。因此，一个 User 模型将对应于一个 UserPolicy 类。

如果希望提供自己的策略发现逻辑，可以使用 Gate::guessPolicyNamesUsing 方法注册自定义回调。通常，这个方法应该从应用程序的 AuthServiceProvider 的 boot 方法中调用:

use Illuminate\Support\Facades\Gate;

Gate::guessPolicyNamesUsing(function ($modelClass) {
    // 返回策略类名…
});

注意：在 AuthServiceProvider 中显式映射的任何策略都将优先于任何潜在的自动发现策略。

编写策略

策略方法

一旦注册了策略，您可以为它授权的每个操作添加方法。例如，让我们在 PostPolicy 上定义一个 update 方法，它确定给定的 User 是否可以更新给定的 Post 实例。

update 方法将接收一个 User 和一个 Post 实例作为参数，并应返回 true 或 false，指示用户是否被授权更新给定的 Post。所以，在这个例子中，让我们验证用户的 id 是否与帖子上的 user_id 匹配：

<?php

namespace App\Policies;

use App\Post;
use App\User;

class PostPolicy
{
    /**
     * 确定用户是否可以更新给定的帖子。
     *
     * @param  \App\User  $user
     * @param  \App\Post  $post
     * @return bool
     */
    public function update(User $user, Post $post)
    {
        return $user->id === $post->user_id;
    }
}

您可以根据策略授权的各种操作的需要，继续在策略上定义其他方法。例如，您可以定义 view 或 delete 方法来授权各种 Post 操作，但请记住，您可以自由地为策略方法指定任何名称。

建议：如果您在通过 Artisan 控制台生成策略时使用了 --model 选项，那么它已经包含了 viewAny、view、create、update、delete、restore 和 forceDelete 操作的方法。

策略响应

到目前为止，我们只研究了返回简单布尔值的策略方法。然而，有时您可能希望返回更详细的响应，包括错误消息。为此，您可以从您的策略方法返回一个\Auth\Access\Response：

use Illuminate\Auth\Access\Response;

/**
 * 确定用户是否可以更新给定的帖子。
 *
 * @param  \App\User  $user
 * @param  \App\Post  $post
 * @return \Illuminate\Auth\Access\Response
 */
public function update(User $user, Post $post)
{
    return $user->id === $post->user_id
                ? Response::allow()
                : Response::deny('You do not own this post.');
}

当从策略返回授权响应时，Gate::allows 方法仍然返回一个简单的布尔值；但是，你可以使用 Gate::inspect 方法来获得Gate返回的完整授权响应：

$response = Gate::inspect('update', $post);

if ($response->allowed()) {
    // 该动作授权通过...
} else {
    echo $response->message();
}

当然，当使用 Gate::authorize 方法在未授权操作时抛出 AuthorizationException，授权响应提供的错误消息将传播到 HTTP 响应：

Gate::authorize('update', $post);

// 该动作授权通过…

不包含模型方法

一些策略方法只接收当前经过身份验证的用户，而不接收它们授权的模型的实例。这种情况在授权 create 操作时最为常见。例如，如果您正在创建博客，您可能希望检查用户是否被授权创建任何帖子。

当定义不接收模型实例的策略方法时，例如 create 方法，它将不接收模型实例。相反，您应该将方法定义为只期望经过身份验证的用户：

/**
 * 确定给定用户是否可以创建帖子。
 *
 * @param  \App\User  $user
 * @return bool
 */
public function create(User $user)
{
    //
}

Guest 用户

默认情况下，如果传入的 HTTP 请求不是由经过身份验证的用户发起的，所有的门和策略都会自动返回 false。但是，您可以通过声明一个「可选」类型提示或为用户参数定义提供一个 null 默认值，从而允许这些授权检查通过您的门和策略:

<?php

namespace App\Policies;

use App\Post;
use App\User;

class PostPolicy
{
    /**
     * 确定用户是否可以更新给定的帖子。
     *
     * @param  \App\User  $user
     * @param  \App\Post  $post
     * @return bool
     */
    public function update(?User $user, Post $post)
    {
        return optional($user)->id === $post->user_id;
    }
}

策略过滤器

对于某些用户，您可能希望授权给定策略中的所有操作。为此，在策略上定义一个 before 方法。before 方法将在策略上的任何其他方法之前执行，从而使您有机会在实际调用预期的策略方法之前授权操作。此功能最常用于授权应用程序管理员执行任何操作：

public function before($user, $ability)
{
    if ($user->isSuperAdmin()) {
        return true;
    }
}

如果您想拒绝用户的所有授权，您应该从 before 方法返回 false。如果返回 null，则授权将传递给策略方法。

注意：如果策略类的 before 方法不包含与正在检查的功能名称匹配的名称的方法，则不会调用该方法。

使用策略授权动作

通过用户模型

Laravel 应用程序中包含的 User 模型包括两个用于授权操作的有用方法：can 和 cant。can 方法接收您希望授权的操作和相关模型。例如，让我们来确定一个用户是否被授权更新一个给定的 Post 模型:

if ($user->can('update', $post)) {
    //
}

如果为给定模型注册了策略，can 方法将自动调用适当的策略并返回布尔结果。如果没有为模型注册策略，can 方法将尝试调用匹配给定操作名称的基于闭包的 Gate。

不需要指定模型的动作

记住，像 create 这样的操作可能不需要模型实例。在这些情况下，可以将类名传递给 can 方法。类名将用于确定在授权操作时使用哪个策略：

use App\Post;

if ($user->can('create', Post::class)) {
    // 在相关策略上执行 "create" 方法…
}

通过中间件

Laravel 包含一个中间件，可以在传入的请求到达路由或控制器之前对操作进行授权。默认情况下，Illuminate\Auth\Middleware\Authorize 中间件被分配给 App\Http\Kernel 类中的 can 键。让我们来探索一个使用 can 中间件授权用户更新博客文章的例子：

use App\Post;

Route::put('/post/{post}', function (Post $post) {
    // 当前用户可以更新帖子…
})->middleware('can:update,post');

在本例中，我们传递了 can 中间件两个参数。第一个是希望授权的操作的名称，第二个是希望传递给策略方法的路由参数。在本例中，由于我们使用隐式模型绑定，一个 Post 模型将被传递给策略方法。如果用户没有被授权执行给定的操作，则中间件将生成一个带有 403 状态代码的 HTTP 响应。

不需要指定模型的动作

同样，像 create 这样的一些操作可能不需要模型实例。在这些情况下，可以将类名传递给中间件。类名将用于确定在授权操作时使用哪个策略：

Route::post('/post', function () {
    // 当前用户可以创建贴子…
})->middleware('can:create,App\Post');

通过控制器辅助函数

除了为 User 模型提供的有用方法之外，Laravel 还为任何扩展 App\Http\Controllers\Controller 基类的控制器提供了一个有用的 authorize 方法。与 can 方法一样，此方法接受您要授权的操作的名称和相关模型。如果操作未被授权，authorize方法将抛出一个 Illuminate\Auth\Access\AuthorizationException ，默认的 Laravel 异常处理程序将转换为具有 403 状态代码的HTTP响应：

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Post;
use Illuminate\Http\Request;

class PostController extends Controller
{
    /**
     * 更新指定博客帖子。
     *
     * @param  Request  $request
     * @param  Post  $post
     * @return Response
     * @throws \Illuminate\Auth\Access\AuthorizationException
     */
    public function update(Request $request, Post $post)
    {
        $this->authorize('update', $post);

        // 当前用户可以更新博客....
    }
}

不需要指定模型的动作

如前所述，像create这样的一些动作可能不需要模型实例。在这些情况下，您应该将类名传递给authorize方法。类名将用于确定授权操作时使用的策略：

/**
 * 创建一个新的博客
 *
 * @param  Request  $request
 * @return Response
 * @throws \Illuminate\Auth\Access\AuthorizationException
 */
public function create(Request $request)
{
    $this->authorize('create', Post::class);

    // 当前用户可以新建博客...
}

授权资源控制器

如果你使用的是资源控制器，那么你就可以在控制器构造方法里使用 authorizeResource 方法。此方法将适当的 can 中间件定义附加到资源控制器相应的方法中。

authorizeResource 方法接收模型类名作为第一个参数，以及路由名称 / 包含模型 ID 的请求参数作为其第二个参数：

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Post;
use Illuminate\Http\Request;

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

以下控制器方法将映射到其对应的策略方法：

控制器方法	策略方法
index	viewAny
show	view
create	create
store	create
edit	update
update	update
destroy	delete

{提示} 你可以使用带有 --model 选项的 make:policy 命令去快速生成基于给定模型的策略类：php artisan make:policy PostPolicy --model=Post。

通过 Blade 模板

当编写 Blade 模板时，可能希望仅在用户被授权执行给定操作时才显示页面的一部分。比如，你可能希望仅在用户可以实际更新帖子时显示博客帖子的更新表单。在这样情况下，你可以使用 @can 和 @cannot 等一系列指令：

@can('update', $post)
    <!-- 当前用户可以更新文章 -->
@elsecan('create', App\Post::class)
    <!-- 当前用户可以新建文章 -->
@endcan

@cannot('update', $post)
    <!-- 当前用户不可以更新文章 -->
@elsecannot('create', App\Post::class)
    <!-- 当前用户不可以新建文章 -->
@endcannot

这些指令是编写 @if 和 @unless 语句的捷径。 @can 和 @cannot 语句分别转化为以下语句：

@if (Auth::user()->can('update', $post))
    <!-- 当前用户可以更新文章 -->
@endif

@unless (Auth::user()->can('update', $post))
    <!-- 当前用户不可以更新文章 -->
@endunless

您还可以确定用户是否具有来自给定能力列表的任何授权能力。要实现这一点，请使用 @canany 指令：

@canany(['update', 'view', 'delete'], $post)
    // 当前用户可以更新，查看和删除文章
@elsecanany(['create'], \App\Post::class)
    // 当前用户可以创建文章
@endcanany

不依赖模型的动作

与大多数其他授权方法一样，如果动作不需要模型实例，则可以将类名传递给 @can 和 @cannot 指令：

@can('create', App\Post::class)
    <!-- 当前用户可以创建文章 -->
@endcan

@cannot('create', App\Post::class)
    <!-- 当前用户不可以创建文章 -->
@endcannot

提供附加上下文

使用策略授权操作时，您可以将数组作为第二个参数传递给各种授权函数和辅助方法。数组中的第一个元素将用于确定应调用哪个策略，而其余数组元素作为参数传递给策略方法，并可在进行授权决策时用于其他上下文。例如，考虑以下 PostPolicy 方法定义，其中包含一个额外的 $category 参数：

/**
 * 确定用户是否可以更新给定的帖子。
 *
 * @param  \App\User  $user
 * @param  \App\Post  $post
 * @param  int  $category
 * @return bool
 */
public function update(User $user, Post $post, int $category)
{
    return $user->id === $post->user_id && 
           $category > 3;
}

在尝试确定验证过的用户是否可以更新给定文章时，我们可以像这样调用此策略方法：

/**
 * 更新给定的博客文章.
 *
 * @param  Request  $request
 * @param  Post  $post
 * @return Response
 * @throws \Illuminate\Auth\Access\AuthorizationException
 */
public function update(Request $request, Post $post)
{
    $this->authorize('update', [$post, $request->input('category')]);

    //当前用户可以更新这篇博客文章...
}

用户授权

用户授权

简介

Gates

编写 Gates

授权动作

授权或抛出异常

提供上下文

Gate 响应

Gate 拦截检查

创建策略

生成策略

注册策略

策略自动发现

编写策略

策略方法

策略响应

不包含模型方法

Guest 用户

策略过滤器

使用策略授权动作

通过用户模型

不需要指定模型的动作

通过中间件

不需要指定模型的动作

通过控制器辅助函数

不需要指定模型的动作

授权资源控制器

通过 Blade 模板

不依赖模型的动作

提供附加上下文

热门教程

最新教程