Сервіс-контейнер · Laravel

Вступ

Контейнер сервісів Laravel - потужний інструмент для керування залежностями класів і впровадження залежностей (dependency injection). Впровадження залежностей - вигадлива назва простої речі: залежності класу «впроваджуються» в нього через конструктор або, подекуди, через «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. Тому ми впровадимо сервіс, здатний отримувати подкасти. Оскільки сервіс впроваджено, під час тестування застосунку ми легко зробимо «mock» або підставну реалізацію сервісу AppleMusic.

Глибоке розуміння контейнера сервісів Laravel необхідне і для побудови потужного великого застосунку, і для внеску в саме ядро Laravel.

Розвʼязання без конфігурації

Якщо клас не має залежностей або залежить лише від інших конкретних класів (не інтерфейсів), контейнеру не треба пояснювати, як цей клас створити. Наприклад, ви можете покласти такий код у файл routes/web.php:

<?php

class Service
{
    // ...
}

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

У цьому прикладі звернення до маршруту / вашого застосунку автоматично створить клас Service і впровадить його в обробник маршруту. Це змінює правила гри. Це означає, що ви можете розробляти застосунок і користуватися впровадженням залежностей, не переймаючись роздутими конфігураційними файлами.

На щастя, багато класів, які ви писатимете під час розробки на Laravel, автоматично отримують свої залежності через контейнер, зокрема контролери, слухачі подій, middleware та інші. Крім того, ви можете вказувати типи залежностей у методі handle завдань у черзі. Щойно ви відчуєте смак автоматичного впровадження залежностей без жодної конфігурації, розробляти без нього здаватиметься неможливим.

Коли користуватися контейнером

Завдяки розвʼязанню без конфігурації ви часто вказуватимете типи залежностей у маршрутах, контролерах, слухачах подій та інших місцях, жодного разу не звертаючись до контейнера вручну. Наприклад, ви можете вказати тип обʼєкта Illuminate\Http\Request у визначенні маршруту, щоб легко дістатися поточного запиту. Хоча для написання цього коду взаємодіяти з контейнером не доводиться, саме він за лаштунками керує впровадженням цих залежностей:

use Illuminate\Http\Request;

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

У багатьох випадках, завдяки автоматичному впровадженню залежностей і фасадам, ви можете будувати застосунки на 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

Як альтернативу ви можете позначити інтерфейс чи клас атрибутом #[Singleton], щоб указати контейнеру розвʼязувати його один раз:

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

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

Привʼязка scoped-сінглтонів

Метод 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 реєструє scoped-привʼязку тільки тоді, коли для вказаного типу привʼязки ще немає:

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

Атрибут Scoped

Як альтернативу ви можете позначити інтерфейс чи клас атрибутом #[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);

Цей вираз каже контейнеру впроваджувати RedisEventPusher, коли класу потрібна реалізація EventPusher. Тепер ми можемо вказати інтерфейс EventPusher як тип у конструкторі класу, який розвʼязує контейнер. Памʼятайте: контролери, слухачі подій, middleware та інші типи класів у застосунках Laravel завжди створюються через контейнер:

use App\Contracts\EventPusher;

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

Атрибут Bind

Для додаткової зручності 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
{
    // ...
}

Для привʼязок, які залежать від довільної умови, є атрибут 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
{
    // ...
}

[!NOTE] Атрибут 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 розвʼяже значення, збережене під указаним ключем у attribute bag поточного запиту: #[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 вашого атрибута, який має розвʼязати значення для впровадження в клас, що використовує цей атрибут. У прикладі нижче ми відтворимо вбудований атрибут Config із Laravel:

<?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
{
    /**
     * 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
     * @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');

Привʼязка типізованих variadic-аргументів

Подеколи клас отримує масив типізованих обʼєктів через variadic-аргумент конструктора:

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

Variadic-залежності з тегом

Іноді клас має variadic-залежність, типізовану певним класом (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 створює екземпляр класу з контейнера. Він приймає імʼя класу або інтерфейсу, який ви хочете розвʼязати:

use App\Services\Transistor;

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

Якщо частина залежностей вашого класу не розвʼязується через контейнер, ви можете передати їх асоціативним масивом у метод makeWith. Наприклад, ми можемо вручну передати аргумент конструктора $id, потрібний сервісу Transistor:

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

Автоматичне впровадження

Як альтернативу (і це важливо) ви можете вказати тип залежності в конструкторі класу, який створює контейнер, зокрема контролерів, слухачів подій, middleware тощо. Крім того, типи залежностей можна вказувати в методі 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 callable. Ним можна навіть викликати замикання з автоматичним впровадженням його залежностей:

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. Тому, щоб отримати екземпляр контейнера Laravel, ви можете вказати як тип інтерфейс контейнера PSR-11:

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

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

    // ...
});

Якщо вказаний ідентифікатор розвʼязати не вдається, кидається виняток. Це буде екземпляр Psr\Container\NotFoundExceptionInterface, якщо ідентифікатор ніколи не привʼязували. Якщо ідентифікатор привʼязано, але розвʼязати його не вдалося, кидається екземпляр Psr\Container\ContainerExceptionInterface.