控制器

简介

与其在路由文件中把全部请求处理逻辑都写成闭包，你可能更希望用「控制器」类来组织这些行为。控制器可以把相关的请求处理逻辑归到同一个类中。例如，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
{
    /**
     * Show the profile for a given user.
     */
    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 方法，并将路由参数传给该方法。

INFO

控制器并非必须扩展基类。不过，有时扩展一个包含应在全部控制器间共享方法的基类控制器会更方便。

单动作控制器

若某个控制器动作特别复杂，你可能会觉得把整个控制器类专门用于该单一动作更方便。为此，可以在控制器中定义单个 __invoke 方法：

php

<?php

namespace App\Http\Controllers;

class ProvisionServer extends Controller
{
    /**
     * Provision a new web server.
     */
    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

INFO

控制器 stub 可通过发布 stub 进行自定义。

控制器中间件

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

php

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

或者，你可能更方便在控制器类中指定中间件。为此，控制器应实现 HasMiddleware 接口，该接口要求控制器具有静态 middleware 方法。从此方法中，你可以返回应应用于控制器动作的中间件数组：

php

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;

class UserController implements HasMiddleware
{
    /**
     * Get the middleware that should be assigned to the controller.
     */
    public static function middleware(): array
    {
        return [
            'auth',
            new Middleware('log', only: ['index']),
            new Middleware('subscribed', except: ['store']),
        ];
    }

    // ...
}

你也可以将控制器中间件定义为闭包，从而在不编写完整中间件类的情况下便捷地定义内联中间件：

php

use Closure;
use Illuminate\Http\Request;

/**
 * Get the middleware that should be assigned to the controller.
 */
public static function middleware(): array
{
    return [
        function (Request $request, Closure $next) {
            return $next($request);
        },
    ];
}

中间件属性

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

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

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

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

<?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 选项快速创建处理这些动作的控制器：

shell

php artisan make:controller PhotoController --resource

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

php

use App\Http\Controllers\PhotoController;

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

这一条路由声明会创建多条路由，用于处理该资源上的各种动作。生成的控制器已经为每个动作准备了方法 stub。请记住，你随时可以通过运行 route:list Artisan 命令快速查看应用的路由概览。

你甚至可以通过向 resources 方法传入数组，一次注册多个资源控制器：

php

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

softDeletableResources 方法会注册多个都使用 withTrashed 方法的资源控制器：

php

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

资源控制器处理的动作

Verb	URI	Action	Route Name
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 访问：

text

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

约束嵌套资源

Laravel 的隐式模型绑定功能可以自动约束嵌套绑定，从而确认解析出的子模型属于父模型。在定义嵌套资源时使用 scoped 方法，即可启用自动约束，并指示 Laravel 应按哪个字段检索子资源。更多说明请参阅约束资源路由文档。

浅层嵌套

通常，URI 中不必同时包含父级和子级 ID，因为子级 ID 本身已是唯一标识符。当使用自增主键等唯一标识符在 URI 段中标识模型时，可以选择使用「浅层嵌套」：

php

use App\Http\Controllers\CommentController;

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

该路由定义会注册如下路由：

Verb	URI	Action	Route Name
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：

text

/users/{admin_user}

约束资源路由

Laravel 的作用域隐式模型绑定功能可以自动约束嵌套绑定，从而确认解析出的子模型属于父模型。在定义嵌套资源时使用 scoped 方法，即可启用自动约束，并指示 Laravel 应按哪个字段检索子资源：

php

use App\Http\Controllers\PhotoCommentController;

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

该路由会注册一个带约束的嵌套资源，可通过如下 URI 访问：

text

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

当使用自定义键的隐式绑定作为嵌套路由参数时，Laravel 会按约定猜测父模型上的关联名称，并自动约束查询以通过父模型检索嵌套模型。在本例中，会假定 Photo 模型有一个名为 comments（路由参数名的复数形式）的关联，可用于检索 Comment 模型。

本地化资源 URI

默认情况下，Route::resource 会使用英语动词和复数规则创建资源 URI。若需要本地化 create 和 edit 动作动词，可以使用 Route::resourceVerbs 方法。这可以在应用的 App\Providers\AppServiceProvider 的 boot 方法开头完成：

php

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

Laravel 的复数化器支持多种语言，你可根据需要配置。自定义动词和复数语言后，诸如 Route::resource('publicacion', PublicacionController::class) 的资源路由注册会生成如下 URI：

text

/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);

INFO

请记住让控制器保持专注。若你经常需要典型资源动作集之外的方法，可考虑将控制器拆成两个更小的控制器。

单例资源控制器

有时，应用中的某些资源只能有一个实例。例如，用户的「个人资料」可以编辑或更新，但用户不能有多个「个人资料」。同样，一张图片可能只有一个「缩略图」。这类资源称为「单例资源」，意味着该资源有且仅有一个实例。在这些场景下，你可以注册「单例」资源控制器：

php

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

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

上面的单例资源定义会注册如下路由。可以看到，单例资源不会注册「创建」路由，且注册的路由不接受标识符，因为该资源只能有一个实例：

Verb	URI	Action	Route Name
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 资源则是具有如下路由的单例资源：

Verb	URI	Action	Route Name
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 路由：

Verb	URI	Action	Route Name
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 允许你使用 middleware、middlewareFor 和 withoutMiddlewareFor 方法，将中间件分配给资源路由的全部或仅特定方法。这些方法提供了对每个资源动作所应用中间件的细粒度控制。

将中间件应用于所有方法

你可以使用 middleware 方法，将中间件分配给资源或单例资源路由生成的全部路由：

php

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

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

将中间件应用于特定方法

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

php

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 单例资源控制器一起使用：

php

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

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

从特定方法排除中间件

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

php

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

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

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

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

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

        return redirect('/users');
    }
}

控制器 ​

简介 ​

编写控制器 ​

基础控制器 ​

单动作控制器 ​

控制器中间件 ​

中间件属性 ​

授权属性 ​

资源控制器 ​

资源控制器处理的动作 ​

自定义模型缺失时的行为 ​

软删除模型 ​

指定资源模型 ​

生成表单请求 ​

部分资源路由 ​

API 资源路由 ​

嵌套资源 ​

约束嵌套资源 ​

浅层嵌套 ​

命名资源路由 ​

命名资源路由参数 ​

约束资源路由 ​

本地化资源 URI ​

补充资源控制器 ​

单例资源控制器 ​

可创建的单例资源 ​

API 单例资源 ​

中间件与资源控制器 ​

将中间件应用于所有方法 ​

将中间件应用于特定方法 ​

从特定方法排除中间件 ​

依赖注入与控制器 ​

构造函数注入 ​

方法注入 ​

控制器

简介

编写控制器

基础控制器

单动作控制器

控制器中间件

中间件属性

授权属性

资源控制器

资源控制器处理的动作

自定义模型缺失时的行为

软删除模型

指定资源模型

生成表单请求

部分资源路由

API 资源路由

嵌套资源

约束嵌套资源

浅层嵌套

命名资源路由

命名资源路由参数

约束资源路由

本地化资源 URI

补充资源控制器

单例资源控制器

可创建的单例资源

API 单例资源

中间件与资源控制器

将中间件应用于所有方法

将中间件应用于特定方法

从特定方法排除中间件

依赖注入与控制器

构造函数注入

方法注入