控制器

介绍

你可以通过 "控制器" 类来组织请求处理逻辑，而不是在路由文件中将所有请求处理逻辑定义为闭包函数。控制器可以将相关的请求处理逻辑分组到一个单独的类中。例如，UserController 类可能处理与用户有关的所有传入请求，包括显示、创建、更新和删除用户。默认情况下，控制器存储在 app/Http/Controllers 目录中。

编写控制器

基本控制器

让我们看一个基本控制器的示例。请注意，控制器扩展了 Laravel 中包含的基本控制器类：

<?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 方法，并将路由参数传递给该方法。

控制器不一定需要扩展基类。但是，你将无法访问方便的功能，如 middleware 和 authorize 方法。

单一操作控制器

如果一个控制器操作特别复杂，您可能会发现将一个单一的控制器类专门用于该单一操作非常方便。为了实现这一点，您可以在控制器中定义一个单一的 __invoke 方法：

<?php
 
namespace App\Http\Controllers;
 
use App\Models\User;
use Illuminate\Http\Response;
 
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  

您可以使用 stub publishing 自定义控制器 stub。

控制器中间件

在路由文件中，可以为控制器的路由分配中间件：

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

或者，您可能会发现在控制器的构造函数中指定中间件更加方便。通过在控制器的构造函数中使用 middleware 方法，可以为控制器的操作分配中间件：

class UserController extends Controller
{
    /**
     * Instantiate a new controller instance.
     */
    public function __construct()
    {
        $this->middleware('auth');
        $this->middleware('log')->only('index');
        $this->middleware('subscribed')->except('store');
    }
}

控制器还允许您使用闭包注册中间件。这为为单个控制器定义一个内联中间件提供了方便的方式，而无需定义整个中间件类：

use Closure;
use Illuminate\Http\Request;
 
$this->middleware(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 选项可以让控制器的方法对模型进行类型提示（路由模型绑定），这里以 Photo 模型为例：

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

生成表单请求

--requests 选项可以为控制器的存储和更新方法生成表单请求类：

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\RouteServiceProvider 的 boot 方法开头执行：

/**
 * Define your route model bindings, pattern filters, etc.
 */
public function boot(): void
{
    Route::resourceVerbs([
        'create' => 'crear',
        'edit' => 'editar',
    ]);

    // ...
}

Laravel 的复数形式支持多种不同的语言，可以根据需要进行配置。一旦定制了动词和复数形式的语言，例如 Route::resource('publicacion', PublicacionController::class) 这样的资源路由注册将会产生以下 URI：

/publicacion/crear

/publicacion/{publicaciones}/editar

补充资源控制器

如果你需要在资源控制器之外添加其他路由，应该在调用 Route::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();

在这个例子中，以下路由将被注册。可以看到，可创建的 Singleton 资源还将注册一个 DELETE 路由：

如果您希望 Laravel 为单例资源注册 DELETE 路由，但不注册创建或存储路由，可以使用 destroyable 方法：

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

API 单例资源

可以使用 apiSingleton 方法注册仅通过 API 操作的单例资源，因此创建和编辑路由不再必要：

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

当然，API 单例资源也可以是可创建的，这将为资源注册存储和删除路由：

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