用户授权 · laravel 5.4

<article><h1>Laravel 的用户授权系统</h1><ul><li><a href="#introduction">简介</a></li><li><a href="#gates">Gates</a><ul><li><a href="#writing-gates">编写 Gates</a></li><li><a href="#authorizing-actions-via-gates">通过 Gates 授权动作</a></li></ul></li><li><a href="#creating-policies">创建策略</a><ul><li><a href="#generating-policies">生成策略</a></li><li><a href="#registering-policies">注册策略</a></li></ul></li><li><a href="#writing-policies">编写策略</a><ul><li><a href="#policy-methods">策略方法</a></li><li><a href="#methods-without-models">不使用模型方法</a></li><li><a href="#policy-filters">策略过滤器</a></li></ul></li><li><a href="#authorizing-actions-using-policies">使用策略授权动作</a><ul><li><a href="#via-the-user-model">通过用户模型</a></li><li><a href="#via-middleware">通过中间件</a></li><li><a href="#via-controller-helpers">通过控制器辅助函数</a></li><li><a href="#via-blade-templates">通过 Blade 模板</a></li></ul></li></ul><a name="introduction"></a><h2><a href="#introduction">简介</a></h2>除了内置提供的 <a href="/docs/5.4/authentication">用户认证</a> 服务外，Laravel 还提供一种更简单的方式来处理用户授权动作。类似用户认证，Laravel 有 2 种主要方式来实现用户授权：gates 和策略。可以把 gates 和策略类比于路由和控制器。Gates 提供了一个简单、基于闭包的方式来授权认证。策略则和控制器类似，在特定的模型或者资源中通过分组来实现授权认证的逻辑。我们先来看看 gates，然后再看策略。在你的应用中，不要将 gates 和策略当作相互排斥的方式。大部分应用很可能同时包含 gates 和策略，并且能很好的工作。Gates 大部分应用在模型和资源无关的地方，比如查看管理员的面板。与此相比，策略应该用在特定的模型或者资源中。<a name="gates"></a><h2><a href="#gates">Gates</a></h2><a name="writing-gates"></a><h3>编写 Gates</h3>Gates 是用来决定用户是否授权访问给定的动作的闭包函数，并且典型的做法是在 <code class=" language-php">App\Providers\AuthServiceProvider</code> 类中使用 <code class=" language-php">Gate</code> facade 定义。Gates 接受一个用户实例作为第一个参数，接受可选参数，比如相关的 Eloquent 模型：<pre class=" language-php"><code class=" language-php">/** * 注册任意用户认证、用户授权服务。 * * @return void */ public function boot() { $this->registerPolicies(); Gate::define('update-post', function ($user, $post) { return $user->id == $post->user_id; }); }</code></pre><a name="authorizing-actions-via-gates"></a><h3>使用 gates 授权动作</h3>使用 gates 来授权动作时，应当使用 <code class=" language-php">allows</code> 方法。注意你并不需要传递当前认证通过的用户给 <code class=" language-php">allows</code> 方法。Laravel 会自动处理好传入的用户，然后传递给 gate 闭包函数：<pre class=" language-php"><code class=" language-php">if (Gate::allows('update-post', $post)) { // 当前用户可以更新 post... } if (Gate::denies('update-post', $post)) { // 当前用户不能更新 post... }</code></pre>如果需要指定一个特定的用户可以访问某个动作，可以使用 <code class=" language-php">Gate</code> facade 中的 <code class=" language-php">forUser</code> 方法：<pre class=" language-php"><code class=" language-php">if (Gate::forUser($user)->allows('update-post', $post)) { // 指定用户可以更新 post... } if (Gate::forUser($user)->denies('update-post', $post)) { // 指定用户不能更新 post... }</code></pre><a name="creating-policies"></a><h2><a href="#creating-policies">创建策略</a></h2><a name="generating-policies"></a><h3>生成策略</h3>策略是在特定模型或者资源中组织授权逻辑的类。例如，如果应用是一个博客，会有一个 <code class=" language-php">Post</code> 模型和一个相应的 <code class=" language-php">PostPolicy</code> 来授权用户动作，比如创建或者更新博客。可以使用 <code class=" language-php">make:policy</code> <a href="/docs/5.4/artisan">artisan 命令</a> 来生成策略。生成的策略将放置在 <code class=" language-php">app/Policies</code> 目录。如果在你的应用中不存在这个目录，那么 Laravel 会自动创建：<pre class=" language-php"><code class=" language-php">php artisan make:policy PostPolicy</code></pre><code class=" language-php">make:policy</code> 会生成空的策略类。如果希望生成的类包含基本的「CRUD」策略方法，可以在使用命令时指定 <code class=" language-php">--model</code> 选项：<pre class=" language-php"><code class=" language-php">php artisan make:policy PostPolicy --model=Post</code></pre><blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 所有授权策略会通过 Laravel <a href="/docs/5.4/container">服务容器</a> 解析，意指你可以在授权策略的构造器对任何需要的依赖使用类型提示，它们将会被自动注入。</blockquote><a name="registering-policies"></a><h3>注册策略</h3>一旦该授权策略存在，需要将它进行注册。<code class=" language-php">AuthServiceProvider</code> 包含了一个 <code class=" language-php">policies</code> 属性，可将各种模型对应至管理它们的授权策略。注册一个策略将引导 Laravel 在授权动作访问给定模型时使用何种策略：<pre class=" language-php"><code class=" language-php"><?php namespace App\Providers; use App\Post; use App\Policies\PostPolicy; use Illuminate\Support\Facades\Gate; use Illuminate\Foundation\Support\Providers\AuthServiceProvider as ServiceProvider; class AuthServiceProvider extends ServiceProvider { /** * 应用的策略映射。 * * @var array */ protected $policies = [ Post::class => PostPolicy::class, ]; /** * 注册任意用户认证、用户授权服务。 * * @return void */ public function boot() { $this->registerPolicies(); // } }</code></pre><a name="writing-policies"></a><h2><a href="#writing-policies">编写策略</a></h2><a name="policy-methods"></a><h3>策略方法</h3>一旦授权策略被生成且注册，我们就可以为每个权限的授权增加方法。例如，让我们在 <code class=" language-php">PostPolicy</code> 中定义一个 <code class=" language-php">update</code> 方法，它会判断指定的 <code class=" language-php">User</code> 是否可以「更新」一条 <code class=" language-php">Post</code>。<code class=" language-php">update</code> 方法接受 <code class=" language-php">User</code> 和 <code class=" language-php">Post</code> 实例作为参数，并且应当返回 <code class=" language-php">true</code> 或 <code class=" language-php">false</code> 来指明用户是否授权更新给定的 <code class=" language-php">Post</code>。因此，这个例子中，我们判断用户的 id 是否和 post 中的 <code class=" language-php">user_id</code> 匹配：<pre class=" language-php"><code class=" language-php"><?php namespace App\Policies; use App\User; use App\Post; 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; } }</code></pre>你可以接着在此授权策略定义额外的方法，作为各种权限需要的授权。例如，你可以定义 <code class=" language-php">view</code> 或 <code class=" language-php">delete</code> 方法来授权 <code class=" language-php">Post</code> 的多种行为。可以为自定义策略方法使用自己喜欢的名字。<blockquote class="has-icon tip"><div class="flag"><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:a="http://ns.adobe.com/AdobeSVGViewerExtensions/3.0/" version="1.1" x="0px" y="0px" width="56.6px" height="87.5px" viewBox="0 0 56.6 87.5" enable-background="new 0 0 56.6 87.5" xml:space="preserve"><path fill="#FFFFFF" d="M28.7 64.5c-1.4 0-2.5-1.1-2.5-2.5v-5.7 -5V41c0-1.4 1.1-2.5 2.5-2.5s2.5 1.1 2.5 2.5v10.1 5 5.8C31.2 63.4 30.1 64.5 28.7 64.5zM26.4 0.1C11.9 1 0.3 13.1 0 27.7c-0.1 7.9 3 15.2 8.2 20.4 0.5 0.5 0.8 1 1 1.7l3.1 13.1c0.3 1.1 1.3 1.9 2.4 1.9 0.3 0 0.7-0.1 1.1-0.2 1.1-0.5 1.6-1.8 1.4-3l-2-8.4 -0.4-1.8c-0.7-2.9-2-5.7-4-8 -1-1.2-2-2.5-2.7-3.9C5.8 35.3 4.7 30.3 5.4 25 6.7 14.5 15.2 6.3 25.6 5.1c13.9-1.5 25.8 9.4 25.8 23 0 4.1-1.1 7.9-2.9 11.2 -0.8 1.4-1.7 2.7-2.7 3.9 -2 2.3-3.3 5-4 8L41.4 53l-2 8.4c-0.3 1.2 0.3 2.5 1.4 3 0.3 0.2 0.7 0.2 1.1 0.2 1.1 0 2.2-0.8 2.4-1.9l3.1-13.1c0.2-0.6 0.5-1.2 1-1.7 5-5.1 8.2-12.1 8.2-19.8C56.4 12 42.8-1 26.4 0.1zM43.7 69.6c0 0.5-0.1 0.9-0.3 1.3 -0.4 0.8-0.7 1.6-0.9 2.5 -0.7 3-2 8.6-2 8.6 -1.3 3.2-4.4 5.5-7.9 5.5h-4.1H28h-0.5 -3.6c-3.5 0-6.7-2.4-7.9-5.7l-0.1-0.4 -1.8-7.8c-0.4-1.1-0.8-2.1-1.2-3.1 -0.1-0.3-0.2-0.5-0.2-0.9 0.1-1.3 1.3-2.1 2.6-2.1H41C42.4 67.5 43.6 68.2 43.7 69.6zM37.7 72.5H26.9c-4.2 0-7.2 3.9-6.3 7.9 0.6 1.3 1.8 2.1 3.2 2.1h4.1 0.5 0.5 3.6c1.4 0 2.7-0.8 3.2-2.1L37.7 72.5z"></path></svg></div> 如果在 Artisan 控制台生成策略使用 <code class=" language-php">--model</code> 选项，会自动包含 <code class=" language-php">view</code>、<code class=" language-php">create</code>、<code class=" language-php">update</code> 和 <code class=" language-php">delete</code> 动作。</blockquote><a name="methods-without-models"></a><h3>不包含模型方法</h3>一些策略方法只接受当前认证通过的用户作为参数，而不用传入授权相关的模型实例。最普遍的应用场景就是授权 <code class=" language-php">create</code> 动作。例如，如果正在创建一篇博客，你可能希望检查一下当前用户是否授权创建博客。当定义一个不需要传入模型实例的策略方法时，比如 <code class=" language-php">create</code> 方法，你需要定义这个方法只接受已授权的用户作为参数：<pre class=" language-php"><code class=" language-php">/** * 判断给定用户是否可以创建博客。 * * @param \App\User $user * @return bool */ public function create(User $user) { // }</code></pre><a name="policy-filters"></a><h3>策略过滤器</h3>对特定用户，你可能希望通过指定的策略授权所有动作。要达到这个目的，可以在策略中定义一个 <code class=" language-php">before</code> 方法。<code class=" language-php">before</code> 方法会在策略中其他所有方法之前执行，这样提供了一种方式来授权动作而不是指定的策略方法来执行判断。这个功能最常见的场景是授权应用的管理员可以访问所有动作：<pre class=" language-php"><code class=" language-php">public function before($user, $ability) { if ($user->isSuperAdmin()) { return true; } }</code></pre>如果你想拒绝用户所有的授权，你应该在 <code class=" language-php">before</code> 方法中返回 <code class=" language-php">false</code>。如果返回的是 <code class=" language-php">null</code>，则通过其他的策略方法来决定授权与否。<a name="authorizing-actions-using-policies"></a><h2><a href="#authorizing-actions-using-policies">使用策略授权动作</a></h2><a name="via-the-user-model"></a><h3>通过用户模型</h3>Laravel 应用内置的 <code class=" language-php">User</code> 模型包含 2 个有用的方法来授权动作：<code class=" language-php">can</code> 和 <code class=" language-php">cant</code>。<code class=" language-php">can</code> 方法指定需要授权的动作和相关的模型。例如，判定一个用户是否授权更新给定的 <code class=" language-php">Post</code> 模型：<pre class=" language-php"><code class=" language-php">if ($user->can('update', $post)) { // }</code></pre>如果给定模型的 <a href="#registering-policies">策略已被注册</a>，<code class=" language-php">can</code> 方法会自动调用核实的策略方法并且返回 boolean 值。如果没有策略注册到这个模型，<code class=" language-php">can</code> 方法会尝试调用和动作名相匹配的基于闭包的 Gate。<h4>不需要指定模型的动作</h4>一些动作，比如 <code class=" language-php">create</code>，并不需要指定模型实例。在这种情况下，可传递一个类名给 <code class=" language-php">can</code> 方法。当授权动作时，这个类名将被用来判断使用哪个策略：<pre class=" language-php"><code class=" language-php">use App\Post; if ($user->can('create', Post::class)) { // 执行相关策略中的「create」方法... }</code></pre><a name="via-middleware"></a><h3>通过中间件</h3>Laravel 包含一个可以在请求到达路由或控制器之前就进行动作授权的中间件。默认，<code class=" language-php">Illuminate\Auth\Middleware\Authorize</code> 中间件被指定到 <code class=" language-php">App\Http\Kernel</code> 类中 <code class=" language-php">can</code> 键上。我们用一个授权用户更新博客的例子来讲解 <code class=" language-php">can</code> 中间件的使用：<pre class=" language-php"><code class=" language-php">use App\Post; Route::put('/post/{post}', function (Post $post) { // 当前用户可以更新博客... })->middleware('can:update,post');</code></pre>在这个例子中，我们传递给 <code class=" language-php">can</code> 中间件 2 个参数。第一个是需要授权的动作的名称，第二个是我们希望传递给策略方法的路由参数。这里因为使用了 <a href="/docs/5.4/routing#implicit-binding">隐式模型绑定</a>，一个 <code class=" language-php">Post</code> 会被传递给策略方法。如果用户不被授权访问指定的动作，这个中间件会生成带有 <code class=" language-php">403</code> 状态码的 HTTP 响应。<h4>不需要指定模型的动作</h4>同样的，一些动作，比如 <code class=" language-php">create</code>，并不需要指定模型实例。在这种情况下，可传递一个类名给中间件。当授权动作时，这个类名将被用来判断使用哪个策略：<pre class=" language-php"><code class=" language-php">Route::post('/post', function () { // 当前用户可以创建博客... })->middleware('can:create,App\Post');</code></pre><a name="via-controller-helpers"></a><h3>通过控制器辅助函数</h3>除了在 <code class=" language-php">User</code> 模型中提供辅助方法外，Laravel 也为所有继承了 <code class=" language-php">App\Http\Controllers\Controller</code> 基类的控制器提供了一个有用的 <code class=" language-php">authorize</code> 方法。和 <code class=" language-php">can</code> 方法类似，这个方法接收需要授权的动作和相关的模型作为参数。如果动作不被授权，<code class=" language-php">authorize</code> 方法会抛出 <code class=" language-php">Illuminate\Auth\Access\AuthorizationException</code> 异常，然后被 Laravel 默认的异常处理器转化为带有 <code class=" language-php">403</code> 状态码的 HTTP 响应：<pre class=" language-php"><code class=" language-php"><?php namespace App\Http\Controllers; use App\Post; use Illuminate\Http\Request; use App\Http\Controllers\Controller; class PostController extends Controller { /** * 更新给定博客 * * @param Request $request * @param Post $post * @return Response */ public function update(Request $request, Post $post) { $this->authorize('update', $post); // 当前用户可以更新博客... } }</code></pre><h4>不需要指定模型的动作</h4>和之前讨论的一样，一些动作，比如 <code class=" language-php">create</code>，并不需要指定模型实例。在这种情况下，可传递一个类名给 <code class=" language-php">authorize</code> 方法。当授权动作时，这个类名将被用来判断使用哪个策略：<pre class=" language-php"><code class=" language-php">/** * 新建博客 * * @param Request $request * @return Response */ public function create(Request $request) { $this->authorize('create', Post::class); // 当前用户可以新建博客... }</code></pre><a name="via-blade-templates"></a><h3>通过 Blade 模板</h3>当编写 Blade 模板时，你可能希望页面的指定部分只展示给允许授权访问给定动作的用户。例如，你可能希望只展示更新表单给有权更新博客的用户。这种情况下，你可以直接使用 <code class=" language-php">@can</code> 和 <code class=" language-php">@cannot</code> 指令。<pre class=" language-php"><code class=" language-php">@can('update', $post)  @elsecan('create', $post)  @endcan @cannot('update', $post)  @elsecannot('create', $post)  @endcannot</code></pre>这些指令在编写 <code class=" language-php">@if</code> 和 <code class=" language-php">@unless</code> 时提供了方便的缩写。<code class=" language-php">@can</code> 和 <code class=" language-php">@cannot</code> 各自转化为如下声明：<pre class=" language-php"><code class=" language-php">@if (Auth::user()->can('update', $post))  @endif @unless (Auth::user()->can('update', $post))  @endunless</code></pre><h4>不需要指定模型的动作</h4>和大部分其他的授权方法类似，当动作不需要模型实例时，你可以传递一个类名给 <code class=" language-php">@can</code> 和 <code class=" language-php">@cannot</code> 指令：<pre class=" language-php"><code class=" language-php">@can('create', Post::class)  @endcan @cannot('create', Post::class)  @endcannot</code></pre></article>