控制器

• 簡介
• 撰寫控制器
  • 基本控制器
  • 單一動作控制器
• 控制器中介層
• 資源控制器
  • 部分資源路由
  • 巢狀資源
  • 命名資源路由
  • 命名資源路由參數
  • 作用域資源路由
  • 本地化資源 URI
  • 補充資源控制器
  • 單例資源控制器
• 依賴注入與控制器

簡介

您可能不希望將所有請求處理邏輯定義為路由檔案中的閉包，而是希望使用「控制器」類別來組織此行為。控制器可以將相關的請求處理邏輯分組到一個類別中。例如，UserController 類別可能會處理所有與使用者相關的傳入請求，包括顯示、建立、更新和刪除使用者。依預設，控制器儲存在 app/Http/Controllers 目錄中。

撰寫控制器

基本控制器

若要快速產生新的控制器，您可以執行 make:controller Artisan 命令。依預設，應用程式的所有控制器都儲存在 app/Http/Controllers 目錄中

php artisan make:controller UserController

讓我們看看基本控制器的範例。控制器可以有任意數量的公開方法來回應傳入的 HTTP 請求

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

撰寫控制器類別和方法後，您可以像這樣定義指向控制器方法的路由

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

當傳入的請求符合指定的路由 URI 時，將會調用 App\Http\Controllers\UserController 類別上的 show 方法，並且路由參數將會傳遞給該方法。

單一動作控制器

如果控制器動作特別複雜，您可能會發現將整個控制器類別專用於該單一動作會很方便。若要完成此操作，您可以在控制器中定義一個 __invoke 方法

<?php
 
namespace App\Http\Controllers;
 
class ProvisionServer extends Controller
{
    /**
     * Provision a new web server.
     */
    public function __invoke()
    {
        // ...
    }
}

在為單一動作控制器註冊路由時，您不需要指定控制器方法。相反地，您可以簡單地將控制器的名稱傳遞給路由器

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

您可以使用 make:controller Artisan 命令的 --invokable 選項產生可調用的控制器

php artisan make:controller ProvisionServer --invokable

控制器中介層

中介層可以在您的路由檔案中指派給控制器的路由

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

或者，您可能會發現在控制器類別中指定中介層會很方便。若要執行此操作，您的控制器應該實作 HasMiddleware 介面，該介面規定控制器應具有靜態 middleware 方法。在此方法中，您可以傳回應套用至控制器動作的中介層陣列

<?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
{
    /**
     * Get the middleware that should be assigned to the controller.
     */
    public static function middleware(): array
    {
        return [
            'auth',
            new Middleware('log', only: ['index']),
            new Middleware('subscribed', except: ['store']),
        ];
    }
 
    // ...
}

您也可以將控制器中介層定義為閉包，這提供了一種方便的方式來定義內嵌中介層，而無需撰寫整個中介層類別

use Closure;
use Illuminate\Http\Request;
 
/**
 * Get the middleware that should be assigned to the controller.
 */
public static function middleware(): array
{
    return [
        function (Request $request, Closure $next) {
            return $next($request);
        },
    ];
}

資源控制器

如果您將應用程式中的每個 Eloquent 模型視為一個「資源」，則通常會針對應用程式中的每個資源執行相同的動作集。例如，假設您的應用程式包含 Photo 模型和 Movie 模型。使用者很可能會建立、讀取、更新或刪除這些資源。

由於這種常見的用例，Laravel 資源路由使用一行程式碼將典型的建立、讀取、更新和刪除（「CRUD」）路由指派給控制器。若要開始使用，我們可以利用 make:controller Artisan 命令的 --resource 選項，快速建立一個控制器來處理這些動作

php artisan make:controller PhotoController --resource

此命令將在 app/Http/Controllers/PhotoController.php 產生一個控制器。控制器將包含每個可用的資源操作的方法。接下來，您可以註冊一個指向控制器的資源路由

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

此單一路由宣告會建立多個路由，以處理資源上的各種動作。產生的控制器已經為每個這些動作存根方法。請記住，您可以隨時執行 route:list Artisan 命令，快速概覽應用程式的路由。

您甚至可以透過將陣列傳遞給 resources 方法，一次註冊多個資源控制器

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

資源控制器處理的動作

自訂遺失模型行為

通常，如果找不到隱式綁定的資源模型，則會產生 404 HTTP 回應。但是，您可以在定義資源路由時呼叫 missing 方法來自訂此行為。如果找不到隱式綁定的模型來處理任何資源的路由，則 missing 方法會接受將會調用的閉包

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

use App\Http\Controllers\PhotoController;
 
Route::resource('photos', PhotoController::class)->withTrashed();

不帶引數呼叫 withTrashed 將允許軟刪除模型以用於 show、edit 和 update 資源路由。您可以將陣列傳遞給 withTrashed 方法，指定這些路由的子集

Route::resource('photos', PhotoController::class)->withTrashed(['show']);

指定資源模型

如果您正在使用路由模型綁定，並且希望資源控制器的方法進行模型實例的類型提示，則可以在產生控制器時使用 --model 選項

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

產生表單請求

您可以在產生資源控制器時提供 --requests 選項，以指示 Artisan 為控制器的儲存和更新方法產生表單請求類別

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

部分資源路由

在宣告資源路由時，您可以指定控制器應該處理的動作子集，而不是完整的預設動作集

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 方法來自動排除這兩個路由

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

php artisan make:controller PhotoController --api

巢狀資源

有時候您可能需要定義巢狀資源的路由。例如，相片資源可能有多個可以附加到相片的評論。若要巢狀化資源控制器，您可以在路由宣告中使用「點」表示法

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

此路由將註冊一個巢狀資源，可以使用如下的 URI 存取

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

範圍化巢狀資源

Laravel 的隱式模型綁定功能可以自動範圍化巢狀綁定，以便確認解析的子模型屬於父模型。透過在定義巢狀資源時使用 scoped 方法，您可以啟用自動範圍化，並指示 Laravel 應該透過哪個欄位擷取子資源。如需如何完成此操作的詳細資訊，請參閱有關範圍化資源路由的文件。

淺巢狀

通常，在 URI 中同時包含父 ID 和子 ID 並非絕對必要，因為子 ID 本身已是唯一的識別符。當使用自動遞增的主鍵等唯一識別符來識別 URI 片段中的模型時，您可以選擇使用「淺層巢狀」。

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

此路由定義將定義以下路由：

命名資源路由

預設情況下，所有資源控制器動作都有路由名稱；但是，您可以通過傳遞一個包含您想要的路由名稱的 names 陣列來覆蓋這些名稱。

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

命名資源路由參數

預設情況下，Route::resource 將根據資源名稱的「單數化」版本，為您的資源路由建立路由參數。您可以使用 parameters 方法，輕鬆地針對每個資源覆蓋此設定。傳遞給 parameters 方法的陣列應該是一個資源名稱和參數名稱的關聯陣列。

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

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

/users/{admin_user}

作用域資源路由

Laravel 的作用域隱式模型綁定功能可以自動限定巢狀綁定的範圍，以確保解析後的子模型確實屬於父模型。在定義巢狀資源時使用 scoped 方法，您可以啟用自動限定範圍，並指示 Laravel 應該使用哪個欄位來檢索子資源。

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

此路由將註冊一個作用域的巢狀資源，可以使用類似以下的 URI 來存取：

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

當使用自訂鍵值隱式綁定作為巢狀路由參數時，Laravel 會自動限定查詢範圍，以便使用約定來猜測父級上的關聯名稱，以此檢索父級中的巢狀模型。在此範例中，將假定 Photo 模型有一個名為 comments（路由參數名稱的複數形式）的關聯，可以用來檢索 Comment 模型。

本地化資源 URI

預設情況下，Route::resource 將使用英文動詞和複數規則來建立資源 URI。如果您需要本地化 create 和 edit 動作動詞，您可以使用 Route::resourceVerbs 方法。這可以在應用程式的 App\Providers\AppServiceProvider 中的 boot 方法開始時完成。

/**
 * Bootstrap any application services.
 */
public function boot(): void
{
    Route::resourceVerbs([
        'create' => 'crear',
        'edit' => 'editar',
    ]);
}

Laravel 的複數化工具支援數種不同的語言，您可以根據需要進行設定。一旦自訂了動詞和複數化語言，像是 Route::resource('publicacion', PublicacionController::class) 這樣的資源路由註冊將產生以下的 URI：

/publicacion/crear
 
/publicacion/{publicaciones}/editar

補充資源控制器

如果您需要在預設資源路由集合之外為資源控制器新增其他路由，您應該在呼叫 Route::resource 方法之前定義這些路由；否則，resource 方法定義的路由可能會無意中優先於您的補充路由。

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

單例資源控制器

有時，您的應用程式會有一些只能有一個實例的資源。例如，使用者的「個人資料」可以編輯或更新，但使用者不能擁有超過一個「個人資料」。同樣地，圖片可能只有一個「縮圖」。這些資源稱為「單例資源」，表示該資源只能存在一個實例。在這些情況下，您可以註冊一個「單例」資源控制器。

use App\Http\Controllers\ProfileController;
use Illuminate\Support\Facades\Route;
 
Route::singleton('profile', ProfileController::class);

上面的單例資源定義將註冊以下路由。如您所見，單例資源不會註冊「建立」路由，且註冊的路由不接受識別符，因為資源只能有一個實例。

單例資源也可以巢狀於標準資源中。

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

在此範例中，photos 資源將接收所有標準資源路由；但是，thumbnail 資源將是一個單例資源，具有以下路由：

可建立的單例資源

有時，您可能需要為單例資源定義建立和儲存路由。若要完成此操作，您可以在註冊單例資源路由時調用 creatable 方法。

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

在此範例中，將註冊以下路由。如您所見，可建立的單例資源也會註冊 DELETE 路由。

如果您希望 Laravel 為單例資源註冊 DELETE 路由，但不註冊建立或儲存路由，則可以使用 destroyable 方法。

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

API 單例資源

apiSingleton 方法可以用來註冊一個將通過 API 操作的單例資源，因此不需要 create 和 edit 路由。

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

當然，API 單例資源也可以是 creatable，這將為資源註冊 store 和 destroy 路由。

Route::apiSingleton('photos.thumbnail', ProfileController::class)->creatable();

依賴注入與控制器

建構函式注入

Laravel 服務容器用於解析所有 Laravel 控制器。因此，您可以在控制器的建構函式中類型提示控制器可能需要的任何相依性。宣告的相依性將會自動解析並注入到控制器實例中。

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

如果您的控制器方法也期望從路由參數獲取輸入，請在其他相依性之後列出您的路由引數。例如，如果您的路由定義如下：

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

您仍然可以類型提示 Illuminate\Http\Request，並通過以下方式定義您的控制器方法來存取您的 id 參數：

<?php
 
namespace App\Http\Controllers;
 
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
 
class UserController extends Controller
{
    /**
     * Update the given user.
     */
    public function update(Request $request, string $id): RedirectResponse
    {
        // Update the user...
 
        return redirect('/users');
    }
}