控制器

介绍
编写控制器
- 基本控制器
- 单动作控制器
控制器中间件
资源控制器
依赖注入与控制器

介绍

与其在路由文件中将所有请求处理逻辑定义为闭包，不如使用“控制器”类来组织这些行为。控制器可以将相关的请求处理逻辑分组到一个类中。例如，一个 UserController 类可能会处理与用户相关的所有传入请求，包括显示、创建、更新和删除用户。默认情况下，控制器存储在 app/Http/Controllers 目录中。

编写控制器

基本控制器

让我们来看一个基本控制器的例子。注意，控制器扩展了 Laravel 附带的基础控制器类：App\Http\Controllers\Controller：

php

<?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)
        ]);
    }
}

您可以像这样为此控制器方法定义一个路由：

php

use App\Http\Controllers\UserController;

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

当传入请求与指定的路由 URI 匹配时，将调用 App\Http\Controllers\UserController 类上的 show 方法，并将路由参数传递给该方法。

NOTE

控制器不是必须扩展基类。然而，您将无法访问诸如 middleware 和 authorize 方法等便捷功能。

单动作控制器

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

php

<?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()
    {
        // ...
    }
}

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

php

use App\Http\Controllers\ProvisionServer;

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

您可以使用 make:controller Artisan 命令的 --invokable 选项生成一个可调用的控制器：

php

php artisan make:controller ProvisionServer --invokable

NOTE

可以使用存根发布自定义控制器存根。

控制器中间件

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

php

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

或者，您可能会发现方便的是在控制器的构造函数中指定中间件。使用控制器构造函数中的 middleware 方法，您可以将中间件分配给控制器的动作：

php

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

控制器还允许您使用闭包注册中间件。这为单个控制器定义内联中间件提供了一种便捷的方法，而无需定义整个中间件类：

php

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

资源控制器

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

由于这种常见的用例，Laravel 资源路由将典型的创建、读取、更新和删除（“CRUD”）路由分配给一个控制器，只需一行代码即可。首先，我们可以使用 make:controller Artisan 命令的 --resource 选项快速创建一个控制器来处理这些操作：

php

php artisan make:controller PhotoController --resource

此命令将在 app/Http/Controllers/PhotoController.php 生成一个控制器。控制器将包含每个可用资源操作的方法。接下来，您可以注册一个指向控制器的资源路由：

php

use App\Http\Controllers\PhotoController;

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

此单个路由声明创建多个路由以处理资源上的各种操作。生成的控制器将已经为每个这些操作预留了方法。请记住，您始终可以通过运行 route:list Artisan 命令快速查看应用程序的路由概览。

您甚至可以通过将数组传递给 resources 方法一次注册多个资源控制器：

php

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

资源控制器处理的动作

动词	URI	动作	路由名称
GET	`/photos`	index	photos.index
GET	`/photos/create`	create	photos.create
POST	`/photos`	store	photos.store
GET	`/photos/{photo}`	show	photos.show
GET	`/photos/{photo}/edit`	edit	photos.edit
PUT/PATCH	`/photos/{photo}`	update	photos.update
DELETE	`/photos/{photo}`	destroy	photos.destroy

自定义缺失模型行为

通常，如果未找到隐式绑定的资源模型，将生成 404 HTTP 响应。但是，您可以通过在定义资源路由时调用 missing 方法来自定义此行为。missing 方法接受一个闭包，如果找不到隐式绑定的模型，该闭包将在资源的任何路由中被调用：

php

use App\Http\Controllers\PhotoController;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Redirect;

Route::resource('photos', PhotoController::class)
        ->missing(function (Request $request) {
            return Redirect::route('photos.index');
        });

指定资源模型

如果您正在使用路由模型绑定并希望资源控制器的方法对模型实例进行类型提示，您可以在生成控制器时使用 --model 选项：

php

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

生成表单请求

在生成资源控制器时，您可以提供 --requests 选项，以指示 Artisan 为控制器的存储和更新方法生成表单请求类：

php

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

部分资源路由

在声明资源路由时，您可以指定控制器应处理的动作子集，而不是完整的默认动作集：

php

use App\Http\Controllers\PhotoController;

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

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

API 资源路由

在声明将由 API 消费的资源路由时，您通常希望排除呈现 HTML 模板的路由，例如 create 和 edit。为了方便起见，您可以使用 apiResource 方法自动排除这两个路由：

php

use App\Http\Controllers\PhotoController;

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

您可以通过将数组传递给 apiResources 方法一次注册多个 API 资源控制器：

php

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

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

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

php

php artisan make:controller PhotoController --api

嵌套资源

有时您可能需要定义嵌套资源的路由。例如，一个照片资源可能有多个评论可以附加到照片上。要嵌套资源控制器，您可以在路由声明中使用“点”表示法：

php

use App\Http\Controllers\PhotoCommentController;

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

此路由将注册一个嵌套资源，可以通过以下 URI 访问：

php

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

范围嵌套资源

Laravel 的隐式模型绑定功能可以自动范围嵌套绑定，以便确认解析的子模型属于父模型。通过在定义嵌套资源时使用 scoped 方法，您可以启用自动范围并指示 Laravel 应通过哪个字段检索子资源。有关如何实现此目的的更多信息，请参阅范围资源路由文档。

浅层嵌套

通常，在 URI 中同时包含父 ID 和子 ID 并不是完全必要的，因为子 ID 已经是一个唯一标识符。当使用唯一标识符（例如自增主键）在 URI 段中标识模型时，您可以选择使用“浅层嵌套”：

php

use App\Http\Controllers\CommentController;

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

此路由定义将定义以下路由：

动词	URI	动作	路由名称
GET	`/photos/{photo}/comments`	index	photos.comments.index
GET	`/photos/{photo}/comments/create`	create	photos.comments.create
POST	`/photos/{photo}/comments`	store	photos.comments.store
GET	`/comments/{comment}`	show	comments.show
GET	`/comments/{comment}/edit`	edit	comments.edit
PUT/PATCH	`/comments/{comment}`	update	comments.update
DELETE	`/comments/{comment}`	destroy	comments.destroy

命名资源路由

默认情况下，所有资源控制器动作都有一个路由名称；但是，您可以通过传递一个包含所需路由名称的 names 数组来覆盖这些名称：

php

use App\Http\Controllers\PhotoController;

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

命名资源路由参数

默认情况下，Route::resource 将根据资源名称的“单数化”版本为您的资源路由创建路由参数。您可以使用 parameters 方法轻松地为每个资源覆盖此设置。传递给 parameters 方法的数组应为资源名称和参数名称的关联数组：

php

use App\Http\Controllers\AdminUserController;

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

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

php

/users/{admin_user}

范围资源路由

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

php

use App\Http\Controllers\PhotoCommentController;

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

此路由将注册一个范围嵌套资源，可以通过以下 URI 访问：

php

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

当使用自定义键的隐式绑定作为嵌套路由参数时，Laravel 将自动范围查询以通过其父级检索嵌套模型，使用约定来猜测父级上的关系名称。在这种情况下，将假定 Photo 模型具有一个名为 comments 的关系（路由参数名称的复数形式），可用于检索 Comment 模型。

本地化资源URI

默认情况下，Route::resource 将使用英语动词创建资源 URI。如果您需要本地化 create 和 edit 动作动词，可以使用 Route::resourceVerbs 方法。这可以在应用程序的 App\Providers\RouteServiceProvider 中的 boot 方法的开头完成：

php

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

    // ...
}

一旦动词被自定义，像 Route::resource('fotos', PhotoController::class) 这样的资源路由注册将生成以下 URI：

php

/fotos/crear

/fotos/{foto}/editar

补充资源控制器

如果您需要为资源控制器添加默认资源路由集之外的其他路由，您应该在调用 Route::resource 方法之前定义这些路由；否则，由 resource 方法定义的路由可能会无意中优先于您的补充路由：

php

use App\Http\Controller\PhotoController;

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

NOTE

请记住保持控制器的专注。如果您发现自己经常需要典型资源动作集之外的方法，请考虑将控制器拆分为两个较小的控制器。

依赖注入与控制器

构造函数注入

Laravel 服务容器用于解析所有 Laravel 控制器。因此，您可以在其构造函数中对控制器可能需要的任何依赖项进行类型提示。声明的依赖项将自动解析并注入到控制器实例中：

php

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * 用户存储库实例。
     */
    protected $users;

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

方法注入

除了构造函数注入，您还可以对控制器的方法进行类型提示依赖项。方法注入的一个常见用例是将 Illuminate\Http\Request 实例注入到控制器方法中：

php

<?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;

        //
    }
}

如果您的控制器方法还期望来自路由参数的输入，请在其他依赖项之后列出您的路由参数。例如，如果您的路由定义如下：

php

use App\Http\Controllers\UserController;

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

您仍然可以对 Illuminate\Http\Request 进行类型提示，并通过以下方式定义控制器方法来访问您的 id 参数：

php

<?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)
    {
        //
    }
}

控制器 ​

介绍 ​

编写控制器 ​

基本控制器 ​

单动作控制器 ​

控制器中间件 ​

资源控制器 ​

资源控制器处理的动作 ​

自定义缺失模型行为 ​

指定资源模型 ​

生成表单请求 ​

部分资源路由 ​

API 资源路由 ​

嵌套资源 ​

范围嵌套资源 ​

浅层嵌套 ​

命名资源路由 ​

命名资源路由参数 ​

范围资源路由 ​

本地化资源URI ​

补充资源控制器 ​

依赖注入与控制器 ​

构造函数注入 ​

方法注入 ​

控制器

介绍

编写控制器

基本控制器

单动作控制器

控制器中间件

资源控制器

资源控制器处理的动作

自定义缺失模型行为

指定资源模型

生成表单请求

部分资源路由

API 资源路由

嵌套资源

范围嵌套资源

浅层嵌套

命名资源路由

命名资源路由参数

范围资源路由

本地化资源URI

补充资源控制器

依赖注入与控制器

构造函数注入

方法注入