控制器

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

介绍

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

编写控制器

基本控制器

要快速生成一个新的控制器，可以运行 make:controller Artisan 命令。默认情况下，应用程序的所有控制器都存储在 app/Http/Controllers 目录中：

shell

php artisan make:controller UserController

让我们看看一个基本控制器的例子。一个控制器可以有任意数量的公共方法来响应传入的 HTTP 请求：

php

<?php

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\View\View;

class UserController extends Controller
{
    /**
     * 显示给定用户的个人资料。
     */
    public function show(string $id): View
    {
        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;

class ProvisionServer extends Controller
{
    /**
     * 配置一个新的 Web 服务器。
     */
    public function __invoke()
    {
        // ...
    }
}

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

php

use App\Http\Controllers\ProvisionServer;

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

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

shell

php artisan make:controller ProvisionServer --invokable

NOTE

可以使用 stub publishing 自定义控制器存根。

控制器中间件

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

php

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

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

php

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

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

php

use Closure;
use Illuminate\Http\Request;

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

资源控制器

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

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

shell

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');
        });

软删除模型

通常，隐式模型绑定不会检索已被软删除的模型，而是返回 404 HTTP 响应。但是，您可以通过在定义资源路由时调用 withTrashed 方法来指示框架允许软删除的模型：

php

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class)->withTrashed();

调用 withTrashed 而不带参数将允许 show、edit 和 update 资源路由的软删除模型。您可以通过将数组传递给 withTrashed 方法来指定这些路由的子集：

php

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

指定资源模型

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

shell

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

生成表单请求

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

shell

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 开关：

shell

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 应通过哪个字段检索子资源。有关如何实现此目的的更多信息，请参阅 scoping resource routes 文档。

浅层嵌套

通常，在 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

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

    // ...
}

Laravel 的复数化支持多种不同的语言，您可以根据需要进行配置。一旦动词和复数化语言被自定义，像 Route::resource('publicacion', PublicacionController::class) 这样的资源路由注册将生成以下 URI：

php

/publicacion/crear

/publicacion/{publicaciones}/editar

补充资源控制器

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

php

use App\Http\Controller\PhotoController;

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

NOTE

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

单例资源控制器

有时，您的应用程序将有可能只有一个实例的资源。例如，用户的“个人资料”可以被编辑或更新，但用户可能没有多个“个人资料”。同样，图像可能有一个“缩略图”。这些资源称为“单例资源”，意味着只能存在一个资源实例。在这些情况下，您可以注册一个“单例”资源控制器：

php

use App\Http\Controllers\ProfileController;
use Illuminate\Support\Facades\Route;

Route::singleton('profile', ProfileController::class);

上面的单例资源定义将注册以下路由。正如您所看到的，单例资源没有注册“创建”路由，并且注册的路由不接受标识符，因为只能存在一个资源实例：

动词	URI	操作	路由名称
GET	`/profile`	show	profile.show
GET	`/profile/edit`	edit	profile.edit
PUT/PATCH	`/profile`	update	profile.update

单例资源也可以嵌套在标准资源中：

php

Route::singleton('photos.thumbnail', ThumbnailController::class);

在此示例中，photos 资源将接收所有标准资源路由；然而，thumbnail 资源将是一个单例资源，具有以下路由：

动词	URI	操作	路由名称
GET	`/photos/{photo}/thumbnail`	show	photos.thumbnail.show
GET	`/photos/{photo}/thumbnail/edit`	edit	photos.thumbnail.edit
PUT/PATCH	`/photos/{photo}/thumbnail`	update	photos.thumbnail.update

可创建的单例资源

有时，您可能希望为单例资源定义创建和存储路由。为此，您可以在注册单例资源路由时调用 creatable 方法：

php

Route::singleton('photos.thumbnail', ThumbnailController::class)->creatable();

在此示例中，将注册以下路由。正如您所看到的，DELETE 路由也将为可创建的单例资源注册：

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

如果您希望 Laravel 为单例资源注册 DELETE 路由，但不注册创建或存储路由，可以使用 destroyable 方法：

php

Route::singleton(...)->destroyable();

API 单例资源

apiSingleton 方法可用于注册一个将通过 API 操作的单例资源，从而使 create 和 edit 路由不必要：

php

Route::apiSingleton('profile', ProfileController::class);

当然，API 单例资源也可以是 creatable，这将为资源注册 store 和 destroy 路由：

php

Route::apiSingleton('photos.thumbnail', ProfileController::class)->creatable();

依赖注入与控制器

构造函数注入

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

php

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * 创建一个新的控制器实例。
     */
    public function __construct(
        protected UserRepository $users,
    ) {}
}

方法注入

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

php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * 存储一个新用户。
     */
    public function store(Request $request): RedirectResponse
    {
        $name = $request->name;

        // 存储用户...

        return redirect('/users');
    }
}

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

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\RedirectResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    /**
     * 更新给定用户。
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // 更新用户...

        return redirect('/users');
    }
}

</rewritten_file>

控制器 ​

介绍 ​

编写控制器 ​

基本控制器 ​

单动作控制器 ​

控制器中间件 ​

资源控制器 ​

资源控制器处理的操作 ​

自定义缺失模型行为 ​

软删除模型 ​

指定资源模型 ​

生成表单请求 ​

部分资源路由 ​

API 资源路由 ​

嵌套资源 ​

嵌套资源的范围 ​

浅层嵌套 ​

命名资源路由 ​

命名资源路由参数 ​

资源路由范围 ​

本地化资源 URI ​

补充资源控制器 ​

单例资源控制器 ​

可创建的单例资源 ​

API 单例资源 ​

依赖注入与控制器 ​

构造函数注入 ​

方法注入 ​

控制器

介绍

编写控制器

基本控制器

单动作控制器

控制器中间件

资源控制器

资源控制器处理的操作

自定义缺失模型行为

软删除模型

指定资源模型

生成表单请求

部分资源路由

API 资源路由

嵌套资源

嵌套资源的范围

浅层嵌套

命名资源路由

命名资源路由参数

资源路由范围

本地化资源 URI

补充资源控制器

单例资源控制器

可创建的单例资源

API 单例资源

依赖注入与控制器

构造函数注入

方法注入