服务容器

• 简介
  • 零配置解析
  • 何时使用容器
• 绑定
  • 绑定基础
  • 绑定接口到实现
  • 上下文绑定
  • 上下文属性
  • 绑定原始值
  • 绑定类型化可变参数
  • 标签
  • 扩展绑定
• 解析
  • Make 方法
  • 自动注入
• 方法调用和注入
• 容器事件
  • 重新绑定
• PSR-11

简介

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 服务的虚拟实现。

深入理解 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));
});

NOTE

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

绑定单例

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,
) {}

绑定属性

Laravel 还提供了 Bind 属性以增加便利性。您可以将此属性应用于任何接口，以告诉 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
{
    // ...
}

上下文绑定

有时您可能有两个使用相同接口的类，但您希望在每个类中注入不同的实现。例如，两个控制器可能依赖于 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、RouteParameter 和 Tag 属性：

<?php

namespace App\Http\Controllers;

use App\Contracts\UserRepository;
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\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,
        #[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 属性：

<?php

namespace App\Attributes;

use Attribute;
use Illuminate\Contracts\Container\Container;
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);
    }
}

绑定原始值

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

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->tag(FirstReport::class, 'reports');
$this->app->tag([SecondReport::class, ThirdReport::class], 'reports');

一旦服务被标记，您可以通过 tagged 方法轻松解析它们：

$this->app->bind(ReportAggregator::class, function (Application $app) {
    return new ReportAggregator($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);

如果您不在服务提供者中，您可以使用 App 门面：

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

$transistor = App::make(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,
    ) {}
}

方法调用和注入

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

<?php

namespace App;

use App\Services\AppleMusic;

class Service
{
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    public function processPodcast($id)
    {
        // ...
    }
}

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

use App\Service;
use Illuminate\Support\Facades\App;

$service = App::make(Service::class);

$result = App::call([$service, 'processPodcast'], ['id' => 1]);

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 事件。您可以使用 rebinding 方法监听此事件：

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

$this->app->bind(EventPusher::class, function (Application $app) {
    return new RedisEventPusher(
        $app->make('redis.connection')
    );
});

$this->app->rebinding(EventPusher::class, function (Application $app) {
    // 当 "EventPusher" 绑定被修改时调用...
});

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