服务容器

介绍

Laravel 服务容器是一个强大的工具，用于管理类的依赖关系并执行依赖注入。依赖注入是一个高大上的术语，本质上是指：类的依赖通过构造函数，或者在某些情况下，通过 “setter” 方法注入到类中。

让我们看一个简单的例子：

<?php

namespace App\Http\Controllers;

use App\Services\AppleMusic;
use Illuminate\View\View;

class PodcastController extends Controller
{
    /**
     * 创建一个新的控制器实例。
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    /**
     * 显示给定播客的信息。
     */
    public function show(string $id): View
    {
        return view('podcasts.show', [
            'podcast' => $this->apple->findPodcast($id)
        ]);
    }
}

在这个例子中，PodcastController 需要从像 Apple Music 这样的数据源中获取播客。因此，我们将注入一个能够检索播客的服务。由于这个服务是被注入的，我们可以在测试应用程序时轻松地 “mock”（模拟）或者创建一个 AppleMusic 服务的虚拟实现。

深入理解 Laravel 服务容器对于构建一个强大、复杂的应用程序至关重要，同时也对贡献 Laravel 核心代码有很大帮助。

零配置解析

如果一个类没有依赖项，或者仅依赖于其它具体类（而不是接口），那么容器无需指示如何解析该类。例如，您可以在 routes/web.php 文件中放入以下代码：

<?php

class Service
{
    // ...
}

Route::get('/', function (Service $service) {
    die($service::class);
});

在这个例子中，访问应用程序的 / 路由将自动解析 Service 类，并将其注入到路由处理器中。这是革命性的。这意味着您可以在开发应用程序时，利用依赖注入，而不需要担心臃肿的配置文件。

幸运的是，当您构建 Laravel 应用程序时，许多类会通过容器自动接收其依赖项，包括【控制器】、【事件监听器】、【中间件】等。此外，您还可以在【队列作业】的 handle 方法中使用类型提示依赖项。一旦体验了自动且零配置的依赖注入，您会觉得没有它就无法进行开发。

何时使用容器

得益于零配置解析，您将经常在路由、控制器、事件监听器等地方使用类型提示依赖项，而无需手动与容器交互。例如，您可能在路由定义中对 Illuminate\Http\Request 对象进行类型提示，以便轻松访问当前请求。尽管我们在编写此代码时从未与容器进行交互，但容器在后台管理着这些依赖项的注入：

use Illuminate\Http\Request;

Route::get('/', function (Request $request) {
    // ...
});

在许多情况下，得益于自动依赖注入和门面（【facades】），您可以在不手动绑定或解析任何容器内容的情况下构建 Laravel 应用程序。那么，您何时需要手动与容器交互呢？让我们来看两个情况。

首先，如果您编写一个实现了接口的类，并且希望在路由或类构造函数中对该接口进行类型提示，您必须【告诉容器如何解析该接口】。其次，如果您正在【编写一个 Laravel 包】，并计划与其它 Laravel 开发者共享，您可能需要将该包的服务绑定到容器中。

绑定

绑定基础

简单绑定

几乎所有的服务容器绑定都会在服务提供者中注册，因此大多数示例将展示在这种上下文中使用容器。

在服务提供者中，您始终可以通过 $this->app 属性访问容器。我们可以使用 bind 方法注册一个绑定，传入我们希望注册的类或接口名称，以及一个返回该类实例的闭包：

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->bind(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

请注意，我们将容器本身作为解析器的参数传入。然后，我们可以使用容器来解析我们正在构建的对象的子依赖项。

如前所述，您通常会在服务提供者中与容器交互；然而，如果您希望在服务提供者之外与容器交互，您可以通过 App 门面来实现：

use App\Services\Transistor;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\App;

App::bind(Transistor::class, function (Application $app) {
    // ...
});

您可以使用 bindIf 方法，仅在尚未为给定类型注册绑定时，才注册容器绑定：

$this->app->bindIf(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

如果类没有依赖任何接口，则无需将它们绑定到容器中。容器不需要被指示如何构建这些对象，因为它可以通过反射自动解析这些对象。

绑定单例

singleton 方法将一个类或接口绑定到容器中，该类或接口只应解析一次。一旦单例绑定被解析，容器在随后的调用中将返回相同的对象实例：

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->singleton(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

您可以使用 singletonIf 方法，仅在尚未为给定类型注册绑定时，才注册单例容器绑定：

$this->app->singletonIf(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

绑定作用域单例

scoped 方法将一个类或接口绑定到容器中，该类或接口只应在给定的 Laravel 请求/作业生命周期内解析一次。虽然该方法与 singleton 方法类似，但使用 scoped 方法注册的实例将在 Laravel 应用程序启动新的 “生命周期” 时被清除，例如当【Laravel Octane】工作进程处理新的请求，或当 Laravel 【队列工作进程】处理新的作业时：

use App\Services\Transistor;
use App\Services\PodcastParser;
use Illuminate\Contracts\Foundation\Application;

$this->app->scoped(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

您可以使用 scopedIf 方法，仅在尚未为给定类型注册绑定时，才注册作用域容器绑定：

$this->app->scopedIf(Transistor::class, function (Application $app) {
    return new Transistor($app->make(PodcastParser::class));
});

绑定实例

您还可以使用 instance 方法将现有的对象实例绑定到容器中。给定的实例将在随后的容器调用中始终返回：

use App\Services\Transistor;
use App\Services\PodcastParser;

$service = new Transistor(new PodcastParser);

$this->app->instance(Transistor::class, $service);

绑定接口到实现

服务容器的一个非常强大的功能是它能够将接口绑定到特定的实现。例如，假设我们有一个 EventPusher 接口和一个 RedisEventPusher 实现。一旦我们编写了 RedisEventPusher 对该接口的实现，就可以像下面这样将其注册到服务容器中：

use App\Contracts\EventPusher;
use App\Services\RedisEventPusher;

$this->app->bind(EventPusher::class, RedisEventPusher::class);

这条语句告诉容器，当某个类需要 EventPusher 的实现时，应注入 RedisEventPusher。现在我们可以在由容器解析的类的构造函数中对 EventPusher 接口进行类型提示。请记住，Laravel 应用程序中的控制器、事件监听器、中间件以及各种其它类型的类总是通过容器进行解析：

use App\Contracts\EventPusher;

/**
 * 创建一个新的类实例。
 */
public function __construct(
    protected EventPusher $pusher,
) {}

上下文绑定

有时您可能有两个类使用相同的接口，但您希望将不同的实现注入到每个类中。例如，两个控制器可能依赖于 Illuminate\Contracts\Filesystem\Filesystem 接口的不同实现。Laravel 提供了一个简单、流畅的接口来定义这种行为：

use App\Http\Controllers\PhotoController;
use App\Http\Controllers\UploadController;
use App\Http\Controllers\VideoController;
use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Support\Facades\Storage;

$this->app->when(PhotoController::class)
          ->needs(Filesystem::class)
          ->give(function () {
              return Storage::disk('local');
          });

$this->app->when([VideoController::class, UploadController::class])
          ->needs(Filesystem::class)
          ->give(function () {
              return Storage::disk('s3');
          });

这段代码演示了如何在不同的控制器中注入不同的 Filesystem 实现。PhotoController 将使用本地磁盘存储，而 VideoController 和 UploadController 将使用 S3 存储。

上下文属性

由于上下文绑定通常用于注入驱动程序的实现或配置值，Laravel 提供了多种上下文绑定属性，允许在不需要在服务提供者中手动定义上下文绑定的情况下，注入这些类型的值。

例如，可以使用 Storage 属性来注入特定的【存储磁盘】：

namespace App\Http\Controllers;

use Illuminate\Container\Attributes\Storage;
use Illuminate\Contracts\Filesystem\Filesystem;

class PhotoController extends Controller
{
    public function __construct(
        #[Storage('local')] protected Filesystem $filesystem
    )
    {
        // ...
    }
}

除了 Storage 属性，Laravel 还提供了 Auth、Cache、Config、DB、Log、RouteParameter 和 Tag 属性：

namespace App\Http\Controllers;

use App\Models\Photo;
use Illuminate\Container\Attributes\Auth;
use Illuminate\Container\Attributes\Cache;
use Illuminate\Container\Attributes\Config;
use Illuminate\Container\Attributes\DB;
use Illuminate\Container\Attributes\Log;
use Illuminate\Container\Attributes\RouteParameter;
use Illuminate\Container\Attributes\Tag;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Contracts\Cache\Repository;
use Illuminate\Database\Connection;
use Psr\Log\LoggerInterface;

class PhotoController extends Controller
{
    public function __construct(
        #[Auth('web')] protected Guard $auth,
        #[Cache('redis')] protected Repository $cache,
        #[Config('app.timezone')] protected string $timezone,
        #[DB('mysql')] protected Connection $connection,
        #[Log('daily')] protected LoggerInterface $log,
        #[RouteParameter('photo')] protected Photo $photo,
        #[Tag('reports')] protected iterable $reports,
    )
    {
        // ...
    }
}

此外，Laravel 还提供了 CurrentUser 属性，用于将当前认证的用户注入到给定的路由或类中：

use App\Models\User;
use Illuminate\Container\Attributes\CurrentUser;

Route::get('/user', function (#[CurrentUser] User $user) {
    return $user;
})->middleware('auth');

定义自定义属性

您可以通过实现 Illuminate\Contracts\Container\ContextualAttribute 接口来创建自己的上下文属性。容器将调用您属性的 resolve 方法，该方法应解析出应该注入到使用该属性的类中的值。在下面的示例中，我们将重新实现 Laravel 内置的 Config 属性：

namespace App\Attributes;

use Illuminate\Contracts\Container\ContextualAttribute;

#[Attribute(Attribute::TARGET_PARAMETER)]
class Config implements ContextualAttribute
{
    /**
     * 创建一个新的属性实例。
     */
    public function __construct(public string $key, public mixed $default = null)
    {
    }

    /**
     * 解析配置值。
     *
     * @param  self  $attribute
     * @param  \Illuminate\Contracts\Container\Container  $container
     * @return mixed
     */
    public static function resolve(self $attribute, Container $container)
    {
        return $container->make('config')->get($attribute->key, $attribute->default);
    }
}

在这个示例中，我们定义了一个 Config 属性，它会从容器中解析并返回配置值。您可以为任何其它需要注入的特定值创建类似的自定义属性。

绑定基础类型

有时，您可能有一个类接收一些注入的类，但也需要注入一个原始值，例如整数。您可以轻松地使用上下文绑定来注入类所需的任何值：

use App\Http\Controllers\UserController;

$this->app->when(UserController::class)
          ->needs('$variableName')
          ->give($value);

有时，类可能依赖于一组【标记】的实例。使用 giveTagged 方法，您可以轻松地注入所有具有该标签的容器绑定：

$this->app->when(ReportAggregator::class)
    ->needs('$reports')
    ->giveTagged('reports');

如果您需要注入来自应用程序配置文件的值，可以使用 giveConfig 方法：

$this->app->when(ReportAggregator::class)
    ->needs('$timezone')
    ->giveConfig('app.timezone');

绑定类型可变参数

有时，您可能有一个类使用变参构造函数接收一组类型化的对象数组：

use App\Models\Filter;
use App\Services\Logger;

class Firewall
{
    /**
     * 过滤器实例。
     *
     * @var array
     */
    protected $filters;

    /**
     * 创建一个新的类实例。
     */
    public function __construct(
        protected Logger $logger,
        Filter ...$filters,
    ) {
        $this->filters = $filters;
    }
}

通过使用上下文绑定，你可以通过为 give 方法提供一个闭包，该闭包返回一个已解析的 Filter 实例数组，从而解析这个依赖。

$this->app->when(Firewall::class)
          ->needs(Filter::class)
          ->give(function (Application $app) {
                return [
                    $app->make(NullFilter::class),
                    $app->make(ProfanityFilter::class),
                    $app->make(TooLongFilter::class),
                ];
          });

为了方便，您也可以直接提供一个类名数组，容器会在 Firewall 需要 Filter 实例时解析这些类：

$this->app->when(Firewall::class)
          ->needs(Filter::class)
          ->give([
              NullFilter::class,
              ProfanityFilter::class,
              TooLongFilter::class,
          ]);

变参标签依赖

有时，类可能有一个变参依赖，它被类型提示为给定的类（例如 Report …$reports）。使用 needs 和 giveTagged 方法，您可以轻松地为给定的依赖注入所有具有该【标签】的容器绑定：

$this->app->when(ReportAggregator::class)
    ->needs(Report::class)
    ->giveTagged('reports');

标记

有时，你可能需要解析某一 “类别” 的所有绑定。例如，假设你正在构建一个报告分析器，该分析器接收一个包含多种不同 Report 接口实现的数组。在注册了 Report 实现之后，你可以使用 tag 方法为它们分配一个标签：

$this->app->bind(CpuReport::class, function () {
    // ...
});

$this->app->bind(MemoryReport::class, function () {
    // ...
});

$this->app->tag([CpuReport::class, MemoryReport::class], 'reports');

一旦这些服务被打上标签，您可以通过容器的 tagged 方法轻松解析它们：

$this->app->bind(ReportAnalyzer::class, function (Application $app) {
    return new ReportAnalyzer($app->tagged('reports'));
});

扩展绑定

extend 方法允许修改已解析的服务。例如，当一个服务被解析时，您可以运行额外的代码来装饰或配置该服务。extend 方法接受两个参数：您要扩展的服务类和一个返回修改后服务的闭包。闭包接收正在解析的服务和容器实例：

$this->app->extend(Service::class, function (Service $service, Application $app) {
    return new DecoratedService($service);
});

解析

make 方法

您可以使用 make 方法从容器中解析一个类实例。make 方法接受您希望解析的类或接口的名称：

use App\Services\Transistor;

$transistor = $this->app->make(Transistor::class);

如果您的类的一些依赖项无法通过容器解析，您可以通过将它们作为关联数组传递给 makeWith 方法来手动注入。例如，我们可以手动传递 Transistor 服务所需的 $id 构造函数参数：

use App\Services\Transistor;

$transistor = $this->app->makeWith(Transistor::class, ['id' => 1]);

bound 方法可用于确定类或接口是否已在容器中显式绑定：

if ($this->app->bound(Transistor::class)) {
    // ...
}

如果您在代码中没有访问 $app 变量的服务提供者外部位置，您可以使用 App facade 或 app 助手函数从容器解析类实例：

use App\Services\Transistor;
use Illuminate\Support\Facades\App;

$transistor = App::make(Transistor::class);

$transistor = app(Transistor::class);

如果您希望将 Laravel 容器实例本身注入到一个由容器解析的类中，您可以在类的构造函数中类型提示 Illuminate\Container\Container 类：

use Illuminate\Container\Container;

/**
 * 创建一个新的类实例。
 */
public function __construct(
    protected Container $container,
) {}

自动注入

另外，您还可以在由容器解析的类的构造函数中进行依赖注入类型提示，包括【控制器】、【事件监听器】、【中间件】等。此外，您还可以在【队列作业】的 handle 方法中进行依赖注入类型提示。实际上，这是容器解析大多数对象的方式。

例如，您可以在控制器的构造函数中对应用程序定义的服务进行类型提示。容器会自动解析并将服务注入到类中：

<?php

namespace App\Http\Controllers;

use App\Services\AppleMusic;

class PodcastController extends Controller
{
    /**
     * 创建一个新的控制器实例。
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    /**
     * 显示给定播客的信息。
     */
    public function show(string $id): Podcast
    {
        return $this->apple->findPodcast($id);
    }
}

方法调用和注入

有时，您可能希望在对象实例上调用一个方法，同时允许容器自动注入该方法的依赖项。例如，给定以下类：

<?php

namespace App;

use App\Services\AppleMusic;

class PodcastStats
{
    /**
     * 生成新的播客统计报告。
     */
    public function generate(AppleMusic $apple): array
    {
        return [
            // ...
        ];
    }
}

您可以通过容器调用 generate 方法，如下所示：

use App\PodcastStats;
use Illuminate\Support\Facades\App;

$stats = App::call([new PodcastStats, 'generate']);

call 方法接受任何 PHP 可调用对象。容器的 call 方法甚至可以用来调用一个闭包，同时自动注入其依赖项：

use App\Services\AppleMusic;
use Illuminate\Support\Facades\App;

$result = App::call(function (AppleMusic $apple) {
    // ...
});

容器事件

每次服务容器解析一个对象时，都会触发一个事件。您可以使用 resolving 方法监听此事件：

use App\Services\Transistor;
use Illuminate\Contracts\Foundation\Application;

$this->app->resolving(Transistor::class, function (Transistor $transistor, Application $app) {
    // 当容器解析 "Transistor" 类型的对象时调用...
});

$this->app->resolving(function (mixed $object, Application $app) {
    // 当容器解析任何类型的对象时调用...
});

如您所见，正在解析的对象会被传递给回调，允许您在对象交给其使用者之前，设置任何额外的属性。

重新绑定

rebinding 方法允许您监听服务何时被重新绑定到容器中，这意味着它在初始绑定后再次注册或被覆盖。当您需要在每次特定绑定被更新时更新依赖项或修改行为时，这非常有用：

use App\Contracts\PodcastPublisher;
use App\Services\SpotifyPublisher;
use App\Services\TransistorPublisher;
use Illuminate\Contracts\Foundation\Application;

$this->app->bind(PodcastPublisher::class, SpotifyPublisher::class);

$this->app->rebinding(
    PodcastPublisher::class,
    function (Application $app, PodcastPublisher $newInstance) {
        //
    },
);

// 新的绑定将触发 rebinding 闭包...
$this->app->bind(PodcastPublisher::class, TransistorPublisher::class);

在这个例子中，当 PodcastPublisher 的绑定被更新时，rebinding 闭包会被触发。

PSR-11

Laravel 的服务容器实现了【PSR-11】接口。因此，您可以通过类型提示 PSR-11 容器接口来获取 Laravel 容器的实例：

use App\Services\Transistor;
use Psr\Container\ContainerInterface;

Route::get('/', function (ContainerInterface $container) {
    $service = $container->get(Transistor::class);

    // ...
});

如果给定的标识符无法解析，容器将抛出一个异常。如果标识符从未被绑定过，抛出的异常将是 Psr\Container\NotFoundExceptionInterface 的实例。如果标识符已经绑定但无法解析，则会抛出 Psr\Container\ContainerExceptionInterface 的实例。