服务容器

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

简介

Laravel 服务容器是一个强大的工具，用于管理类依赖项并执行依赖项注入。依赖项注入是一个花哨的短语，其本质是：类依赖项通过构造函数或某些情况下的“setter”方法“注入”到类中。

让我们看一个简单的例子

<?php
 
namespace App\Http\Controllers;
 
use App\Services\AppleMusic;
use Illuminate\View\View;
 
class PodcastController extends Controller
{
    /**
     * Create a new controller instance.
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}
 
    /**
     * Show information about the given podcast.
     */
    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) {
    die($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));
});

绑定单例

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

绑定实例

你还可以使用 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;
 
/**
 * Create a new class instance.
 */
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');
          });

上下文属性

由于上下文绑定通常用于注入驱动程序或配置值的实现，因此 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、DB、Log、RouteParameter 和 Tag 属性。

<?php
 
namespace App\Http\Controllers;
 
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\Tag;
use Illuminate\Contracts\Auth\Guard;
use Illuminate\Contracts\Cache\Repository;
use Illuminate\Contracts\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,
        #[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 Illuminate\Contracts\Container\ContextualAttribute;
 
#[Attribute(Attribute::TARGET_PARAMETER)]
class Config implements ContextualAttribute
{
    /**
     * Create a new attribute instance.
     */
    public function __construct(public string $key, public mixed $default = null)
    {
    }
 
    /**
     * Resolve the configuration value.
     *
     * @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
{
    /**
     * The filter instances.
     *
     * @var array
     */
    protected $filters;
 
    /**
     * Create a new class instance.
     */
    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;
 
/**
 * Create a new class instance.
 */
public function __construct(
    protected Container $container,
) {}

自动注入

或者，更重要的是，您可以在由容器解析的类的构造函数中类型提示依赖项，包括控制器、事件监听器、中间件等等。此外，您可以在队列作业的handle方法中类型提示依赖项。在实践中，这就是大多数对象应该如何由容器解析的。

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

<?php
 
namespace App\Http\Controllers;
 
use App\Services\AppleMusic;
 
class PodcastController extends Controller
{
    /**
     * Create a new controller instance.
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}
 
    /**
     * Show information about the given podcast.
     */
    public function show(string $id): Podcast
    {
        return $this->apple->findPodcast($id);
    }
}

方法调用和注入

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

<?php
 
namespace App;
 
use App\Services\AppleMusic;
 
class PodcastStats
{
    /**
     * Generate a new podcast stats report.
     */
    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) {
    // Called when container resolves objects of type "Transistor"...
});
 
$this->app->resolving(function (mixed $object, Application $app) {
    // Called when container resolves object of any type...
});

如您所见，正在解析的对象将传递给回调，允许您在将其提供给使用者之前设置对象上的任何其他属性。

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