控制器

• 介绍
• 编写控制器
  • 基本控制器
  • 单操作控制器
• 控制器中间件
• 资源控制器
  • 部分资源路由
  • 嵌套资源
  • 命名资源路由
  • 命名资源路由参数
  • 范围资源路由
  • 本地化资源 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');
    }
}