控制器 – 乌鸦嘴文档中心

介绍

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

编写控制器

基础控制器

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

php artisan make:controller UserController

让我们看一个基础控制器的示例。控制器可以有任意数量的公共方法，这些方法将响应传入的 HTTP 请求：

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

编写好控制器类和方法后，可以像这样定义一个到控制器方法的路由：

use App\Http\Controllers\UserController;

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

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

[!NOTE]
控制器并非必须扩展一个基类。然而，有时扩展一个包含应在所有控制器中共享的方法的基控制器类会很方便。

单操作控制器

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

<?php

namespace App\Http\Controllers;

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

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

use App\Http\Controllers\ProvisionServer;

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

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

php artisan make:controller ProvisionServer --invokable

[!NOTE]
可以使用存根发布自定义控制器存根。

控制器中间件

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

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

或者，您可能会发现在控制器类中指定中间件会很方便。为此，您的控制器应该实现HasMiddleware接口，该接口规定控制器应该有一个静态的middleware方法。从这个方法中，您可以返回一个应应用于控制器操作的中间件数组：

<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;

class UserController extends Controller implements HasMiddleware
{
    /**
     * 获取应分配给控制器的中间件。
     */
    public static function middleware(): array
    {
        return [
            'auth',
            new Middleware('log', only: ['index']),
            new Middleware('subscribed', except: ['store']),
        ];
    }

    //...
}

您还可以将控制器中间件定义为闭包，这提供了一种方便的方式来定义内联中间件，而无需编写整个中间件类：

use Closure;
use Illuminate\Http\Request;

/**
 * 获取应分配给控制器的中间件。
 */
public static function middleware(): array
{
    return [
        function (Request $request, Closure $next) {
            return $next($request);
        },
    ];
}

资源控制器

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

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

php artisan make:controller PhotoController --resource

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

use App\Http\Controllers\PhotoController;

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

这个单一的路由声明创建了多个路由来处理资源上的各种操作。生成的控制器已经为每个操作都有了方法存根。记住，您可以通过运行route:list Artisan 命令随时快速查看应用程序的路由。

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

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

资源控制器处理的操作

动词	URI	操作	路由名称
GET	`/photos`	索引	photos.index
GET	`/photos/create`	创建	photos.create
POST	`/photos`	存储	photos.store
GET	`/photos/{photo}`	显示	photos.show
GET	`/photos/{photo}/edit`	编辑	photos.edit
PUT/PATCH	`/photos/{photo}`	更新	photos.update
DELETE	`/photos/{photo}`	删除	photos.destroy

#### 自定义未找到模型的行为

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

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 方法来指示框架允许软删除的模型：

use App\Http\Controllers\PhotoController;

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

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

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

指定资源模型

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

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

生成表单请求

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

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

部分资源路由

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

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 方法自动排除这两个路由：

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 方法的 API 资源控制器，可以在执行 make:controller 命令时使用 --api 开关：

php artisan make:controller PhotoController --api

嵌套资源

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

use App\Http\Controllers\PhotoCommentController;

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

此路由将注册一个嵌套资源，可以使用如下 URI 进行访问：

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

为嵌套资源设置范围

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

浅嵌套

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

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 数组来覆盖这些名称：

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 路由生成以下 URI：

/users/{admin_user}

设置资源路由的范围

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

use App\Http\Controllers\PhotoCommentController;

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

此路由将注册一个设置范围的嵌套资源，可以使用如下 URI 进行访问：

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

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

本地化资源 URI

默认情况下，Route::resource 将使用英语动词和复数规则创建资源 URI。如果您需要本地化 create（创建）和 edit（编辑）操作动词，可以使用 Route::resourceVerbs 方法。您可以在应用程序的 App\Providers\AppServiceProvider 的 boot 方法的开头进行此操作：

/**
 * 引导任何应用程序服务。
 */
public function boot(): void
{
    Route::resourceVerbs([
        'create' => 'crear',
        'edit' => 'editar',
    ]);
}

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

/publicacion/crear

/publicacion/{publicaciones}/editar

补充资源控制器

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

use App\Http\Controller\PhotoController;

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

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

单例资源控制器

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

use App\Http\Controllers\ProfileController;
use Illuminate\Support\Facades\Route;
 
Route::singleton('profile', ProfileController::class);

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

动词	URI	操作	路由名称
GET	`/profile`	显示	profile.show
GET	`/profile/edit`	编辑	profile.edit
PUT/PATCH	`/profile`	更新	profile.update

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

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

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

动词	URI	操作	路由名称
GET	`/photos/{photo}/thumbnail`	显示	photos.thumbnail.show
GET	`/photos/{photo}/thumbnail/edit`	编辑	photos.thumbnail.edit
PUT/PATCH	`/photos/{photo}/thumbnail`	更新	photos.thumbnail.update

可创建的单例资源

偶尔，您可能想要为单例资源定义创建和存储路由。要实现此目的，您可以在注册单例资源路由时调用 creatable 方法：

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

在此示例中，将注册以下路由。如您所见，对于可创建的单例资源，还将注册一个 DELETE 路由：

动词	URI	操作	路由名称
GET	`/photos/{photo}/thumbnail/create`	创建	photos.thumbnail.create
POST	`/photos/{photo}/thumbnail`	存储	photos.thumbnail.store
GET	`/photos/{photo}/thumbnail`	显示	photos.thumbnail.show
GET	`/photos/{photo}/thumbnail/edit`	编辑	photos.thumbnail.edit
PUT/PATCH	`/photos/{photo}/thumbnail`	更新	photos.thumbnail.update
DELETE	`/photos/{photo}/thumbnail`	销毁	photos.thumbnail.destroy

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

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

API 单例资源

apiSingleton 方法可用于注册将通过 API 进行操作的单例资源，因此不需要 create（创建）和 edit（编辑）路由：

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

当然，API 单例资源也可以是 creatable（可创建的），这将为资源注册 store（存储）和 destroy（销毁）路由：

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

依赖注入和控制器

构造函数注入

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

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

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

方法注入

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

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

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

use App\Http\Controllers\UserController;

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

您仍然可以键入提示 Illuminate\Http\Request 并通过如下定义控制器方法来访问您的 id 参数：

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

CSRF 保护 HTTP 请求