Laravel 中文文档

主题

控制器 ​

简介 ​

你可能希望使用「控制器」类来组织请求处理行为，而不是将所有请求处理逻辑定义为路由文件中的闭包。控制器可以将相关的请求处理逻辑分组到一个类中。例如，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

控制器不是必须继承基类。但是，继承一个包含应在所有控制器之间共享的方法的基控制器类有时会很方便。

单动作控制器 ​

如果控制器操作特别复杂，你可能会发现将整个控制器类专门用于该单个操作很方便。为此，你可以在控制器中定义一个 __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 发布进行自定义。

控制器 Middleware ​

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

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

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

php
<?php

namespace App\Http\Controllers;

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

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

    // ...
}

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

php
use Closure;
use Illuminate\Http\Request;

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

Middleware 属性 ​

你也可以使用 PHP 属性为控制器分配 middleware：

php
<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Attributes\Controllers\Middleware;

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

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

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()
    {
        // ...
    }
}

授权属性 ​

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

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

这个单一路由声明创建了多个路由来处理资源上的各种操作。生成的控制器已经为每个操作预置了方法。请记住，你始终可以通过运行 route:list Artisan 命令快速查看应用程序路由的概览。

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

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

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

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

资源控制器处理的操作 ​

HTTP 方法URI操作路由名称
GET/photosindexphotos.index
GET/photos/createcreatephotos.create
POST/photosstorephotos.store
GET/photos/{photo}showphotos.show
GET/photos/{photo}/editeditphotos.edit
PUT/PATCH/photos/{photo}updatephotos.update
DELETE/photos/{photo}destroyphotos.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();

此路由定义将定义以下路由：

HTTP 方法URI操作路由名称
GET/photos/{photo}/commentsindexphotos.comments.index
GET/photos/{photo}/comments/createcreatephotos.comments.create
POST/photos/{photo}/commentsstorephotos.comments.store
GET/comments/{comment}showcomments.show
GET/comments/{comment}/editeditcomments.edit
PUT/PATCH/comments/{comment}updatecomments.update
DELETE/comments/{comment}destroycomments.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
/**
 * 引导任何应用程序服务。
 */
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);

NOTE

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

单例资源控制器 ​

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

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

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

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

HTTP 方法URI操作路由名称
GET/profileshowprofile.show
GET/profile/editeditprofile.edit
PUT/PATCH/profileupdateprofile.update

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

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

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

HTTP 方法URI操作路由名称
GET/photos/{photo}/thumbnailshowphotos.thumbnail.show
GET/photos/{photo}/thumbnail/editeditphotos.thumbnail.edit
PUT/PATCH/photos/{photo}/thumbnailupdatephotos.thumbnail.update

可创建的单例资源 ​

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

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

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

HTTP 方法URI操作路由名称
GET/photos/{photo}/thumbnail/createcreatephotos.thumbnail.create
POST/photos/{photo}/thumbnailstorephotos.thumbnail.store
GET/photos/{photo}/thumbnailshowphotos.thumbnail.show
GET/photos/{photo}/thumbnail/editeditphotos.thumbnail.edit
PUT/PATCH/photos/{photo}/thumbnailupdatephotos.thumbnail.update
DELETE/photos/{photo}/thumbnaildestroyphotos.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();

Middleware 与资源控制器 ​

Laravel 允许你使用 middleware、middlewareFor 和 withoutMiddlewareFor 方法将 middleware 分配给资源路由的所有或特定方法。这些方法提供了对每个资源操作应用哪些 middleware 的细粒度控制。

将 Middleware 应用于所有方法 ​

你可以使用 middleware 方法将 middleware 分配给资源或单例资源路由生成的所有路由：

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

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

将 Middleware 应用于特定方法 ​

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

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

从特定方法排除 Middleware ​

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

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
{
    /**
     * 创建新的控制器实例。
     */
    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');
    }
}