控制器 - Controller

簡介
撰寫 Controller
- 「Controller」基礎
- 單一動作的 Controller
Controller Middleware
Resource Controller
相依性插入與 Controller

簡介

比起在路由檔案中使用閉包來定義所有的請求處理邏輯，你可能會想使用「Controller」類別來管理這個行為。Controller 可以將相關的請求處理邏輯放在單一類別內。舉例來說，UserController 類別可以處理所有有關使用者的連入請求，包含顯示、建立、更新與刪除使用者。預設情況下，Controller 存放在 app/Http/Controllers 目錄下。

撰寫 Controller

基礎 Controller

來看看一個基礎 Controller 的例子。請注意，該 Controller 繼承了包含在 Laravel 內的基礎 Controller 類別：App\Http\Controllers\Controller：

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Models\User;
 7 
 8class UserController extends Controller
 9{
10    /**
11     * Show the profile for a given user.
12     *
13     * @param  int  $id
14     * @return \Illuminate\View\View
15     */
16    public function show($id)
17    {
18        return view('user.profile', [
19            'user' => User::findOrFail($id)
20        ]);
21    }
22} 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Models\User;
 7 
 8class UserController extends Controller
 9{
10    /**
11     * Show the profile for a given user.
12     *
13     * @param  int  $id
14     * @return \Illuminate\View\View
15     */
16    public function show($id)
17    {
18        return view('user.profile', [
19            'user' => User::findOrFail($id)
20        ]);
21    }
22}

可以像這樣定義連結到這個 Controller 的路由：

1use App\Http\Controllers\UserController;
2 
3Route::get('/user/{id}', [UserController::class, 'show']);1use App\Http\Controllers\UserController;
2 
3Route::get('/user/{id}', [UserController::class, 'show']);

當有連入請求符合這個路由 URI 時，將叫用 App\Http\Controllers\UserController 類別的 show 方法，且 route 參數會被傳入這個方法內。

Controller 並不一定要有繼承基礎類別。不過，若不繼承基礎 Controller 的話將無法使用一些如 middleware 或 authorize 方法等方便的功能。

單一動作的 Controller

若某個 Controller 動作特別複雜，則可以將這個動作放到獨立的 Controller 類別。為此，可在該 Controller 內定義一個單一的 __invoke 方法：

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Models\User;
 7 
 8class ProvisionServer extends Controller
 9{
10    /**
11     * Provision a new web server.
12     *
13     * @return \Illuminate\Http\Response
14     */
15    public function __invoke()
16    {
17        // ...
18    }
19} 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Http\Controllers\Controller;
 6use App\Models\User;
 7 
 8class ProvisionServer extends Controller
 9{
10    /**
11     * Provision a new web server.
12     *
13     * @return \Illuminate\Http\Response
14     */
15    public function __invoke()
16    {
17        // ...
18    }
19}

當為單一動作的 Controller 註冊路由時，不需要指定 Controller 方法。只需要傳入該 Controller 的名稱給 Router 即可：

1use App\Http\Controllers\ProvisionServer;
2 
3Route::post('/server', ProvisionServer::class);1use App\Http\Controllers\ProvisionServer;
2 
3Route::post('/server', ProvisionServer::class);

可以通過 make:controller Artisan 指令的 --invokable 選項來建立可被叫用的 Controller：

1php artisan make:controller ProvisionServer --invokable1php artisan make:controller ProvisionServer --invokable

Controller 的 Stub 可通過發佈 Stub 來自定。

Controller Middleware

可在路由檔案中指派 Middleware 給 Controller 的路由：

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

或者，你可能會覺得在 Controller 的建構函式內指定 Middleware 比較方便。在 Controller 的建構函式內使用 middleware 方法，就能指派 Middleware 給該 Controller 的動作：

 1class UserController extends Controller
 2{
 3    /**
 4     * Instantiate a new controller instance.
 5     *
 6     * @return void
 7     */
 8    public function __construct()
 9    {
10        $this->middleware('auth');
11        $this->middleware('log')->only('index');
12        $this->middleware('subscribed')->except('store');
13    }
14} 1class UserController extends Controller
 2{
 3    /**
 4     * Instantiate a new controller instance.
 5     *
 6     * @return void
 7     */
 8    public function __construct()
 9    {
10        $this->middleware('auth');
11        $this->middleware('log')->only('index');
12        $this->middleware('subscribed')->except('store');
13    }
14}

Controller 也能讓你使用閉包來註冊 Middleware。這樣便提供了一種方便的方式來為單一 Controller 定義內崁 Middleware 而無需定義整個 Middleware 類別：

1$this->middleware(function ($request, $next) {
2    return $next($request);
3});1$this->middleware(function ($request, $next) {
2    return $next($request);
3});

資源 Controller

若將專案內的各個 Eloquent Model 當作是「資源」，則我們通常會在專案中對各個資源進行同一系列的動作。舉例來說，假設專案中有個 Photo Model 與 Movie Model。則使用者應該可以建立 (Create)、檢視 (Read)、更新 (Update)、或刪除 (Delete) 這些資源。

由於這個常見的使用情況，Laravel 資源路由可將常見的建立 (Create)、讀取 (Read)、更新 (Update) 與刪除 (Delete) (即「CRUD」) 通過單行程式碼來指派路由。要開始建立資源路由，可使用 make:controller Artisan 指令的 --resource 選項來快速建立處理這些動作的 Controller：

1php artisan make:controller PhotoController --resource1php artisan make:controller PhotoController --resource

這個指令會在 app/Http/Controllers/PhotoController.php 下產生一個 Controller。該 Controller 會包含用於各個可用資源操作的方法。接著，可以註冊一個指向該 Controller 的資源路由：

1use App\Http\Controllers\PhotoController;
2 
3Route::resource('photos', PhotoController::class);1use App\Http\Controllers\PhotoController;
2 
3Route::resource('photos', PhotoController::class);

這一個路由定義會建立多個路由來處理對該資源的數種動作。剛才產生的 Controller 已經預先有了用於這幾個動作的方法了。請記得，你可以隨時通過執行 route:list Artisan 指令來快速檢視專案的路由。

也可以通過傳入陣列給 resources 方法來一次註冊多個資源 Controller：

1Route::resources([
2    'photos' => PhotoController::class,
3    'posts' => PostController::class,
4]);1Route::resources([
2    'photos' => PhotoController::class,
3    'posts' => PostController::class,
4]);

由資源 Controller 處理的動作

動詞	URI	動作	Route 名稱
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

自訂找不到 Model 的行為

通常來說，若找不到隱式繫結的資源 Model 時會產生一個 404 HTTP 回應。不過，可以在定義資源路由時通過呼叫 missing 方法來自訂這個行為。missing 方法接受一個閉包，該閉包會在任何資源的路由上找不到隱式繫結的 Model 時被叫用：

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

指定資源 Model

若使用了路由 Model 繫結，且想型別提示資源 Controller 的方法，可以在產生 Controller 時使用 --model 選項：

1php artisan make:controller PhotoController --model=Photo --resource1php artisan make:controller PhotoController --model=Photo --resource

產生 Form Request

可以在產生資源 Controller 時提供 --requests 選項來告訴 Artisan 要產生用於 Controller 中 storage 與 update 方法的 Form Request 類別：

1php artisan make:controller PhotoController --model=Photo --resource --requests1php artisan make:controller PhotoController --model=Photo --resource --requests

部分資源路由

宣告資源路由時，比起宣告全部的預設動作，也可以只宣告該 Controller 要處理的一部分動作：

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]);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);1use App\Http\Controllers\PhotoController;
2 
3Route::apiResource('photos', PhotoController::class);

也可以通過傳入陣列給 apiResources 方法來一次註冊多個 API 資源 Controller：

1use App\Http\Controllers\PhotoController;
2use App\Http\Controllers\PostController;
3 
4Route::apiResources([
5    'photos' => PhotoController::class,
6    'posts' => PostController::class,
7]);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:contorller 指令時使用 --api 開關：

1php artisan make:controller PhotoController --api1php artisan make:controller PhotoController --api

巢狀資源

有時候我們會需要為巢狀資源定義路由。舉例來說，某個照片資源可能會有多個附加到該照片的留言。要巢狀嵌套資源 Controller，我們可以在路由定義上使用「點」標記法：

1use App\Http\Controllers\PhotoCommentController;
2 
3Route::resource('photos.comments', PhotoCommentController::class);1use App\Http\Controllers\PhotoCommentController;
2 
3Route::resource('photos.comments', PhotoCommentController::class);

該路由會註冊一個巢狀資源，可使用像這樣的 URI 來存取：

1/photos/{photo}/comments/{comment}1/photos/{photo}/comments/{comment}

限定範圍的巢狀資源

Laravel 的隱式 Model 繫結功能可自動限制巢狀繫結的範圍，讓要被解析的子 Model 可被限制在屬於其上層 Model。只要在定義巢狀資源時使用 scoped 方法，就可以開啟自動範圍限制，並告訴 Laravel 應使用子資源的哪個欄位來取得。更多有關此的資訊，請參考限制資源路由的範圍的說明文件。

淺層巢狀

通常，在 URI 中並不需要同時擁有上層 Model 與子 Model 的 ID，因為子 ID 已經是唯一的識別子了。若要在使用唯一如自動遞增的主鍵這樣的識別子來在 URI 區段中識別 Model，可使用「淺層巢狀 (Shallow Nesting)」：

1use App\Http\Controllers\CommentController;
2 
3Route::resource('photos.comments', CommentController::class)->shallow();1use App\Http\Controllers\CommentController;
2 
3Route::resource('photos.comments', CommentController::class)->shallow();

這個路由定義會定義下列路由：

動詞	URI	動作	Route 名稱
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

命名資源路由

預設情況下，所有的資源 Controller 動作都有對應的路由名稱。不過，可以通過將包含欲使用的路由名稱的陣列傳入 names 來複寫這些名稱：

1use App\Http\Controllers\PhotoController;
2 
3Route::resource('photos', PhotoController::class)->names([
4    'create' => 'photos.build'
5]);1use App\Http\Controllers\PhotoController;
2 
3Route::resource('photos', PhotoController::class)->names([
4    'create' => 'photos.build'
5]);

命名資源路由參數

預設情況下，Route::resource 會為依照「單數化 (Singularized)」的資源名稱來為資源路由建立路由參數。可以輕鬆地通過 parameters 方法來對個別資源複寫資源名稱。傳入 parameters 的陣列應為一個包含資源名稱與參數名稱的關聯式陣列：

1use App\Http\Controllers\AdminUserController;
2 
3Route::resource('users', AdminUserController::class)->parameters([
4    'users' => 'admin_user'
5]);1use App\Http\Controllers\AdminUserController;
2 
3Route::resource('users', AdminUserController::class)->parameters([
4    'users' => 'admin_user'
5]);

上述範例會為資源的 show 路由產生下列 URI：

1/users/{admin_user}1/users/{admin_user}

限制資源路由的範圍

Laravel 的限定範圍的隱式 Model 繫結功能可自動限制巢狀繫結的範圍，讓要被解析的子 Model 可被限制在屬於其上層 Model。只要在定義巢狀資源時使用 scoped 方法，就可以開啟自動範圍限制，並告訴 Laravel 應使用子資源的哪個欄位來取得：

1use App\Http\Controllers\PhotoCommentController;
2 
3Route::resource('photos.comments', PhotoCommentController::class)->scoped([
4    'comment' => 'slug',
5]);1use App\Http\Controllers\PhotoCommentController;
2 
3Route::resource('photos.comments', PhotoCommentController::class)->scoped([
4    'comment' => 'slug',
5]);

該路由會註冊一個限定範圍的巢狀資源，可使用像這樣的 URI 來存取：

1/photos/{photo}/comments/{comment:slug}1/photos/{photo}/comments/{comment:slug}

當使用自訂鍵值的隱式繫結作為巢狀路由參數時，Laravel 會自動以慣例推測其上層 Model 上的關聯名稱來將限制巢狀 Model 的查詢範圍。在這個例子中，Laravel 會假設 Photo Model 有個名為 comments 的關聯 (即路由參數名稱的複數形)，該關聯將用於取得 Comment Model。

本地化資源 URI

預設情況下，Route::resource 會使用英語的動詞來建立資源 URI。若有需要本地化 create 與 action 動作的動詞，可以使用 Route::resourceVerbs 方法。這可以放在專案的 App\Providers\RouteServiceProvider 中之 boot 方法開頭。

 1/**
 2 * Define your route model bindings, pattern filters, etc.
 3 *
 4 * @return void
 5 */
 6public function boot()
 7{
 8    Route::resourceVerbs([
 9        'create' => 'crear',
10        'edit' => 'editar',
11    ]);
12 
13    // ...
14} 1/**
 2 * Define your route model bindings, pattern filters, etc.
 3 *
 4 * @return void
 5 */
 6public function boot()
 7{
 8    Route::resourceVerbs([
 9        'create' => 'crear',
10        'edit' => 'editar',
11    ]);
12 
13    // ...
14}

自訂完動詞後，使用如 Route::resource('fotos', PhotoController::class) 註冊的資源路由就會產生下列 URI：

1/fotos/crear
2 
3/fotos/{foto}/editar1/fotos/crear
2 
3/fotos/{foto}/editar

補充資源 Controller

若有需要為某個資源 Controller 增加除了預設資源路由以外的額外路由，則應在呼叫 Route::resource 方法前先定義這些路由。否則，又 resource 方法定義的路由可能會不可預期地取代所擴充的路由：

1use App\Http\Controller\PhotoController;
2 
3Route::get('/photos/popular', [PhotoController::class, 'popular']);
4Route::resource('photos', PhotoController::class);1use App\Http\Controller\PhotoController;
2 
3Route::get('/photos/popular', [PhotoController::class, 'popular']);
4Route::resource('photos', PhotoController::class);

請記得要保持 Controller 的功能專一。若發現常常需要使用除了一般資源動作以外的方法，請考慮將 Controller 拆分成兩個、更小的 Controller。

依賴注入與 Controller

建構函式注入

Laravel 的 Service Container 會被用來解析所有的 Laravel Controller。因此，可以在 Controller 的建構函式內型別提示所有 Controller 所需要的依賴。所宣告的依賴會被自動解析並插入到 Controller 實體上：

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Repositories\UserRepository;
 6 
 7class UserController extends Controller
 8{
 9    /**
10     * The user repository instance.
11     */
12    protected $users;
13 
14    /**
15     * Create a new controller instance.
16     *
17     * @param  \App\Repositories\UserRepository  $users
18     * @return void
19     */
20    public function __construct(UserRepository $users)
21    {
22        $this->users = $users;
23    }
24} 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use App\Repositories\UserRepository;
 6 
 7class UserController extends Controller
 8{
 9    /**
10     * The user repository instance.
11     */
12    protected $users;
13 
14    /**
15     * Create a new controller instance.
16     *
17     * @param  \App\Repositories\UserRepository  $users
18     * @return void
19     */
20    public function __construct(UserRepository $users)
21    {
22        $this->users = $users;
23    }
24}

方法注入

除了注入到建構函式內，也可以在 Controller 的方法上型別提示依賴。常見的使用情況是將 Illuminate\Http\Request 實體注入到 Controller 方法內：

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\Request;
 6 
 7class UserController extends Controller
 8{
 9    /**
10     * Store a new user.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @return \Illuminate\Http\Response
14     */
15    public function store(Request $request)
16    {
17        $name = $request->name;
18 
19        //
20    }
21} 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\Request;
 6 
 7class UserController extends Controller
 8{
 9    /**
10     * Store a new user.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @return \Illuminate\Http\Response
14     */
15    public function store(Request $request)
16    {
17        $name = $request->name;
18 
19        //
20    }
21}

若 Controller 方法也預期會從路由參數取得輸入，則請將路由引數放在其他依賴之後。舉例來說，若路由是像這樣定義：

1use App\Http\Controllers\UserController;
2 
3Route::put('/user/{id}', [UserController::class, 'update']);1use App\Http\Controllers\UserController;
2 
3Route::put('/user/{id}', [UserController::class, 'update']);

還是可以像這樣定義 Controller 方法來型別提示 Illuminate\Http\Request 並取得 id 參數：

 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\Request;
 6 
 7class UserController extends Controller
 8{
 9    /**
10     * Update the given user.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  string  $id
14     * @return \Illuminate\Http\Response
15     */
16    public function update(Request $request, $id)
17    {
18        //
19    }
20} 1<?php
 2 
 3namespace App\Http\Controllers;
 4 
 5use Illuminate\Http\Request;
 6 
 7class UserController extends Controller
 8{
 9    /**
10     * Update the given user.
11     *
12     * @param  \Illuminate\Http\Request  $request
13     * @param  string  $id
14     * @return \Illuminate\Http\Response
15     */
16    public function update(Request $request, $id)
17    {
18        //
19    }
20}