跳到內容

控制器

簡介

除了將所有請求處理邏輯定義為路由檔案中的閉包之外,您可能希望使用「控制器」類別來組織此行為。控制器可以將相關的請求處理邏輯分組到單一類別中。例如,一個 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): View
14 {
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

可以使用stub 發佈自訂控制器 stubs。

控制器中介層

中介層可以分配給路由檔案中控制器的路由

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 HasMiddleware
10{
11 /**
12 * Get the middleware that should be assigned to the controller.
13 */
14 public static function middleware(): array
15 {
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 將允許 showeditupdate 資源路由的軟刪除模型。您可以透過將陣列傳遞給 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 模板的路由,例如 createedit。為了方便起見,您可以使用 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]);

若要快速產生不包含 createedit 方法的 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。如果您需要本地化 createedit 動作動詞,您可以使用 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 的 pluralizer 支援您可以根據需要設定的幾種不同的語言。一旦自訂了動詞和複數化語言,資源路由註冊(例如 Route::resource('publicacion', PublicacionController::class))將產生以下 URI

1/publicacion/crear
2
3/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 操作的單例資源,從而使 createedit 路由變得不必要

1Route::apiSingleton('profile', ProfileController::class);

當然,API 單例資源也可以是 creatable,這將為資源註冊 storedestroy 路由

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): RedirectResponse
14 {
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): RedirectResponse
14 {
15 // Update the user...
16 
17 return redirect('/users');
18 }
19}