Appearance
控制器
介绍
与其将所有请求处理逻辑定义为路由文件中的闭包，不如使用 “controller” 类来组织此行为。控制器可以将相关的请求处理逻辑分组到单个类中。例如，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 方法，并将路由参数传递给该方法。
NOTE
控制器不需要扩展基类。但是，有时扩展包含应在所有控制器之间共享的方法的基控制器类很方便。
单作用控制器
如果控制器操作特别复杂，您可能会发现将整个控制器类专用于该单个操作很方便。为此，您可以在 controller 中定义一个 __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 --invokableNOTE
可以使用 stub publishing 自定义 Controller stub。
控制器中间件
中间件可以在你的路由文件中分配给控制器的路由：
php
Route::get('/profile', [UserController::class, 'show'])->middleware('auth');或者，你可能会发现在 controller 类中指定 middleware 很方便。为此，你的控制器应该实现 HasMiddleware 接口，它规定控制器应该有一个静态中间件方法。从此方法中，您可以返回一个应该应用于控制器操作的中间件数组：
php
<?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']),
];
}
// ...
}你也可以将控制器中间件定义为闭包，这提供了一种定义内联中间件的便捷方法，而无需编写整个中间件类：
php
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 选项快速创建一个控制器来处理这些操作：
shell
php artisan make:controller PhotoController --resource此命令将在 生成一个控制器 app/Http/Controllers/PhotoController.php 。控制器将包含每个可用资源操作的方法。接下来，您可以注册一个指向控制器的资源路由：
php
use App\Http\Controllers\PhotoController;
Route::resource('photos', PhotoController::class);此单个路由声明创建多个路由来处理对资源的各种操作。生成的控制器已经为每个操作创建了 method。请记住，您始终可以通过运行 route:list Artisan 命令来快速了解应用程序的路由。
你甚至可以通过将数组传递给 resources 方法来一次注册多个资源控制器：
php
Route::resources([
'photos' => PhotoController::class,
'posts' => PostController::class,
]);资源控制器处理的操作
| 动词 | URI | 动作 | 路由名称 |
|---|---|---|---|
| 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 方法来自定义此行为。缺少的方法接受一个闭包，如果找不到任何资源路由的隐式绑定模型，将调用该闭包：
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 为控制器的 storage 和 update 方法生成表单请求类：
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 资源控制器：
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嵌套资源
有时，您可能需要定义到嵌套资源的路由。例如，照片资源可能具有多个可能附加到照片的评论。要嵌套资源控制器，您可以在路由声明中使用 “dot” 表示法：
php
use App\Http\Controllers\PhotoCommentController;
Route::resource('photos.comments', PhotoCommentController::class);此路由将注册一个嵌套资源，该资源可通过 URI 访问，如下所示：
php
/photos/{photo}/comments/{comment}确定嵌套资源的范围
Laravel 的隐式模型绑定功能可以自动确定嵌套绑定的范围，以便确认解析的子模型属于父模型。通过在定义嵌套资源时使用 scoped 方法，您可以启用自动范围，并指示 Laravel 应通过哪个字段检索子资源。有关如何完成此操作的更多信息，请参阅有关界定资源路由的文档。
浅层嵌套
通常，在 URI 中同时具有父 ID 和子 ID 并不完全必要，因为子 ID 已经是唯一标识符。当使用唯一标识符（例如自动递增主键）来识别 URI 分段中的模型时，您可以选择使用 “浅层嵌套”：
php
use App\Http\Controllers\CommentController;
Route::resource('photos.comments', CommentController::class)->shallow();此路由定义将定义以下路由：
| 动词 | URI | 行为 | 路由名称 |
|---|---|---|---|
| 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 将根据资源名称的 “singularized” 版本为您的资源路由创建路由参数。您可以使用 parameters 方法轻松覆盖每个资源。传递给 parameters 方法的数组应该是资源名称和参数名称的关联数组：
php
use App\Http\Controllers\AdminUserController;
Route::resource('users', AdminUserController::class)->parameters([
'users' => 'admin_user'
]);上面的示例为资源的 show 路由生成以下 URI：
php
/users/{admin_user}确定资源路由的范围
Laravel 的 scoped implicit model binding 功能可以自动确定嵌套绑定的范围，从而确认解析的子模型属于父模型。通过在定义嵌套资源时使用 scoped 方法，您可以启用自动范围，并指示 Laravel 应通过哪个字段检索子资源：
php
use App\Http\Controllers\PhotoCommentController;
Route::resource('photos.comments', PhotoCommentController::class)->scoped([
'comment' => 'slug',
]);此路由将注册一个范围的嵌套资源，该资源可以使用 URI 进行访问，如下所示：
php
/photos/{photo}/comments/{comment:slug}当使用自定义键控隐式绑定作为嵌套路由参数时，Laravel 将自动确定查询范围，以使用约定猜测父级上的关系名称，按其父级检索嵌套模型。在这种情况下，将假设 Photo 模型具有名为 comments（路由参数名称的复数形式）的关系，该关系可用于检索 Comment 模型。
本地化资源 URI
默认情况下，Route::resource 将使用英文动词和复数规则创建资源 URI。如果需要本地化创建 和 编辑操作动词，可以使用 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：
php
/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
请记住让您的控制器保持专注。如果您发现自己经常需要典型资源操作集之外的方法，请考虑将控制器拆分为两个较小的控制器。
单例资源控制器
有时，您的应用程序将具有可能只有一个实例的资源。例如，可以编辑或更新用户的“个人资料”，但用户不能拥有多个“个人资料”。同样，图像可能只有一个 “缩略图”。这些资源称为 “单一实例资源”，这意味着可能存在资源的一个且只有一个实例。在这些情况下，您可以注册一个 “singleton” 资源控制器：
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 资源将是具有以下路由的 Singleton 资源：
| 动词 | URI | 行动 | 路由名称 |
|---|---|---|---|
| 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 路由：
| 动词 | URI | 行动 | 路由名称 |
|---|---|---|---|
| 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 操作的单例资源，从而使创建和``编辑路由变得不必要：
php
Route::apiSingleton('profile', ProfileController::class);当然，API 单例资源也可以是可创建的，这将为资源注册 store 和 destroy 路由：
php
Route::apiSingleton('photos.thumbnail', ProfileController::class)->creatable();依赖关系注入和控制器
构造函数注入
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 进行 type-hint 操作，并通过定义控制器方法来访问你的 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');
}
}