控制器
简介
除了在路由文件中将所有请求处理逻辑定义为闭包之外,您可能希望使用“控制器”类来组织此行为。控制器可以将相关的请求处理逻辑分组到一个类中。例如,一个 UserController
类可以处理所有与用户相关的传入请求,包括显示、创建、更新和删除用户。默认情况下,控制器存储在 app/Http/Controllers
目录中。
编写控制器
基本控制器
要快速生成一个新的控制器,您可以运行 make:controller
Artisan 命令。默认情况下,应用程序的所有控制器都存储在 app/Http/Controllers
目录中
1php artisan make:controller UserController
让我们看一个基本控制器的例子。一个控制器可以有任意数量的公共方法来响应传入的 HTTP 请求
1<?php 2 3namespace App\Http\Controllers; 4 5use App\Models\User; 6use Illuminate\View\View; 7 8class UserController extends Controller 9{10 /**11 * Show the profile for a given user.12 */13 public function show(string $id): View14 {15 return view('user.profile', [16 'user' => User::findOrFail($id)17 ]);18 }19}
一旦您编写了一个控制器类和方法,您可以像这样定义一个指向控制器方法的路由
1use App\Http\Controllers\UserController;2 3Route::get('/user/{id}', [UserController::class, 'show']);
当传入的请求与指定的路由 URI 匹配时,将调用 App\Http\Controllers\UserController
类上的 show
方法,并将路由参数传递给该方法。
控制器并非 必须 继承基类。但是,有时继承一个包含应在所有控制器之间共享的方法的基控制器类会很方便。
单一行为控制器
如果控制器操作特别复杂,您可能会发现将整个控制器类专用于该单一操作会很方便。为了实现这一点,您可以在控制器中定义一个 __invoke
方法
1<?php 2 3namespace App\Http\Controllers; 4 5class ProvisionServer extends Controller 6{ 7 /** 8 * Provision a new web server. 9 */10 public function __invoke()11 {12 // ...13 }14}
当为单一行为控制器注册路由时,您无需指定控制器方法。相反,您可以简单地将控制器的名称传递给路由器
1use App\Http\Controllers\ProvisionServer;2 3Route::post('/server', ProvisionServer::class);
您可以使用 make:controller
Artisan 命令的 --invokable
选项生成一个可调用控制器
1php artisan make:controller ProvisionServer --invokable
控制器存根可以使用 存根发布 进行自定义。
控制器中间件
中间件 可以在您的路由文件中分配给控制器的路由
1Route::get('/profile', [UserController::class, 'show'])->middleware('auth');
或者,您可能会发现在您的控制器类中指定中间件很方便。为此,您的控制器应实现 HasMiddleware
接口,该接口规定控制器应具有静态 middleware
方法。通过此方法,您可以返回应应用于控制器操作的中间件数组
1<?php 2 3namespace App\Http\Controllers; 4 5use App\Http\Controllers\Controller; 6use Illuminate\Routing\Controllers\HasMiddleware; 7use Illuminate\Routing\Controllers\Middleware; 8 9class UserController extends Controller implements HasMiddleware10{11 /**12 * Get the middleware that should be assigned to the controller.13 */14 public static function middleware(): array15 {16 return [17 'auth',18 new Middleware('log', only: ['index']),19 new Middleware('subscribed', except: ['store']),20 ];21 }22 23 // ...24}
您还可以将控制器中间件定义为闭包,这提供了一种方便的方式来定义内联中间件,而无需编写整个中间件类
1use Closure; 2use Illuminate\Http\Request; 3 4/** 5 * Get the middleware that should be assigned to the controller. 6 */ 7public static function middleware(): array 8{ 9 return [10 function (Request $request, Closure $next) {11 return $next($request);12 },13 ];14}
实现 Illuminate\Routing\Controllers\HasMiddleware
的控制器不应扩展 Illuminate\Routing\Controller
。
资源控制器
如果您将应用程序中的每个 Eloquent 模型都视为“资源”,则通常会对应用程序中的每个资源执行相同的操作集。例如,假设您的应用程序包含一个 Photo
模型和一个 Movie
模型。用户很可能可以创建、读取、更新或删除这些资源。
由于这种常见的用例,Laravel 资源路由使用单行代码将典型的创建、读取、更新和删除(“CRUD”)路由分配给控制器。为了开始,我们可以使用 make:controller
Artisan 命令的 --resource
选项来快速创建一个控制器来处理这些操作
1php artisan make:controller PhotoController --resource
此命令将在 app/Http/Controllers/PhotoController.php
中生成一个控制器。该控制器将包含每个可用资源操作的方法。接下来,您可以注册一个指向控制器的资源路由
1use App\Http\Controllers\PhotoController;2 3Route::resource('photos', PhotoController::class);
这个单一的路由声明创建了多个路由来处理资源上的各种操作。生成的控制器已经为每个操作存根了方法。请记住,您始终可以通过运行 route:list
Artisan 命令快速概览应用程序的路由。
您甚至可以通过将数组传递给 resources
方法一次注册多个资源控制器
1Route::resources([2 'photos' => PhotoController::class,3 'posts' => PostController::class,4]);
资源控制器处理的操作
动词 | 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
方法来自定义此行为。如果找不到任何资源的隐式绑定模型,将调用 missing
方法接受的闭包
1use App\Http\Controllers\PhotoController;2use Illuminate\Http\Request;3use Illuminate\Support\Facades\Redirect;4 5Route::resource('photos', PhotoController::class)6 ->missing(function (Request $request) {7 return Redirect::route('photos.index');8 });
软删除模型
通常,隐式模型绑定不会检索已 软删除 的模型,而是返回 404 HTTP 响应。但是,您可以指示框架通过在定义资源路由时调用 withTrashed
方法来允许软删除模型
1use App\Http\Controllers\PhotoController;2 3Route::resource('photos', PhotoController::class)->withTrashed();
不带任何参数调用 withTrashed
将允许 show
、edit
和 update
资源路由的软删除模型。您可以通过将数组传递给 withTrashed
方法来指定这些路由的子集
1Route::resource('photos', PhotoController::class)->withTrashed(['show']);
指定资源模型
如果您正在使用 路由模型绑定 并且希望资源控制器的方法类型提示模型实例,您可以在生成控制器时使用 --model
选项
1php artisan make:controller PhotoController --model=Photo --resource
生成表单请求
您可以在生成资源控制器时提供 --requests
选项,以指示 Artisan 为控制器的存储和更新方法生成 表单请求类
1php artisan make:controller PhotoController --model=Photo --resource --requests
局部资源路由
在声明资源路由时,您可以指定控制器应处理的操作子集,而不是全套默认操作
1use App\Http\Controllers\PhotoController;2 3Route::resource('photos', PhotoController::class)->only([4 'index', 'show'5]);6 7Route::resource('photos', PhotoController::class)->except([8 'create', 'store', 'update', 'destroy'9]);
API 资源路由
当声明将由 API 使用的资源路由时,您通常希望排除呈现 HTML 模板的路由,例如 create
和 edit
。为了方便起见,您可以使用 apiResource
方法自动排除这两个路由
1use App\Http\Controllers\PhotoController;2 3Route::apiResource('photos', PhotoController::class);
您可以通过将数组传递给 apiResources
方法一次注册多个 API 资源控制器
1use App\Http\Controllers\PhotoController;2use App\Http\Controllers\PostController;3 4Route::apiResources([5 'photos' => PhotoController::class,6 'posts' => PostController::class,7]);
要快速生成不包含 create
或 edit
方法的 API 资源控制器,请在执行 make:controller
命令时使用 --api
开关
1php artisan make:controller PhotoController --api
嵌套资源
有时您可能需要为嵌套资源定义路由。例如,照片资源可能具有可以附加到照片的多个评论。要嵌套资源控制器,您可以在路由声明中使用“点”表示法
1use App\Http\Controllers\PhotoCommentController;2 3Route::resource('photos.comments', PhotoCommentController::class);
此路由将注册一个嵌套资源,可以使用如下 URI 访问
1/photos/{photo}/comments/{comment}
作用域嵌套资源
Laravel 的 隐式模型绑定 功能可以自动作用域嵌套绑定,以便确认已解析的子模型属于父模型。通过在定义嵌套资源时使用 scoped
方法,您可以启用自动作用域,并指示 Laravel 应通过哪个字段检索子资源。有关如何实现此操作的更多信息,请参阅 作用域资源路由 的文档。
浅层嵌套
通常,URI 中同时包含父 ID 和子 ID 并不是完全必要的,因为子 ID 已经是一个唯一标识符。当使用唯一标识符(例如自动递增主键)在 URI 段中标识模型时,您可以选择使用“浅层嵌套”
1use App\Http\Controllers\CommentController;2 3Route::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
数组来覆盖这些名称
1use App\Http\Controllers\PhotoController;2 3Route::resource('photos', PhotoController::class)->names([4 'create' => 'photos.build'5]);
命名资源路由参数
默认情况下,Route::resource
将基于资源名称的“单数化”版本为资源路由创建路由参数。您可以使用 parameters
方法轻松地按每个资源覆盖此设置。传递到 parameters
方法的数组应为资源名称和参数名称的关联数组
1use App\Http\Controllers\AdminUserController;2 3Route::resource('users', AdminUserController::class)->parameters([4 'users' => 'admin_user'5]);
上面的示例为资源的 show
路由生成了以下 URI
1/users/{admin_user}
作用域资源路由
Laravel 的 作用域隐式模型绑定 功能可以自动作用域嵌套绑定,以便确认已解析的子模型属于父模型。通过在定义嵌套资源时使用 scoped
方法,您可以启用自动作用域,并指示 Laravel 应通过哪个字段检索子资源
1use App\Http\Controllers\PhotoCommentController;2 3Route::resource('photos.comments', PhotoCommentController::class)->scoped([4 'comment' => 'slug',5]);
此路由将注册一个作用域嵌套资源,可以使用如下 URI 访问
1/photos/{photo}/comments/{comment:slug}
当使用自定义键控隐式绑定作为嵌套路由参数时,Laravel 将自动作用域查询,以使用约定猜测父项上的关系名称来检索嵌套模型。在本例中,将假定 Photo
模型具有名为 comments
的关系(路由参数名称的复数形式),该关系可用于检索 Comment
模型。
本地化资源 URI
默认情况下,Route::resource
将使用英语动词和复数规则创建资源 URI。如果您需要本地化 create
和 edit
操作动词,您可以使用 Route::resourceVerbs
方法。这可以在应用程序的 App\Providers\AppServiceProvider
中的 boot
方法的开头完成
1/** 2 * Bootstrap any application services. 3 */ 4public function boot(): void 5{ 6 Route::resourceVerbs([ 7 'create' => 'crear', 8 'edit' => 'editar', 9 ]);10}
Laravel 的复数化器支持 您可以根据需要配置的几种不同的语言。一旦动词和复数化语言被自定义,资源路由注册(例如 Route::resource('publicacion', PublicacionController::class)
)将生成以下 URI
1/publicacion/crear23/publicacion/{publicaciones}/editar
补充资源控制器
如果您需要在资源控制器中添加超出默认资源路由集之外的其他路由,则应在调用 Route::resource
方法之前定义这些路由;否则,由 resource
方法定义的路由可能会无意中优先于您的补充路由
1use App\Http\Controller\PhotoController;2 3Route::get('/photos/popular', [PhotoController::class, 'popular']);4Route::resource('photos', PhotoController::class);
请记住保持控制器的专注性。如果您发现自己经常需要典型资源操作集之外的方法,请考虑将控制器拆分为两个较小的控制器。
单例资源控制器
有时,您的应用程序将具有只能有一个实例的资源。例如,用户的“个人资料”可以编辑或更新,但用户可能没有多个“个人资料”。同样,图像可能只有一个“缩略图”。这些资源称为“单例资源”,意味着资源只能存在一个实例。在这些情况下,您可以注册一个“单例”资源控制器
1use App\Http\Controllers\ProfileController;2use Illuminate\Support\Facades\Route;3 4Route::singleton('profile', ProfileController::class);
上面的单例资源定义将注册以下路由。如您所见,“创建”路由未为单例资源注册,并且注册的路由不接受标识符,因为资源只能存在一个实例
动词 | URI | 操作 | 路由名称 |
---|---|---|---|
GET | /profile |
show | profile.show |
GET | /profile/edit |
edit | profile.edit |
PUT/PATCH | /profile |
update | profile.update |
单例资源也可以嵌套在标准资源中
1Route::singleton('photos.thumbnail', ThumbnailController::class);
在本例中,photos
资源将接收所有 标准资源路由;但是,thumbnail
资源将是一个单例资源,具有以下路由
动词 | 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
方法
1Route::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
方法
1Route::singleton(...)->destroyable();
API 单例资源
apiSingleton
方法可用于注册将通过 API 操作的单例资源,从而使 create
和 edit
路由变得不必要
1Route::apiSingleton('profile', ProfileController::class);
当然,API 单例资源也可以是 creatable
的,这将为资源注册 store
和 destroy
路由
1Route::apiSingleton('photos.thumbnail', ProfileController::class)->creatable();
依赖注入与控制器
构造器注入
Laravel 服务容器 用于解析所有 Laravel 控制器。因此,您可以在控制器的构造器中类型提示控制器可能需要的任何依赖项。声明的依赖项将自动解析并注入到控制器实例中
1<?php 2 3namespace App\Http\Controllers; 4 5use App\Repositories\UserRepository; 6 7class UserController extends Controller 8{ 9 /**10 * Create a new controller instance.11 */12 public function __construct(13 protected UserRepository $users,14 ) {}15}
方法注入
除了构造器注入之外,您还可以在控制器的方法中类型提示依赖项。方法注入的常见用例是将 Illuminate\Http\Request
实例注入到您的控制器方法中
1<?php 2 3namespace App\Http\Controllers; 4 5use Illuminate\Http\RedirectResponse; 6use Illuminate\Http\Request; 7 8class UserController extends Controller 9{10 /**11 * Store a new user.12 */13 public function store(Request $request): RedirectResponse14 {15 $name = $request->name;16 17 // Store the user...18 19 return redirect('/users');20 }21}
如果您的控制器方法也期望从路由参数获取输入,请在其他依赖项之后列出您的路由参数。例如,如果您的路由定义如下
1use App\Http\Controllers\UserController;2 3Route::put('/user/{id}', [UserController::class, 'update']);
您仍然可以类型提示 Illuminate\Http\Request
,并通过将控制器方法定义如下来访问您的 id
参数
1<?php 2 3namespace App\Http\Controllers; 4 5use Illuminate\Http\RedirectResponse; 6use Illuminate\Http\Request; 7 8class UserController extends Controller 9{10 /**11 * Update the given user.12 */13 public function update(Request $request, string $id): RedirectResponse14 {15 // Update the user...16 17 return redirect('/users');18 }19}