服务容器-Laravel 文档-果果开发

简介

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 的数据源获取播客。因此，我们将注入一个能够获取播客的服务。由于该服务是通过注入的方式传入的，在测试应用时，我们就能轻松地对 AppleMusic 服务进行“mock”（模拟），也就是创建一个该服务的虚拟实现。

深入理解 Laravel 服务容器，对于构建功能强大的大型应用，以及为 Laravel 核心本身贡献代码都至关重要。

零配置解析

如果一个类没有依赖，或者仅依赖其他具体类（而非接口），容器就无需被告知如何解析该类。例如，您可以将以下代码放入 routes/web.php 文件中：

<?php

class Service
{
    // ...
}

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

在这个示例中，当访问应用的 / 路由时，容器会自动解析 Service 类并将其注入到路由的处理程序中。这具有变革性的意义。这意味着您在开发应用时，无需担心繁杂的配置文件，就能使用依赖注入。

值得庆幸的是，在构建 Laravel 应用时，您编写的许多类都能通过容器自动获取其依赖，其中包括控制器、事件监听器、中间件等等。此外，您还可以在队列任务的 handle 方法中对依赖进行类型提示。一旦体验到自动且零配置的依赖注入的强大功能，就会觉得没有它根本无法进行开发。

何时使用容器

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

use Illuminate\Http\Request;

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

在很多情况下，得益于自动依赖注入和门面，您无需手动向容器绑定或从容器中解析任何内容，就能构建 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));
});

为方便起见，您可以省略将要注册的类或接口名作为单独的参数传入，而是让 Laravel 从您提供给 bind 方法的闭包的返回类型中推断类型：

App::bind(function (Application $app): Transistor {
    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));
});

单例属性

此外，您可以使用 #[Singleton] 特性标记某个接口或类，以告知容器它只需被解析一次：

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

#[Singleton]
class Transistor
{
    // ...
}

绑定作用域单例

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

作用域属性

此外，您可以使用 #[Scoped] 特性标记某个接口或类，以告知容器它在给定的 Laravel 请求 / 任务生命周期内只应被解析一次：

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Scoped;

#[Scoped]
class Transistor
{
    // ...
}

绑定实例

你还可以使用 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,
) {}

Bind 特性

Laravel 还提供了一个 Bind 特性（attribute），使用起来更为便捷。你可以将该特性应用到任意接口上，以此告知 Laravel：每当请求该接口时，应当自动注入哪个实现。使用 Bind 特性时，无需在应用的服务提供者中再执行任何额外的服务注册操作。

此外，可以在一个接口上添加多个 Bind 特性，以便针对特定的环境集合配置要注入的不同实现：

<?php

namespace App\Contracts;

use App\Services\FakeEventPusher;
use App\Services\RedisEventPusher;
use Illuminate\Container\Attributes\Bind;

#[Bind(RedisEventPusher::class)]
#[Bind(FakeEventPusher::class, environments: ['local', 'testing'])]
interface EventPusher
{
    // ...
}

除此之外，还可以应用 Singleton 和 Scoped 特性，用于指示容器绑定应当只解析一次，还是每次请求或作业的生命周期中解析一次：

use App\Services\RedisEventPusher;
use Illuminate\Container\Attributes\Bind;
use Illuminate\Container\Attributes\Singleton;

#[Bind(RedisEventPusher::class)]
#[Singleton]
interface EventPusher
{
    // ...
}

对于依赖任意条件的绑定，可以使用 BindWhen 特性。该闭包可以接收容器，并且当需要应用该绑定时应返回 true。Bind 和 BindWhen 特性会按照声明的顺序进行求值：

use App\Services\BetaEventPusher;
use Illuminate\Container\Attributes\BindWhen;
use Laravel\Pennant\Feature;

#[BindWhen(BetaEventPusher::class, static fn () => Feature::active('beta-events'))]
interface EventPusher
{
    // ...
}

BindWhen 特性需要 PHP 8.5 或更高版本。

上下文绑定

有时你可能会遇到两个使用同一接口的类，但希望向每个类注入不同的实现。例如，两个控制器可能依赖 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');
    });

上下文特性

由于上下文绑定常用于注入驱动的实现或配置值，Laravel 提供了多种上下文绑定特性，无需在服务提供者中手动定义上下文绑定，就能注入这类值。

例如，Storage 特性可用于注入特定的存储磁盘：

<?php

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、Context、DB、Give、Log、RequestAttribute、RouteParameter 以及 Tag 特性：

<?php

namespace App\Http\Controllers;

use App\Contracts\UserRepository;
use App\Models\Organization;
use App\Models\Photo;
use App\Repositories\DatabaseRepository;
use Illuminate\Container\Attributes\Auth;
use Illuminate\Container\Attributes\Cache;
use Illuminate\Container\Attributes\Config;
use Illuminate\Container\Attributes\Context;
use Illuminate\Container\Attributes\DB;
use Illuminate\Container\Attributes\Give;
use Illuminate\Container\Attributes\Log;
use Illuminate\Container\Attributes\RequestAttribute;
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,
        #[Context('uuid')] protected string $uuid,
        #[Context('ulid', hidden: true)] protected string $ulid,
        #[DB('mysql')] protected Connection $connection,
        #[Give(DatabaseRepository::class)] protected UserRepository $users,
        #[Log('daily')] protected LoggerInterface $log,
        #[RequestAttribute('organization')] protected Organization $organization,
        #[RouteParameter] protected Photo $photo,
        #[Tag('reports')] protected iterable $reports,
    ) {
        // ...
    }
}

RouteParameter 特性会解析与变量名匹配的路由参数。如果有需要，你可以显式指定路由参数的名称：#[RouteParameter('photo')]。

RequestAttribute 特性会解析当前请求的属性包中，以给定键存储的值：#[RequestAttribute('organization')]。

此外，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 特性：

<?php

namespace App\Attributes;

use Attribute;
use Illuminate\Contracts\Container\Container;
use Illuminate\Contracts\Container\ContextualAttribute;
use ReflectionParameter;

#[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
     * @param  \ReflectionParameter  $parameter
     * @return mixed
     */
    public static function resolve(self $attribute, Container $container, ReflectionParameter $parameter)
    {
        return $container->make('config')->get($attribute->key, $attribute->default);
    }
}

绑定基本类型

有时你可能遇到一个类，它既接收一些注入的类，也需要注入一个基本类型的值（比如整数）。你可以很方便地使用上下文绑定来注入该类所需的任意值：

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

绑定带类型的可变参数

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

<?php

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 门面或 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) {
        //
    },
);

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

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 的实例。

服务容器

简介