服务容器

简介
- 零配置解析
- 何时使用容器
绑定
解决
- Make 方法
- 自动注入
方法调用和注入
容器事件
- 重新绑定
PSR-11

简介

Laravel 服务容器是一个强大的工具，用于管理类依赖和执行依赖注入。依赖注入是一个花哨的说法，其本质上意味着：类依赖通过构造函数，或者在某些情况下，通过“设置器”方法被“注入”到类中。

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

php

<?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

<?php

class Service
{
    // ...
}

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

在此示例中，访问您应用程序的 / 路由将自动解析 Service 类并将其注入到您的路由处理器中。这具有颠覆性。这意味着您可以开发您的应用程序并利用依赖注入而无需担心臃肿的配置文件。

值得庆幸的是，在构建 Laravel 应用程序时，您将编写的许多类会自动通过容器接收其依赖项，包括控制器，事件监听器，中间件，以及更多。此外，您可以在队列任务的handle方法中类型提示依赖项。一旦您体会到自动和零配置依赖注入的强大功能，就觉得没有它就无法进行开发。

何时使用容器

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

php

use Illuminate\Http\Request;

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

在许多情况下，得益于自动依赖注入和外观模式，你可以构建 Laravel 应用程序而无需手动绑定或从容器中解析任何东西。**那么，你什么时候会手动与容器交互呢？**让我们审视两种情况。

首先，如果你编写一个实现接口的类，并且希望在路由或类构造器中对该接口进行类型提示，你必须[告诉容器如何解析该接口](#binding-interfaces-to-implementations)。其次，如果你正在[编写一个 Laravel 包](/zh-cn/docs/laravel/12.x/packages)，打算与其他 Laravel 开发者分享，你可能需要将你的包的服务绑定到容器中。

绑定

绑定基础

简单绑定

几乎所有服务容器绑定都将在服务提供者中注册，因此这些示例大部分将演示在该上下文中如何使用容器。

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

php

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 外观来实现：

php

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

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

你可以在尚未注册给定类型的绑定时，使用 bindIf 方法来注册容器绑定:

php

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

为方便起见，你可以省略提供你希望注册的类或接口名作为一个单独的参数，转而让 Laravel 从你提供给 bind 方法的闭包的返回类型中推断类型：

php

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

[!NOTE]
如果类不依赖于任何接口, 则无需将它们绑定到容器中. 容器无需被告知如何构建这些对象, 因为它可以通过反射自动解析这些对象.

绑定一个单例

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

php

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 方法来注册一个单例容器绑定，仅当针对给定类型尚未注册绑定时：

php

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

单例属性

php

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

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

绑定作用域单例

scoped 方法将类或接口绑定到容器中，使其在给定的 Laravel 请求 / 任务生命周期内只解析一次。尽管此方法类似于 singleton 方法，但使用 scoped 方法注册的实例将在 Laravel 应用程序启动新“生命周期”时被刷新，例如当 Laravel Octane 工作进程处理新请求时，或当 Laravel 队列工作进程处理新任务时：

php

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 方法注册一个作用域容器绑定，仅当给定类型尚未注册绑定时：

php

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

作用域属性

或者，你可以使用 #[Scoped] 属性标记一个接口或类，以告知容器它应该在一个给定的 Laravel 请求/任务生命周期中被解析一次：

php

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Scoped;

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

绑定实例

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

php

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

$service = new Transistor(new PodcastParser);

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

绑定接口到实现

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

php

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

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

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

php

use App\Contracts\EventPusher;

/**
 * Create a new class instance.
 */
public function __construct(
    protected EventPusher $pusher,
) {}

绑定属性

Laravel 也提供了一个 Bind 属性，以增加便利性。你可以将此属性应用到任何接口上，以告诉 Laravel 每当请求该接口时应自动注入哪个实现。当使用 Bind 属性时，无需在你的应用程序的服务提供者中执行任何额外的服务注册。

此外，可以在接口上放置多个 Bind 属性，以配置应针对给定环境集注入的不同实现：

php

<?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
{
    // ...
}

此外，单例和作用域属性可以应用，以指示容器绑定是应该解析一次，还是在每个请求/作业生命周期内解析一次：

php

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 提供了一个简单、流畅的接口来定义此行为：

php

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

<?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, 以及标签属性：

php

<?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 属性，用于将当前认证用户注入到给定的路由或类中：

php

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

<?php

namespace App\Attributes;

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

绑定原语

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

php

use App\Http\Controllers\UserController;

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

有时一个类可能依赖于一个带标签的实例数组。使用 giveTagged 方法，你可以轻松注入所有带有该标签的容器绑定：

php

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

如果您需要从您应用程序的某个配置文件中注入一个值，您可以使用 giveConfig 方法：

php

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

绑定类型化可变参数

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

php

<?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 实例数组的闭包来解决此依赖：

php

$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 实例时解析：

php

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

可变参数标签依赖

有时一个类可能有一个可变参数依赖，该依赖被类型提示为一个给定类 (Report ...$reports)。使用 needs 和 giveTagged 方法，你可以轻松地注入所有带有该标签的容器绑定，以满足给定的依赖项：

php

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

标记

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

php

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

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

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

服务被标记后，你可以轻松地解析所有这些服务，通过容器的 tagged 方法：

php

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

扩展绑定

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

php

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

解决

`make` 方法

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

php

use App\Services\Transistor;

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

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

php

use App\Services\Transistor;

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

该 bound 方法可用于确定某个类或接口是否已明确绑定到容器中：

php

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

如果你在服务提供者之外，在代码中无法访问 $app 变量的位置，你可以使用 App 外观或 app 辅助函数从容器中解析类实例：

php

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

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

$transistor = app(Transistor::class);

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

php

use Illuminate\Container\Container;

/**
 * Create a new class instance.
 */
public function __construct(
    protected Container $container,
) {}

自动注入

此外，更重要的是，你可以在容器解析的类的构造函数中对依赖项进行类型提示，包括控制器，事件监听器，中间件，等等。此外，你可以在队列任务的handle方法中对依赖项进行类型提示。实际上，这是你的大多数对象应该由容器解析的方式。

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

php

<?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

<?php

namespace App;

use App\Services\AppleMusic;

class PodcastStats
{
    /**
     * Generate a new podcast stats report.
     */
    public function generate(AppleMusic $apple): array
    {
        return [
            // ...
        ];
    }
}

您可以像这样通过容器调用 generate 方法：

php

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

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

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

php

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

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

容器事件

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

php

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

正如你所见，正在被解析的对象将被传递给回调函数，使你可以在对象被交付给其消费者之前，为其设置任何额外的属性。

重绑定

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

php

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

// New binding will trigger rebinding closure...
$this->app->bind(PodcastPublisher::class, TransistorPublisher::class);

PSR-11

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

php

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

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

    // ...
});

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

服务容器

简介
- 零配置解析
- 何时使用容器
绑定
解决
- Make 方法
- 自动注入
方法调用和注入
容器事件
- 重新绑定
PSR-11

简介

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

php

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

对 Laravel 服务容器的深入理解，对于构建一个功能强大、规模庞大的应用程序以及为 Laravel 核心本身做贡献都至关重要。

零配置解析

如果一个类没有依赖项或只依赖于其他具体类 (而非接口), 容器就不需要被告知如何解析该类。例如, 你可以将以下代码放置在你的 routes/web.php 文件中:

php

<?php

class Service
{
    // ...
}

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

何时使用容器

php

use Illuminate\Http\Request;

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

绑定

绑定基础

简单绑定

几乎所有服务容器绑定都将在服务提供者中注册，因此这些示例大部分将演示在该上下文中如何使用容器。

php

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 外观来实现：

php

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

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

你可以在尚未注册给定类型的绑定时，使用 bindIf 方法来注册容器绑定:

php

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

为方便起见，你可以省略提供你希望注册的类或接口名作为一个单独的参数，转而让 Laravel 从你提供给 bind 方法的闭包的返回类型中推断类型：

php

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

[!NOTE]
如果类不依赖于任何接口, 则无需将它们绑定到容器中. 容器无需被告知如何构建这些对象, 因为它可以通过反射自动解析这些对象.

绑定一个单例

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

php

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 方法来注册一个单例容器绑定，仅当针对给定类型尚未注册绑定时：

php

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

单例属性

php

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

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

绑定作用域单例

php

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 方法注册一个作用域容器绑定，仅当给定类型尚未注册绑定时：

php

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

作用域属性

或者，你可以使用 #[Scoped] 属性标记一个接口或类，以告知容器它应该在一个给定的 Laravel 请求/任务生命周期中被解析一次：

php

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Scoped;

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

绑定实例

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

php

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

$service = new Transistor(new PodcastParser);

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

绑定接口到实现

php

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

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

php

use App\Contracts\EventPusher;

/**
 * Create a new class instance.
 */
public function __construct(
    protected EventPusher $pusher,
) {}

绑定属性

此外，可以在接口上放置多个 Bind 属性，以配置应针对给定环境集注入的不同实现：

php

<?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
{
    // ...
}

此外，单例和作用域属性可以应用，以指示容器绑定是应该解析一次，还是在每个请求/作业生命周期内解析一次：

php

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

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

上下文绑定

php

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

上下文属性

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

php

<?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, 以及标签属性：

php

<?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 属性，用于将当前认证用户注入到给定的路由或类中：

php

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

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

定义自定义属性

php

<?php

namespace App\Attributes;

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

绑定原语

php

use App\Http\Controllers\UserController;

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

有时一个类可能依赖于一个带标签的实例数组。使用 giveTagged 方法，你可以轻松注入所有带有该标签的容器绑定：

php

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

如果您需要从您应用程序的某个配置文件中注入一个值，您可以使用 giveConfig 方法：

php

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

绑定类型化可变参数

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

php

<?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 实例数组的闭包来解决此依赖：

php

$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 实例时解析：

php

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

可变参数标签依赖

php

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

标记

php

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

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

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

服务被标记后，你可以轻松地解析所有这些服务，通过容器的 tagged 方法：

php

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

扩展绑定

php

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

解决

`make` 方法

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

php

use App\Services\Transistor;

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

php

use App\Services\Transistor;

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

该 bound 方法可用于确定某个类或接口是否已明确绑定到容器中：

php

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

如果你在服务提供者之外，在代码中无法访问 $app 变量的位置，你可以使用 App 外观或 app 辅助函数从容器中解析类实例：

php

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

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

$transistor = app(Transistor::class);

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

php

use Illuminate\Container\Container;

/**
 * Create a new class instance.
 */
public function __construct(
    protected Container $container,
) {}

自动注入

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

php

<?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

<?php

namespace App;

use App\Services\AppleMusic;

class PodcastStats
{
    /**
     * Generate a new podcast stats report.
     */
    public function generate(AppleMusic $apple): array
    {
        return [
            // ...
        ];
    }
}

您可以像这样通过容器调用 generate 方法：

php

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

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

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

php

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

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

容器事件

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

php

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

正如你所见，正在被解析的对象将被传递给回调函数，使你可以在对象被交付给其消费者之前，为其设置任何额外的属性。

重绑定

php

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

// New binding will trigger rebinding closure...
$this->app->bind(PodcastPublisher::class, TransistorPublisher::class);

PSR-11

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

php

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

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

    // ...
});

文档导航

服务容器

简介

零配置解析

何时使用容器

绑定

绑定基础

简单绑定

绑定一个单例

单例属性

绑定作用域单例

作用域属性

绑定实例

绑定接口到实现

绑定属性

上下文绑定

上下文属性

定义自定义属性

绑定原语

绑定类型化可变参数

可变参数标签依赖

标记

扩展绑定

解决

make 方法

自动注入

方法调用和注入

容器事件

重绑定

PSR-11

服务容器

简介

零配置解析

何时使用容器

绑定

绑定基础

简单绑定

绑定一个单例

单例属性

绑定作用域单例

作用域属性

绑定实例

绑定接口到实现

绑定属性

上下文绑定

上下文属性

定义自定义属性

绑定原语

绑定类型化可变参数

可变参数标签依赖

标记

扩展绑定

解决

make 方法

自动注入

方法调用和注入

容器事件

重绑定

PSR-11

`make` 方法

`make` 方法