Що робить service provider і чим bind відрізняється від singleton і scoped?

Пояснення

Провайдери - це список класів, який Laravel проходить двічі. Спершу Application::registerConfiguredProviders() бере провайдери з bootstrap/providers.php (у Laravel 11+ саме там, а не в config/app.php) плюс знайдені через package discovery у bootstrap/cache/packages.php і викликає в кожного register(). Коли зареєстровані всі, окремим проходом іде Application::boot() з викликом boot() у тому ж порядку. На цьому поділі тримається вся роль провайдера: у register() ви не знаєте, що вже лежить у контейнері, бо чужий провайдер може стояти нижче в списку, а в boot() знаєте напевно. Звідси правило, яке звучить догматично, поки не спіймаєш баг: у register() тільки привʼязки й mergeConfigFrom(), у boot() - маршрути, слухачі подій, Gate::define(), Blade-директиви, publishes(). Виклик make() усередині register() небезпечний і поза питанням порядку: він заморожує обʼєкт до того, як інший провайдер устигне зробити йому extend(), і передчасно піднімає відкладені провайдери.

Три способи привʼязки відрізняє одне: скільки живе результат. bind() зберігає рецепт і виконує його на кожне розвʼязання. singleton() - це той самий bind() з прапорцем shared: true: перший make() кладе обʼєкт у $instances, усі наступні дістають його звідти. Слово «singleton» тут оманливе, бо життя обмежене життям контейнера, а не процесу PHP: під FPM контейнер помирає разом із запитом, тому singleton там де-факто був request-scoped, і покоління розробників писало його не замислюючись. scoped() робить те саме, що singleton(), плюс записує abstract у масив $scopedInstances - саме цей масив вичищає forgetScopedInstances(). Поруч є instance() (покласти готовий обʼєкт), bindIf()/singletonIf() для пакетів, які не мають затирати вибір застосунку, і extend() для обгортання чужої реалізації.

Різниця між singleton і scoped стає видимою рівно тоді, коли контейнер переживає запит. Octane тримає один Application на воркер і між запитами прогонює слухача FlushTemporaryContainerInstances, який викликає forgetScopedInstances(); черговий воркер робить те саме через Worker::resetScope() перед кожною задачею. Тому scoped - це «один на запит або задачу», а singleton під Octane - «один на воркер, поки його не перезапустять». Сервіс, який тримає в полі Request, поточного користувача, locale чи тенанта, у першому випадку безпечний, у другому віддасть другому відвідувачу дані першого. Скидання не всесильне: воно прибирає обʼєкт із контейнера, але не рятує від захопленого замиканням $request, статичної властивості або вже розвʼязаної залежності всередині іншого singleton-а. Для таких випадків у config/octane.php є списки flush і warm.

Відкладений провайдер живе за домовленістю: його не чіпають, поки хтось не попросить звʼязку. Клас реалізує DeferrableProvider і повертає з provides() перелік звʼязок; ProviderRepository компілює bootstrap/cache/services.php, де eager-провайдери реєструються завжди, а deferred лежать картою «звʼязка → провайдер». Коли make() натрапляє на невідому звʼязку з цієї карти, викликається registerDeferredProvider(), який реєструє провайдер і одразу бутить, якщо застосунок уже завантажений. Маніфест перебудовується сам, щойно змінився список провайдерів, і зникає після optimize:clear. Дві пастки трапляються постійно. Перша: provides() мусить містити той самий рядок, за яким реально резолвлять - забіндили 'pdf.renderer', а повернули PdfRenderer::class, і привʼязка не зʼявиться ніколи. Друга: boot() відкладеного провайдера виконується непередбачувано пізно, тому маршрут або Event::listen() там тихо не працюють; для подій є окремий вихід - метод when(), який повертає імена подій, на які провайдер підпишуть ліниво.

Контекстна привʼязка закриває те, чого autowiring не може за визначенням. Скаляр без значення за замовчуванням дає BindingResolutionException: Unresolvable dependency, і лікується він через when(X::class)->needs('$dpi')->give(...) або ->giveConfig('pdf.dpi'). Один інтерфейс із двома реалізаціями для різних споживачів - той самий when()->needs()->give(), а для наборів однотипних сервісів є tag()/giveTagged(). Механіка тут неочевидна: при контекстному розвʼязанні контейнер навмисно ігнорує кеш $instances і не пише туди результат, інакше перший споживач зафіксував би свою реалізацію для всього застосунку. З Laravel 11 частину цих випадків забирають контекстні атрибути в сигнатурі (#[Config], #[Storage], #[CurrentUser]), а Laravel 12 додав #[Bind], #[Singleton] і #[Scoped] на інтерфейсі. Це менше коду, але вибір реалізації переїжджає в клас-споживач, і підмінити його одним рядком у тесті вже не вийде. Загальна межа лишається простою: провайдери потрібні інтерфейсам, скалярам і налаштуванню пакетів, а не кожному сервісу - конкретний клас із типізованим конструктором контейнер збере й без жодної реєстрації.

КодPHP

// bootstrap/providers.php (Laravel 11+) містить лише список класів провайдерів.
final class PdfServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        // Конфіг пакета треба злити до того, як хтось прочитає config('pdf.*').
        $this->mergeConfigFrom(__DIR__.'/../../config/pdf.php', 'pdf');

        // Новий обʼєкт на кожну інʼєкцію: рендерер накопичує стан документа.
        $this->app->bind(PdfRenderer::class, fn (Application $app) => new PdfRenderer(
            $app->make(BinaryLocator::class),
        ));

        // Один на процес: усередині лише шлях до бінарника, даних запиту немає.
        $this->app->singleton(BinaryLocator::class);

        // Тримає locale й поточного тенанта, тому лише scoped:
        // Octane скидає його через forgetScopedInstances() між запитами,
        // а Worker::resetScope() - перед кожною задачею черги.
        $this->app->scoped(RenderContext::class);

        // Скалярний $dpi контейнер сам не розвʼяже: даємо контекстно.
        $this->app->when(PdfRenderer::class)
            ->needs('$dpi')
            ->giveConfig('pdf.dpi', 150);

        // Той самий інтерфейс, різні диски для різних споживачів.
        $this->app->when(InvoiceExporter::class)
            ->needs(Filesystem::class)
            ->give(fn () => Storage::disk('invoices'));
    }

    public function boot(): void
    {
        // Спрацює лише тоді, коли хтось витягне звʼязку з provides().
        // Тому Route:: і Event::listen() сюди класти не можна.
        $this->publishes([__DIR__.'/../../config/pdf.php' => config_path('pdf.php')], 'pdf');
    }

    /** @return array<int, string> Без цього списку провайдер не завантажиться ніколи. */
    public function provides(): array
    {
        return [PdfRenderer::class, BinaryLocator::class, RenderContext::class];
    }
}

Що хоче почути інтервʼюер

Що завантаження йде у два проходи: спершу `register()` в усіх провайдерів, потім `boot()` в усіх, і саме тому в `boot()` вже можна розраховувати на чужі привʼязки, а в `register()` ні.

Що `singleton()` - це `bind($abstract, $concrete, shared: true)`, тобто той самий механізм плюс збереження результату в `$instances`; час життя обмежений життям контейнера, а не «назавжди».

Що `scoped()` додатково реєструє abstract у `$scopedInstances`, і `forgetScopedInstances()` викидає саме їх: під Octane це робить `FlushTemporaryContainerInstances`, у `queue:work` - `Worker::resetScope()` перед кожною задачею.

Що `DeferrableProvider` + `provides()` відкладають реєстрацію до першого `make()` потрібної звʼязки, а карта «звʼязка → провайдер» лежить у `bootstrap/cache/services.php`.

Що контекстна привʼязка `when()->needs()->give()` вирішує дві задачі, яких autowiring не тягне: скаляри в конструкторі й дві реалізації одного інтерфейсу для різних споживачів.

Типові помилки

Класти `Route::`, `Event::listen()`, `Gate::define()` або `View::composer()` у відкладений провайдер: його `boot()` виконається лише тоді, коли хтось витягне звʼязку з `provides()`, а до того маршрут просто не існує.

Оголосити провайдер `DeferrableProvider` і залишити `provides()` порожнім або з іншим ключем, ніж той, за яким реально резолвлять: привʼязка не зареєструється ніколи, а помилка буде `Target is not instantiable`.

Резолвити залежності прямо в `register()`: провайдер потрібного сервісу може бути ще не зареєстрований, а обʼєкт заморозиться до того, як інший провайдер устигне його `extend()`.

Ставити `singleton` сервісу, який тримає `Request`, поточного користувача, `locale` чи Eloquent-модель: під FPM це непомітно, під Octane і в довгих чергових воркерах стан протікає між запитами.

Вважати, що `scoped` рятує від будь-якого протікання: воно скидає лише сам обʼєкт із контейнера, а замикання, яке захопило `$request` у `singleton`, або статична властивість класу лишаються.

Плодити провайдер під кожен сервіс: конкретні класи з типізованим конструктором контейнер створює без жодної реєстрації, провайдер потрібен інтерфейсам, скалярам і налаштуванню пакетів.

ПОРАДА

Тримайте дві осі й не змішуйте їх. Перша - час: `register()` до всього, `boot()` після всіх реєстрацій. Друга - життя обʼєкта: `bind` (щоразу новий), `singleton` (один на життя контейнера), `scoped` (один на запит або задачу). Далі одним реченням додайте, що `scoped` існує саме заради Octane й довгих воркерів, а `deferred` - це компроміс, який коштує вам маршрутів і слухачів у `boot()`.

Додаткові питанняЗ ВІДПОВІДЯМИ

`Application::registerConfiguredProviders()` проходить список провайдерів і викликає `register()` у кожного, і лише потім `Application::boot()` другим проходом викликає `boot()`. Тому в `register()` існують тільки ті привʼязки, чиї провайдери йшли раніше в списку, і покладатися на порядок не можна. Туди кладуть `bind`/`singleton`/`scoped`/`instance`, контекстні привʼязки, теги і `mergeConfigFrom()` (він має відпрацювати до того, як хтось прочитає `config('pdf.dpi')`). У `boot()` іде все, що вимагає готового застосунку: `Route::`, `Event::listen()`, `Gate::define()`, `Blade::directive()`, `Validator::extend()`, `publishes()`, `loadMigrationsFrom()`, `Model::preventLazyLoading()`. Практичні наслідки плутанини: виклик `make()` у `register()` заморожує обʼєкт до того, як інший провайдер устигне його `extend()`, і, гірше, передчасно вантажить відкладені провайдери, зводячи нанівець їхній сенс. Зворотна помилка м’якша: `bind()` у `boot()` спрацює, але не вплине на вже розвʼязані singleton-и. Корисна деталь: `boot()` викликається через `$this->app->call()`, тому в його сигнатуру можна вписати залежності (`public function boot(Router $router): void`), а `register()` викликається напряму і method injection там не працює. Якщо треба щось зробити після всіх `boot()`, є `$this->app->booted(fn () => ...)`.

`ProviderRepository::load()` при першому запуску компілює маніфест у `bootstrap/cache/services.php`: провайдери без `DeferrableProvider` потрапляють у `eager` і реєструються на кожному запиті, а решта - у `deferred` як карта «кожен рядок із `provides()` → клас провайдера». Контейнер у `make()` бачить незнайому звʼязку в цій карті і викликає `registerDeferredProvider()`, який реєструє провайдер і, якщо застосунок уже завантажений, одразу викликає його `boot()`. Маніфест перекомпільовується автоматично, коли список провайдерів змінився, і зникає після `optimize:clear`/`clear-compiled`. Виграш реальний тільки тоді, коли `register()` дорогий: створює клієнта, читає файл, будує конфіг стороннього SDK. Для провайдера з трьох `bind()` із замиканнями економія - це кілька викликів методу, бо замикання все одно не виконуються до першого `make()`. Ціна ж відчутна: боту немає, поки нікому не потрібна звʼязка, тому маршрути, слухачі, директиви й міграції з такого провайдера просто не існують. Окремий вихід для подій дає метод `when()` у провайдері: масив імен подій, на які `ProviderRepository::registerLoadEvents()` повісить ліниву реєстрацію, і провайдер піднімуть, щойно така подія станеться. Під Octane сенс відкладення падає майже до нуля: воркер стартує раз, а не на кожен запит.

Симптоми впізнавані: другий користувач бачить чужі дані, `locale` або тенант «залипає» від попереднього запиту, memory-графік воркера росте лінійно й падає лише після `max-requests`. Причина в тому, що під FPM контейнер помирає разом із процесом і будь-який `singleton` де-факто був request-scoped, а Octane тримає той самий `Application` між запитами. Діагностика: подивіться, які обʼєкти сервіс тримає в полях. Небезпечні - `Request`, `Auth`/`User`, `Config`, `Repository` кеша, Eloquent-модель, будь-який лічильник чи масив, що накопичується. Виправлень три, і вони не взаємозамінні. Перше: зробити сервіс stateless і брати запит через `request()` у методі, а не через конструктор. Друге: замінити `singleton` на `scoped` для обʼєктів, які за визначенням живуть один запит (контекст рендерингу, поточний тенант) - Octane викидає їх через `forgetScopedInstances()` у слухачі `FlushTemporaryContainerInstances` на `RequestReceived`. Третє: те, що переписати не можна, додати в `config/octane.php` у `flush` (список звʼязок, які скидаються між запитами) і не забути `warm` для тих, що навпаки мають створюватись один раз. Той самий механізм працює в чергах: `Illuminate\Queue\Worker::resetScope()` викликає `forgetScopedInstances()` перед кожною задачею, тому `scoped` у `queue:work` - це «один на задачу», а `singleton` - «один на весь процес воркера».

Скаляр без значення за замовчуванням контейнер розвʼязати не може і кине `BindingResolutionException: Unresolvable dependency resolving [$dpi]`. Штатний спосіб - контекстна привʼязка за іменем змінної: `$this->app->when(PdfRenderer::class)->needs('$dpi')->give(150)` або `->giveConfig('pdf.dpi', 150)`, яке читає конфіг ліниво. Для інтерфейсу синтаксис той самий, але `needs()` приймає клас: `when([InvoiceExporter::class, ReportExporter::class])->needs(Filesystem::class)->give(fn () => Storage::disk('invoices'))`. Для наборів однотипних реалізацій є теги: `$this->app->tag([StripeGateway::class, PayPalGateway::class], 'gateways')` і потім `->needs(iterable::class)->giveTagged('gateways')` або `$this->app->tagged('gateways')`. Важлива механіка: при контекстному розвʼязанні контейнер пропускає кеш `$instances`, тобто `singleton`, у якого для цього споживача є контекстна привʼязка, буде створений окремо і в кеш не потрапить - інакше перший, хто його попросив, зафіксував би реалізацію для всіх. З Laravel 11 частину цього замінюють контекстні атрибути прямо в сигнатурі: `#[Config('pdf.dpi')] int $dpi`, `#[Storage('invoices')] Filesystem $disk`, `#[CurrentUser] User $user`, а в Laravel 12 зʼявились `#[Bind]`, `#[Singleton]` і `#[Scoped]` на самому інтерфейсі, що прибирає потребу в провайдері для простих випадків. Атрибути читабельніші, але прив’язують вибір реалізації до класу-споживача; коли потрібно підмінити все з одного місця (тест, інший тенант), провайдер лишається зручнішим.

оновлено 6 вересня 2026 · ліцензія CC-BY-SA-4.0 Знайшли неточність? Напишіть →