服务容器

简介

Laravel 服务容器是用于管理类依赖并执行依赖注入的强大工具。依赖注入听起来很高深，本质上是指：类的依赖通过构造函数，或在某些情况下通过「setter」方法「注入」到类中。

我们来看一个简单示例：

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 等数据源获取播客。因此，我们将注入一个能够获取播客的服务。由于服务是注入的，在测试应用时我们可以轻松「mock」或创建 AppleMusic 服务的虚拟实现。

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

零配置解析

若某个类没有依赖，或仅依赖其他具体类（而非接口），则无需指示容器如何解析该类。例如，你可以将以下代码放在 routes/web.php 文件中：

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 Facade 进行：

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

INFO

若类不依赖任何接口，则无需将其绑定到容器。容器无需被告知如何构建这些对象，因为它可以使用反射自动解析它们。

绑定单例

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 方法，仅在给定类型尚未注册绑定时才注册单例容器绑定：

php

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

绑定作用域单例

scoped 方法将类或接口绑定到容器中，且在给定的 Laravel 请求 / 任务生命周期内只应被解析一次。该方法与 singleton 类似，但使用 scoped 注册的实例会在 Laravel 应用开启新的「生命周期」时被清空，例如当 Laravel Octane worker 处理新请求，或 Laravel 队列 worker 处理新任务时：

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;

php

/**
 * 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

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

<?php

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

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

绑定原始值

有时某个类会接收一些注入的类，同时还需要注入整数等原始值。你可以轻松使用上下文绑定来注入类可能需要的任何值：

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

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

php

/**
 * 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 方法：

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

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

call 方法接受任何 PHP callable。容器的 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...
});

可以看到，正在解析的对象会传给回调，使你可以在对象交给消费者之前设置任何额外属性。

重新绑定

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

// New binding will trigger rebinding closure...
$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 的实例。

服务容器 ​

简介 ​

零配置解析 ​

何时使用容器 ​

绑定 ​

绑定基础 ​

简单绑定 ​

绑定单例 ​

绑定作用域单例 ​

绑定实例 ​

将接口绑定到实现 ​

上下文绑定 ​

上下文属性 ​

定义自定义属性 ​

绑定原始值 ​

绑定类型化可变参数 ​

可变标签依赖 ​

打标签 ​

扩展绑定 ​

解析 ​

make 方法 ​

自动注入 ​

方法调用与注入 ​

容器事件 ​

重新绑定 ​

PSR-11 ​