控制器

介绍

如果你不想在路由文件中定义所有的请求处理逻辑闭包，你可以考虑使用 “控制器” 类来组织这些行为。控制器可以将相关的请求处理逻辑分组到一个类中。例如，一个 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 方法将被调用，并且路由参数将传递给该方法。

控制器不需要继承基础类。然而，有时将基础控制器类扩展到所有控制器中是很方便的，这样可以在基础控制器中包含一些共享的方法。

单一操作控制器

如果一个控制器操作特别复杂，你可能会觉得将整个控制器类专门用于这个单一操作更加方便。为此，你可以在控制器中定义一个单一的 __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

控制器的模板可以通过 发布存根 来进行自定义。

控制器中间件

你可以在路由文件中为控制器的路由分配【中间件】：

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 Action 路由名称

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

自定义缺失模型的行为

通常，如果隐式绑定的资源模型未找到，Laravel 会生成 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。为此，Laravel 提供了 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 本身已经是唯一标识符。使用像自增主键这样的唯一标识符来标识模型时，你可以选择使用 “浅层嵌套”：

use App\Http\Controllers\CommentController;

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

这个路由定义会定义以下路由：

动作 URI Action 路由名称

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\Controllers\PhotoController;

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

记住要保持控制器的聚焦。如果你发现自己经常需要在典型的资源动作集之外定义方法，可以考虑将控制器拆分为两个更小的控制器。

单例资源控制器

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

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

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

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

动作 URI Action 路由名称

GET

/profile

show

profile.show

GET

/profile/edit

edit

profile.edit

PUT/PATCH

/profile

update

profile.update

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

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

在这个例子中，photos 资源会接收所有【标准的资源路由】；然而，thumbnail 资源将是一个单例资源，注册如下的路由：

动作 URI Action 路由名称

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 方法：

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

在这个例子中，将注册以下路由。可以看到，DELETE 路由也会为可创建的单例资源注册：

动作 URI Action 路由名称

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 方法：

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