Controllers

• Introduction
• 编写控制器
  • 基本控制器
  • 单动作控制器
• 控制器中间件
• 资源控制器
  • 部分资源路线
  • 嵌套资源
  • 命名资源路由
  • 命名资源路由参数
  • 界定资源路线
  • 本地化资源 URI
  • 补充资源控制器
  • 单例资源控制器
• 依赖注入和控制器

#Introduction

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

#编写控制器

#基本控制器

要快速生成新控制器，您可以运行make:controller 工匠命令。默认情况下，应用程序的所有控制器都存储在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 匹配时，show 上的方法App\Http\Controllers\UserController 将调用类并将路由参数传递给该方法。

Note
控制器不是required 扩展基类。但是，您将无法使用便利的功能，例如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);

您可以使用--invokable 的选项make:controller 工匠命令：

php artisan make:controller ProvisionServer --invokable

Note
控制器存根可以使用自定义存根发布.

#控制器中间件

Middleware 可以在你的路由文件中分配给控制器的路由：

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 工匠命令--resource 快速创建控制器来处理这些操作的选项：

php artisan make:controller PhotoController --resource

该命令将在app/Http/Controllers/PhotoController.php.控制器将包含用于每个可用资源操作的方法。接下来，您可以注册指向控制器的资源路由：

use App\Http\Controllers\PhotoController;

Route::resource('photos', PhotoController::class);

这个单一的路由声明创建了多个路由来处理资源上的各种操作。生成的控制器已经为这些操作中的每一个操作存根了方法。请记住，您始终可以通过运行以下命令快速了解应用程序的路由route:list工匠命令。

您甚至可以通过将数组传递给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 方法：

use App\Http\Controllers\PhotoController;
use App\Http\Controllers\PostController;

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

快速生成不包含的 API 资源控制器create 或者edit 方法，使用--api 执行时切换make:controller 命令：

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

上面的示例为资源的生成以下 URIshow 路线：

/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 方法。这可以在开始时完成boot 应用程序中的方法App\Providers\RouteServiceProvider:

/**
 * 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 方法;否则，由resource 方法可能无意中优先于您的补充路线：

use App\Http\Controller\PhotoController;

Route::get('/photos/popular', [PhotoController::class, 'popular']);
Route::resource('photos', PhotoController::class);

Note
请记住让您的控制器保持专注。如果您发现自己经常需要典型资源操作集之外的方法，请考虑将您的控制器拆分为两个较小的控制器。

#单例资源控制器

有时，您的应用程序将拥有可能只有一个实例的资源。例如，可以编辑或更新用户的“个人资料”，但一个用户不能拥有多个“个人资料”。同样，图像可能只有一个“缩略图”。这些资源称为“单例资源”，这意味着可能存在一个且只有一个资源实例。在这些情况下，您可以注册一个“单例”资源控制器：

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