控制器

• 简介
• 编写控制器
  • 基础控制器
  • 单行为控制器
• 控制器中间件
• 资源型控制器
  • 部分资源路由
  • 嵌套资源
  • 命名资源路由
  • 命名资源路由参数
  • 确定资源路由范围
  • 自定义资源 URIs
  • 补充资源控制器
• 依赖注入 & 控制器

简介

为了替代在路由文件中以闭包形式定义的所有的请求处理逻辑，你可能想要使用控制类来组织这些行为。控制器能将相关的请求处理逻辑组成一个单独的类。例如，一个 UserController 类可以处理所有与用户相关的传入请求，包括显示，创建，更新和删除用户，控制器被存放在 app/Http/Controllers 目录。

编写控制器

基础控制器

让我们看一个基础控制器的例子，需要注意的是，该控制器继承了 Laravel 的基础控制器 App\Http\Controllers\Controller：

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Models\User;

class UserController extends Controller
{
    /**
     * 显示指定用户的简介
     *
     * @param  int  $id
     * @return \Illuminate\View\View
     */
    public function show($id)
    {
        return view('user.profile', [
            'user' => User::findOrFail($id)
        ]);
    }
}

你可以像这样定义一个指向控制器行为的路由：

use App\Http\Controllers\UserController;

Route::get('/user/{id}', [UserController::class, 'show']);

当一个请求与指定路由的 URI 匹配时，App\Http\Controllers\UserController 控制器中的 show 方法将会执行。路由参数也将会被传递给该方法。

技巧：控制器并不是 必须 继承基础类。如果控制器没有继承基础类，你将无法使用一些便捷的功能，比如 middleware 和 authorize 方法。

单行为控制器

如果控制器操作特别复杂，你可能会发现将整个控制器类专用于单个操作会很方便。为此，你可以在控制器内定义一个单一的 __invoke 方法：

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Models\User;

class ProvisionServer extends Controller
{
    /**
     * 设置新的 web 服务器
     *
     * @return \Illuminate\Http\Response
     */
    public function __invoke()
    {
        // ...
    }
}

为单个行为控制器注册路由时，无需指定控制器方法。相反，你可以简单的将控制器的名称传递给路由：

use App\Http\Controllers\ProvisionServer;

Route::post('/server', ProvisionServer::class);

你可以通过 Artisan 命令工具里的 make:controller 命令中的 --invokable 选项来生成可调用的控制器：

php artisan make:controller ProvisionServer --invokable

技巧：可以使用 stub 定制 自定义控制器模板。

控制器中间件

中间件 可以在路由文件中分配给控制器的路由：

Route::get('profile', [UserController::class, 'show'])->middleware('auth');

然而，在控制器的构造函数中指定中间件更为方便。使用控制器构造函数中的 middleware 方法，可以轻松的将中间件分配给控制器。你甚至可以将中间件限制为只在控制器中的某些方法生效：

class UserController extends Controller
{
    /**
     * 实例化一个新的控制器实例
     *
     * @return void
     */
    public function __construct()
    {
        $this->middleware('auth');
        $this->middleware('log')->only('index');
        $this->middleware('subscribed')->except('store');
    }
}

同时，控制器还允许你使用一个闭包来注册中间件，这为不定义整个中间件类的情况下为单个控制器定义中间件提供了一种便捷的方法：

$this->middleware(function ($request, $next) {
    return $next($request);
});

资源型控制器

如果你将应用程序中的每个 Eloquent 模型都视为资源，那么通常对应用程序中的每个资源都执行相同的操作。例如，假设你的应用程序中包含一个 Photo 模型和一个 Movie 模型。用户可能可以创建，读取，更新或者删除这些资源。

Laravel 的资源路由通过单行代码即可将典型的「CURD (增删改查)」路由分配给控制器。首先，我们可以使用 Artisan 命令 make:controller 的 --resource 选项来快速创建一个控制器：

php artisan make:controller PhotoController --resource

这个命令将会生成一个控制器 app/Http/Controllers/PhotoController.php。其中包括每个可用资源操作的方法。接下来，你可以给控制器注册一个资源路由：

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class);

这个单一的路由声明创建了多个路由来处理资源上的各种行为。生成的控制器为每个行为保留了方法， 而且你可以通过运行 Artisan 命令 route:list 来快速了解你的应用程序。

你可以通过将数组传参到 resources 方法中的方式来一次性的创建多个资源控制器：

Route::resources([
    'photos' => PhotoController::class,
    'posts' => PostController::class,
]);

资源控制器操作处理

指定资源模型

如果你使用了路由模型的绑定 路由模型绑定 并且想在资源控制器的方法中使用类型提示，你可以在生成控制器的时候使用 --model 选项：

php artisan make:controller PhotoController --resource --model=Photo

部分资源路由

当声明资源路由时，你可以指定控制器处理的部分行为，而不是所有默认的行为：

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class)->only([
    'index', 'show'
]);

Route::resource('photos', PhotoController::class)->except([
    'create', 'store', 'update', 'destroy'
]);

API 资源路由

当声明用于 APIs 的资源路由时，通常需要排除显示 HTML 模板的路由。例如 create and edit。为了方便起见 apiResource 方法自动排除这两个路由：

use App\Http\Controllers\PhotoController;

Route::apiResource('photos', PhotoController::class);

你也可以传递一个数组给 apiResources 方法来同时注册多个 API 资源控制器：

use App\Http\Controllers\PhotoController;
use App\Http\Controllers\PostController;

Route::apiResources([
    'photos' => PhotoController::class,
    'posts' => PostController::class,
]);

要快速生成不包含 create 或 edit 方法的用于开发接口的资源控制器，请在执行 make:controller 命令时使用 --api 参数：

php artisan make:controller PhotoController --api

嵌套资源

有时可能需要定义一个嵌套的资源型路由。例如，照片资源可能被添加了多个评论。那么可以在路由中使用“.”符号来声明资源型控制器：

use App\Http\Controllers\PhotoCommentController;

Route::resource('photos.comments', PhotoCommentController::class);

该路由会注册一个嵌套资源，可以使用如下 URIs 访问：

/photos/{photo}/comments/{comment}

限定嵌套资源的范围

Laravel 的 隐式模型绑定 特性可以自动限定嵌套绑定的范围，以便确认已解析的子模型会自动属于父模型。定义嵌套路由时，使用 scoped 方法，可以开启自动范围限定，也可以指定 Laravel 应该按照哪个字段检索子模型资源，有关如何完成此操作的更多信息，请参见有关 范围资源路由 的文档。

浅层嵌套

通常，并不完全需要在 URI 中同时拥有父 ID 和子 ID，因为子 ID 已经是唯一的标识符。当使用唯一标识符（如自动递增的主键）来标识 URL 中的模型时，可以选择使用「浅嵌套」的方式定义路由：

use App\Http\Controllers\CommentController;

Route::resource('photos.comments', CommentController::class)->shallow();

上面的路由定义方式会定义以下路由：

命名资源路由

默认情况下，所有的资源控制器行为都有一个路由名称。你可以传入 names 数组来覆盖这些名称：

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class)->names([
    'create' => 'photos.build'
]);

命名资源路由参数

默认情况下，Route::resource 会根据资源名称的「单数」形式创建资源路由的路由参数。你可以在选项数组中传入 parameters 参数来轻松地覆盖每个资源。parameters 数组应该是资源名称和参数名称的关联数组：

use App\Http\Controllers\AdminUserController;

Route::resource('users', AdminUserController::class)->parameters([
    'users' => 'admin_user'
]);

上面的示例将会为资源的 show 路由生成以下的 URL：

/users/{admin_user}

限定范围的资源路由

Laravel 的 作用域隐式模型绑定 功能可以自动确定嵌套绑定的范围，以便确认已解析的子模型属于父模型。通过在定义嵌套资源时使用 scoped 方法，你可以启用自动范围界定，并指示 Laravel 应该通过以下方式来检索子资源的哪个字段：

use App\Http\Controllers\PhotoCommentController;

Route::resource('photos.comments', PhotoCommentController::class)->scoped([
    'comment' => 'slug',
]);

此路由将注册一个有范围的嵌套资源，该资源可以通过以下 URIs 进行访问：

/photos/{photo}/comments/{comment:slug}

当使用一个自定义键的隐式绑定作为嵌套路由参数时，Laravel 会自动限定查询范围，按照约定的命名方式去父类中查找关联方法，然后检索到对应的嵌套模型。在这种情况下，将假定 Photo 模型有一个叫 comments （路由参数名的复数）的关联方法，通过这个方法可以检索到 Comment 模型。

本地化资源 URIs

默认情况下，Route::resource 将会用英文动词创建资源 URIs。如果需要自定义 create 和 edit 行为的动名词，你可以在 App\Providers\RouteServiceProvider 的 boot 方法中使用 Route::resourceVerbs 方法实现：

/**
 * 定义你的路由模型绑定，模式过滤器等
 *
 * @return void
 */
public function boot()
{
    Route::resourceVerbs([
        'create' => 'crear',
        'edit' => 'editar',
    ]);

    // ...
}

动作被自定义后，像 Route::resource('fotos', PhotoController::class) 这样注册的资源路由将会产生如下的 URIs：

/fotos/crear

/fotos/{foto}/editar

补充资源控制器

如果你需要增加额外的路由到默认的资源路由之中，你需要在 Route::resource 前定义它们；否则，由 resource 方法定义的路由可能会无意间优先于你定义的路由：

use App\Http\Controller\PhotoController;

Route::get('/photos/popular', [PhotoController::class, 'popular']);
Route::resource('photos', PhotoController::class);

技巧：记得保持你的控制器的专一性。如果你需要典型的资源操作以外的方法，请考虑将你的控制器分割为两个更小的控制器。

依赖注入 & 控制器

构造注入

Laravel 服务容器 用于解析所有 Laravel 控制器。因此，你可以在控制器的构造函数中使用类型提示需要的依赖项。声明的解析会自动解析并注入到控制器实例中去：

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * 用户 repository 实例
     */
    protected $users;

    /**
     * 创建一个新的控制器实例
     *
     * @param  \App\Repositories\UserRepository  $users
     * @return void
     */
    public function __construct(UserRepository $users)
    {
        $this->users = $users;
    }
}

方法注入

除了构造器注入以外，你还可以在控制器方法中类型提示依赖项。最常见的用法便是注入 Illuminate\Http\Request 到你的控制器方法中：

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * 保存一个新用户
     *
     * @param  \Illuminate\Http\Request  $request
     * @return \Illuminate\Http\Response
     */
    public function store(Request $request)
    {
        $name = $request->name;

        //
    }
}

如果你的控制器方法要从路由参数中获取输入内容，请在你的依赖项之后列出你的路由参数。例如，你可以像这样定义路由：

use App\Http\Controllers\UserController;

Route::put('/user/{id}', [UserController::class, 'update']);

如下所示，你依然可以类型提示 Illuminate\Http\Request 并通过定义你的控制器方法访问 id 参数：

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * 修改制定的用户
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  string  $id
     * @return \Illuminate\Http\Response
     */
    public function update(Request $request, $id)
    {
        //
    }
}