# 控制器

-   [简介](#introduction)
-   [编写控制器](#writing-controllers)
    -   [基础控制器](#basic-controllers)
    -   [单动作控制器](#single-action-controllers)
-   [控制器中间件](#controller-middleware)
    -   [中间件属性](#middleware-attributes)
    -   [授权属性](#authorization-attributes)
-   [资源控制器](#resource-controllers)
    -   [部分资源路由](#restful-partial-resource-routes)
    -   [嵌套资源](#restful-nested-resources)
    -   [命名资源路由](#restful-naming-resource-routes)
    -   [命名资源路由参数](#restful-naming-resource-route-parameters)
    -   [作用域限定资源路由](#restful-scoping-resource-routes)
    -   [本地化资源 URI](#restful-localizing-resource-uris)
    -   [补充资源控制器](#restful-supplementing-resource-controllers)
    -   [单例资源控制器](#singleton-resource-controllers)
    -   [中间件与资源控制器](#middleware-and-resource-controllers)
-   [依赖注入与控制器](#dependency-injection-and-controllers)

## 简介

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

> [!注意]
> 控制器并**不要求**继承基类。不过，有时继承一个包含应在所有控制器之间共享的方法的基础控制器类会很方便。

### 单动作控制器

如果某个控制器动作特别复杂，你可能会发现将整个控制器类专门用于这一个动作会很方便。要实现这一点，你可以在控制器中定义一个单独的 `__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
```

> [!注意]
> 可以使用 [stub 发布](/docs/laravel/13.x/artisan#stub-customization) 来自定义控制器 stub。

## 控制器中间件

可以在路由文件中将[中间件](/docs/laravel/13.x/middleware)分配给控制器的路由：

```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
{
    /**
     * 获取应分配给该控制器的中间件。
     */
    public static function middleware(): array
    {
        return [
            'auth',
            new Middleware('log', only: ['index']),
            new Middleware('subscribed', except: ['store']),
        ];
    }

    // ...
}
```

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

```php
use Closure;
use Illuminate\Http\Request;

/**
 * 获取应分配给该控制器的中间件。
 */
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()
    {
        // ...
    }
}
```



### 授权属性

如果您通过策略（policies）对控制器操作进行授权，可以使用 `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)
    {
        // ...
    }
}
```

第一个参数是您希望授权的能力（ability）。第二个参数是应传递给策略的模型类、路由参数或参数集合。

## 资源控制器（Resource Controllers）

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

#### 资源控制器处理的操作

<div class="overflow-auto">

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

</div>

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

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



#### 软删除模型

通常情况下，隐式模型绑定不会检索已被[软删除](https://www.qianwen.com/docs/laravel/13.x/eloquent#soft-deleting)的模型，而是会返回 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']);
```

#### 指定资源模型

如果您正在使用[路由模型绑定](https://www.qianwen.com/docs/laravel/13.x/routing#route-model-binding)，并且希望资源控制器的方法对模型实例进行类型提示，您可以在生成控制器时使用 `--model` 选项：

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

#### 生成表单请求

在生成资源控制器时，您可以提供 `--requests` 选项，以指示 Artisan 为该控制器的存储（storage）和更新（update）方法生成[表单请求类](https://www.qianwen.com/docs/laravel/13.x/validation#form-request-validation)：

```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 的[隐式模型绑定](/docs/laravel/13.x/routing#implicit-model-binding-scoping)功能可以自动限定嵌套绑定的作用域，从而确认解析出的子模型属于父模型。通过在定义嵌套资源时使用 `scoped` 方法，你可以启用自动作用域限定，并指示 Laravel 应通过哪个字段检索子资源。有关如何完成此操作的更多信息，请参阅[限定资源路由作用域](#restful-scoping-resource-routes)文档。



#### 浅层嵌套

通常，URI 中并不完全需要同时包含父级 ID 和子级 ID，因为子级 ID 本身已经是唯一标识符。当使用自动递增主键等唯一标识符在 URI 片段中识别模型时，你可以选择使用“浅层嵌套”：

```php
use App\Http\Controllers\CommentController;

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

该路由定义将会定义以下路由：

<div class="overflow-auto">

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

</div>

### 命名资源路由

默认情况下，所有资源控制器动作都有一个路由名称；不过，你可以通过传入包含所需路由名称的 `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 的[作用域限定隐式模型绑定](/docs/laravel/13.x/routing#implicit-model-binding-scoping)功能可以自动对嵌套绑定进行作用域限定，以确认解析出的子模型属于父模型。通过在定义嵌套资源时使用 `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 会自动限定查询范围，通过父模型来检索嵌套模型，并使用约定来猜测父模型上的关系名称。在这个例子中，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 的复数化工具支持[多种不同的语言，你可以根据自己的需求进行配置](/docs/laravel/13.x/localization#pluralization-language)。一旦动词和复数化语言被自定义，像 `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);
```

> [!注意]
> 请记住保持控制器职责集中。如果你发现自己经常需要典型资源动作集合之外的方法，请考虑将控制器拆分为两个更小的控制器。

### 单例资源控制器

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

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

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

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

<div class="overflow-auto">

| Verb      | URI             | Action | Route Name     |
| --------- | --------------- | ------ | -------------- |
| GET       | `/profile`      | show   | profile.show   |
| GET       | `/profile/edit` | edit   | profile.edit   |
| PUT/PATCH | `/profile`      | update | profile.update |

</div>



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

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

在此示例中，`photos` 资源将获得所有[标准资源路由](#actions-handled-by-resource-controllers)；不过，`thumbnail` 资源将是一个单例资源，并具有以下路由：

<div class="overflow-auto">

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

</div>

#### 可创建的单例资源

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

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

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

<div class="overflow-auto">

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

</div>

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

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

<a name="api-singleton-resources"></a>


#### 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 [服务容器](/docs/laravel/13.x/container) 用于解析所有 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');
    }
}
```