控制器

简介

与其在路由文件中以闭包的形式定义所有请求处理逻辑，你可能希望使用“控制器”类来组织这些行为。控制器可以将相关的请求处理逻辑聚合到一个类中。例如，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 Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;

class UserController 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);
        },
    ];
}

中间件属性

你也可以使用 PHP 属性将中间件分配给控制器：

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Controllers\Middleware;

#[Middleware('auth')]
#[Middleware('log', only: ['index'])]
#[Middleware('subscribed', except: ['store'])]
class UserController
{
    // ...
}

你也可以将中间件属性放在单个控制器方法上。分配给方法的中间件将与在类级别分配的中间件合并：

<?php

namespace App\Http\Controllers;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Routing\Attributes\Controllers\Middleware;

#[Middleware('auth')]
class UserController
{
    #[Middleware('log')]
    #[Middleware('subscribed')]
    public function index()
    {
        // ...
    }

    #[Middleware(static function (Request $request, Closure $next) {
        // ...

        return $next($request);
    })]
    public function store()
    {
        // ...
    }
}

要从控制器或单个控制器方法中排除中间件，请使用 WithoutMiddleware 属性。你可以使用 only 和 except 参数将类级属性限制为特定的控制器方法：

<?php

namespace App\Http\Controllers;

use App\Http\Middleware\EnsureTokenIsValid;
use Illuminate\Routing\Attributes\Controllers\WithoutMiddleware;

#[WithoutMiddleware('subscribed', except: ['index'])]
class UserController
{
    #[WithoutMiddleware(EnsureTokenIsValid::class)]
    public function index()
    {
        // ...
    }

    public function show()
    {
        // ...
    }
}

类级别的 WithoutMiddleware 属性会被子控制器继承。该属性只能移除路由中间件，不适用于全局中间件。

授权属性

如果你通过策略对控制器操作进行授权，可以使用 Authorize 属性作为 can 中间件的便捷快捷方式：

<?php

namespace App\Http\Controllers;

use App\Models\Comment;
use App\Models\Post;
use Illuminate\Routing\Attributes\Controllers\Authorize;

class CommentController
{
    #[Authorize('create', [Comment::class, 'post'])]
    public function store(Post $post)
    {
        // ...
    }

    #[Authorize('delete', 'comment')]
    public function destroy(Comment $comment)
    {
        // ...
    }
}

第一个参数是你要授权的能力。第二个参数是要传递给策略的模型类、路由参数或参数。

资源控制器

如果你将应用程序中的每个 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,
]);

softDeletableResources 方法注册多个资源控制器，这些控制器都使用 withTrashed 方法：

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

资源控制器处理的操作

自定义未找到模型的行为

通常情况下，如果隐式绑定的资源模型未找到，会生成 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

嵌套资源

有时你可能需要为嵌套资源定义路由。例如，一个 photo 资源可能拥有多条可附加到该照片的评论。若要嵌套资源控制器，可在路由声明中使用“点”语法：

use App\Http\Controllers\PhotoCommentController;

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

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

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

限定嵌套资源范围

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

浅层嵌套

由于子 ID 本身就是唯一标识符，URI 中通常无需同时包含父 ID 和子 ID。当在 URI 片段中使用诸如自增主键的唯一标识符来标识模型时，可以选择使用“浅层嵌套”：

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 路由生成如下 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 方法开头完成此操作：

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Route::resourceVerbs([
        'create' => 'crear',
        'edit' => 'editar',
    ]);
}

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

/publicacion/crear

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

上述单例资源定义将注册以下路由。可以看到，单例资源不会注册“创建”路由，且由于资源只能存在一个实例，注册的路由不接受标识符：

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

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

在此示例中，photos 资源将获得所有标准资源路由；而 thumbnail 资源将是单例资源，包含以下路由：

可创建的单例资源

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

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

在此示例中，将注册以下路由。可以看到，可创建的单例资源还会注册 DELETE 路由：

如果你希望 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 允许你使用 middleware、middlewareFor 和 withoutMiddlewareFor 方法，为资源路由的所有方法或仅特定方法分配中间件。这些方法可以对应用到每个资源动作的中间件进行细粒度控制。

对所有方法应用中间件

可以使用 middleware 方法，为资源或单例资源路由生成的所有路由分配中间件：

Route::resource('users', UserController::class)
    ->middleware(['auth', 'verified']);

Route::singleton('profile', ProfileController::class)
    ->middleware('auth');

对特定方法应用中间件

可以使用 middlewareFor 方法，为给定资源控制器的一个或多个特定方法分配中间件：

Route::resource('users', UserController::class)
    ->middlewareFor('show', 'auth');

Route::apiResource('users', UserController::class)
    ->middlewareFor(['show', 'update'], 'auth');

Route::resource('users', UserController::class)
    ->middlewareFor('show', 'auth')
    ->middlewareFor('update', 'auth');

Route::apiResource('users', UserController::class)
    ->middlewareFor(['show', 'update'], ['auth', 'verified']);

middlewareFor 方法也可以与单例和 API 单例资源控制器结合使用：

Route::singleton('profile', ProfileController::class)
    ->middlewareFor('show', 'auth');

Route::apiSingleton('profile', ProfileController::class)
    ->middlewareFor(['show', 'update'], 'auth');

从特定方法中排除中间件

可以使用 withoutMiddlewareFor 方法，从资源控制器的特定方法中排除中间件：

Route::middleware(['auth', 'verified', 'subscribed'])->group(function () {
    Route::resource('users', UserController::class)
        ->withoutMiddlewareFor('index', ['auth', 'verified'])
        ->withoutMiddlewareFor(['create', 'store'], 'verified')
        ->withoutMiddlewareFor('destroy', 'subscribed');
});

依赖注入与控制器

构造函数注入

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

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * Create a new controller instance.
     */
    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
{
    /**
     * Store a new user.
     */
    public function store(Request $request): RedirectResponse
    {
        $name = $request->name;

        // Store the user...

        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
{
    /**
     * Update the given user.
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // Update the user...

        return redirect('/users');
    }
}