Service Container и Dependency Injection

Service Container (контейнер служб, иногда называемый IoC-контейнером — Inversion of Control) — объект-фабрика, отвечающий за создание других объектов в приложении. Когда коду нужен экземпляр класса с зависимостями, он не создаёт его напрямую через new, а просит контейнер: «дай мне экземпляр UserRepository». Контейнер сам разбирает, какие зависимости нужны конструктору этого класса, рекурсивно создаёт их, и возвращает готовый объект.

Это решает несколько задач одновременно. Во-первых, инверсия зависимостей: класс не знает, как создаётся Mailer, ему достаточно объявить, что в конструкторе нужен Mailer-интерфейс. Во-вторых, единое место регистрации: вся «сборка» приложения собирается в провайдерах, а не размазывается по сотням мест с new. В-третьих, заменяемость реализаций: в тесте можно сказать «когда просят Mailer, верни fake», и весь код будет работать с этим fake без модификаций.

В Laravel контейнер реализован классом Illuminate\Container\Container; Illuminate\Foundation\Application — его подкласс, добавляющий специфичные для Laravel возможности (события приложения, информацию об окружении, маршрутизацию). Глобальный экземпляр доступен через хелпер app(), через фасад App, через инъекцию интерфейса Illuminate\Contracts\Container\Container.

Сравним «ручную» сборку и сборку через контейнер на примере класса, шлющего уведомления.

Без контейнера: вызывающий код вынужден знать, как создать все зависимости.

class NotificationService
{
    public function __construct(
        private SmtpMailer $mailer,
        SmsGateway $sms,
        TemplateEngine $templates,
    ) {}
}

// Контроллер вынужден явно собирать графы зависимостей.
public function store(Request $request)
{
    $mailer    = new SmtpMailer(config('mail.host'), config('mail.port'));
    $sms       = new SmsGateway(config('sms.token'));
    $templates = new TemplateEngine(resource_path('templates'));

    $service = new NotificationService($mailer, $sms, $templates);
    $service->send(...);
}

С контейнером: контроллер объявляет, что ему нужно, и получает готовый сервис.

public function store(Request $request, NotificationService $service)
{
    $service->send(...);
    // Laravel сам создал SmtpMailer, SmsGateway, TemplateEngine
    // и собрал из них NotificationService.
}

Контейнер «знает», как создаются SmtpMailer, SmsGateway, TemplateEngine, потому что эти зависимости были зарегистрированы в сервис-провайдерах. Контроллер не несёт ответственности за их сборку.

Dependency Injection (внедрение зависимостей) — принцип проектирования, при котором класс получает свои зависимости извне, а не создаёт их самостоятельно. Класс становится независимым от способа создания зависимости: ему передают готовый объект через конструктор, метод или свойство.

DI — принцип, не привязанный к фреймворку и языку. Контейнер — реализация этого принципа: инструмент, автоматизирующий передачу зависимостей. Можно применять DI без контейнера (ручная передача в конструктор), но в проекте с сотнями классов это становится непрактичным; контейнер автоматизирует процесс.

Главная ценность DI — разрыв жёсткой связи между классами через интерфейсы. Класс OrderService зависит от интерфейса PaymentGateway, а не от конкретного StripeGateway. Конкретная реализация выбирается в одном месте (провайдере), и любая её замена не требует правки кода, использующего сервис.

DI (Dependency Injection) — это конкретный паттерн: способ предоставления объекту его зависимостей извне вместо создания их внутри через new.

DIP (Dependency Inversion Principle) — это принцип из SOLID: модули должны зависеть от абстракций (интерфейсов), а не от конкретных классов.

Три стадии на PHP (Laravel-стиль):

// Нарушены оба принципа: создание зависимости внутри
class OrderService
{
    public function process()
    {
        $gateway = new PayPalGateway();   // жёсткая привязка
        $gateway->charge();
    }
}

// DI есть, но DIP нарушен: внедряем конкретный класс
class OrderService
{
    public function __construct(private PayPalGateway $gateway) {}
    // Тесты уже возможны (можно подсунуть mock),
    // но контроллер знает про конкретный PayPal.
    // Смена на Stripe = правка type-hint во всех местах.
}

// DI + DIP соблюдены: внедряем абстракцию
interface PaymentGatewayInterface
{
    public function charge(): ChargeResult;
}

class PayPalGateway implements PaymentGatewayInterface { /* ... */ }
class StripeGateway implements PaymentGatewayInterface { /* ... */ }

class OrderService
{
    public function __construct(private PaymentGatewayInterface $gateway) {}
    // Класс не знает про PayPal / Stripe.
    // Замена реализации — 1 строчка в провайдере.
}

// В провайдере — выбор реализации в одном месте:
$this->app->bind(PaymentGatewayInterface::class, StripeGateway::class);

В Laravel контейнер помогает автоматически разрешать зависимости, но выбор абстракций (интерфейсов) остаётся за разработчиком — именно это и есть следование DIP. Контейнер не заставит вас использовать интерфейс — он лишь предоставляет удобный механизм биндинга, который вы можете использовать правильно (интерфейс → реализация) или неправильно (конкретный класс → сам себя).

Рассмотрим эволюцию класса от тесной связи с конкретной реализацией к гибкому DI через интерфейс. Видимое улучшение происходит в трёх измерениях: тестируемость, заменяемость, читаемость.

Этап 1: прямая зависимость от конкретного класса. Не тестируется без работающего внешнего API; смена провайдера требует переписывания.

class OrderController
{
    public function checkout(Request $request): Response
    {
        // Класс жёстко зависит от StripeGateway.
        $gateway = new StripeGateway(config('services.stripe.key'));
        $result = $gateway->charge($request->amount);
        // В тесте — реальные обращения к Stripe API.
    }
}

Этап 2: внедрение через конструктор. Зависимость явная, тесты могут подсунуть mock.

class OrderController
{
    public function __construct(private readonly StripeGateway $gateway) {}

    public function checkout(Request $request): Response
    {
        $result = $this->gateway->charge($request->amount);
    }
}

// В тесте
$mock = Mockery::mock(StripeGateway::class);
$mock->shouldReceive('charge')->andReturn(new ChargeResult(true));
app()->instance(StripeGateway::class, $mock);

Этап 3: зависимость от интерфейса. Контроллер вообще не знает, какой провайдер используется. Можно менять Stripe на PayPal через провайдер, без изменений в контроллере.

interface PaymentGateway
{
    public function charge(int $amountCents, string $currency): ChargeResult;
}

class StripeGateway implements PaymentGateway { /* ... */ }
class PaypalGateway implements PaymentGateway { /* ... */ }

// В провайдере
$this->app->bind(PaymentGateway::class, StripeGateway::class);
// или, в зависимости от конфигурации:
$this->app->bind(PaymentGateway::class, function () {
    return match (config('payment.driver')) {
        'stripe' => app(StripeGateway::class),
        'paypal' => app(PaypalGateway::class),
    };
});

class OrderController
{
    public function __construct(private readonly PaymentGateway $gateway) {}
    // Контроллер не знает, какой провайдер активен.
}

Регистрация связи между ключом и конкретной реализацией — основное действие, которое выполняется в сервис-провайдерах. От выбора метода регистрации зависит, как часто будет создаваться экземпляр, разделяется ли он между потребителями и каким образом конкретный класс получит свои зависимости.

Laravel предоставляет три базовых метода: bind() для transient-сервисов (каждое разрешение — новый экземпляр), singleton() для разделяемых сервисов (один экземпляр на весь запрос), instance() для регистрации уже созданного объекта. Выбор зависит от природы сервиса: stateless-сервис без побочных эффектов выгоднее singleton, stateful или дорогой в создании — transient.

Быстрая сводка перед детальным разбором:

bind vs singleton — принципиально:

• bind — контейнер хранит только алгоритм создания (замыкание/класс). Каждый make() запускает алгоритм заново.
• singleton — контейнер хранит и алгоритм, и готовый объект после первого разрешения. Второй make() вернёт кэшированный.

Классическая история — почему bind нужен и как всё связывается вместе. Пять файлов, каждый один-два экрана.

// 1. Интерфейс — контракт (app/Contracts/PaymentGateway.php)
interface PaymentGateway
{
    public function charge(User $user, float $amount): void;
}

// 2. Реализация (app/Services/StripePayment.php)
class StripePayment implements PaymentGateway
{
    public function charge(User $user, float $amount): void {
        // вызов Stripe API
    }
}

// 3. Привязка в AppServiceProvider::register()
public function register(): void
{
    $this->app->bind(PaymentGateway::class, StripePayment::class);
}

// 4. Action зависит от ИНТЕРФЕЙСА, а не от конкретной реализации
class PlaceOrder
{
    public function __construct(private PaymentGateway $payment) {}

    public function handle(User $user, array $items): Order { ... }
}

// 5. Контроллер — Laravel сам собирает PlaceOrder со всеми зависимостями
public function store(StoreOrderRequest $request, PlaceOrder $action)
{
    // $action уже готов, внутри — StripePayment (или что задано в bind)
    $order = $action->handle($request->user(), $request->validated()['items']);
}

Что получили:

• Смена шлюза = 1 строка. Завтра переходим на YooKassa — реализуем YooKassaPayment implements PaymentGateway, меняем bind(..., YooKassaPayment::class). Action не трогаем.
• Тесты без Stripe API. В тесте app()->bind(PaymentGateway::class, FakePayment::class) — Action получит fake.
• Никаких new. Action не знает, кто создаёт зависимости. Контейнер собирает всё сам через autowiring.

Контейнер Illuminate\Container\Container хранит три ключевых массива:

Упрощённая реализация bind():

public function bind($abstract, $concrete = null, $shared = false)
{
    $this->bindings[$abstract] = compact('concrete', 'shared');
}

// singleton — это просто bind с $shared = true
public function singleton($abstract, $concrete = null)
{
    $this->bind($abstract, $concrete, true);
}

Схема make():

1. Есть в $instances (уже разрешённый singleton)? → отдать его.
2. Есть в $contextual для текущего родителя? → взять оттуда.
3. Есть в $bindings? → выполнить concrete (замыкание или new-класс).
4. Ничего нет? → рефлексия: посмотреть конструктор класса, рекурсивно разрешить каждый параметр, вызвать new.
5. Если shared === true — сохранить результат в $instances.

Laravel умеет создавать любой конкретный класс без явной регистрации — через autowiring по type hints. bind() нужен когда:

Рассмотрим регистрацию типового набора сервисов магазина: репозитории (transient), кэш-менеджер (singleton), runtime-конфигурация (instance). Все регистрации выполняются в AppServiceProvider или специализированных провайдерах.

namespace App\Providers;

use App\Cache\StoreCacheManager;
use App\Contracts\Catalog\ProductRepository;
use App\Contracts\Pricing\PriceCalculator;
use App\Repositories\EloquentProductRepository;
use App\Services\Pricing\DefaultPriceCalculator;
use App\Services\Pricing\StoreFeatures;
use Illuminate\Contracts\Container\Container;
use Illuminate\Support\ServiceProvider;

class CatalogServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // 1. Репозиторий — transient. Каждый запрос строит свой query builder.
        $this->app->bind(ProductRepository::class, EloquentProductRepository::class);

        // 2. Кэш-менеджер — singleton. Дорогое соединение к Redis
        //    переиспользуется в течение запроса.
        $this->app->singleton(StoreCacheManager::class, function (Container $app) {
            return new StoreCacheManager(
                redis: $app->make('redis.connection'),
                prefix: config('cache.prefix'),
                defaultTtl: 3600,
            );
        });

        // 3. Калькулятор цен — singleton, потому что использует кэш и не имеет состояния.
        $this->app->singleton(PriceCalculator::class, DefaultPriceCalculator::class);

        // 4. Runtime-конфигурация фич — instance, потому что объект собирается
        //    из конфига при boot приложения.
        $features = new StoreFeatures(config('store.features', []));
        $this->app->instance(StoreFeatures::class, $features);
    }
}

Использование в коде:

class ProductController
{
    // Все четыре зависимости автоматически разрешатся контейнером.
    public function __construct(
        private readonly ProductRepository $repository,
        private readonly StoreCacheManager $cache,
        private readonly PriceCalculator $pricing,
        private readonly StoreFeatures $features,
    ) {}

    public function show(int $id): View
    {
        $product = $this->cache->remember("product.{$id}",
            fn () => $this->repository->findOrFail($id));

        return view('product.show', [
            'product'     => $product,
            'final_price' => $this->pricing->calculate($product),
            'show_promo'  => $this->features->enabled('promo-banner'),
        ]);
    }
}

Scoped binding — промежуточный по поведению режим между bind и singleton. Сервис создаётся один раз в рамках определённого «жизненного цикла» и сбрасывается при его завершении. В Laravel scoped введён ради совместимости с Octane и подобными окружениями, где приложение живёт между запросами и singleton может «протечь» из одного запроса в другой.

В классическом PHP-FPM (запрос — отдельный процесс) разницы между singleton и scoped нет: оба переживают весь запрос и уничтожаются вместе с процессом. В Octane разница принципиальна: singleton сохраняется на всё время жизни worker-процесса (минуты, часы), scoped — только на длительность одного HTTP-запроса. Контейнер автоматически вызывает forgetScopedInstances() между запросами.

Тот же механизм применяется в long-running сценариях вне HTTP: очереди (job — «область»), Artisan-команды с большим обходом данных, тесты с RefreshDatabase. Везде, где сервис должен быть «свежим» для каждой логической операции, но при этом разделяться между шагами этой операции, применяется scoped.

Рассмотрим SaaS-приложение в Octane, где для каждого HTTP-запроса нужен свежий объект TenantContext с идентификатором арендатора, текущим пользователем и trace-id для логирования. В обычных условиях этот объект использовался бы как singleton, но в Octane между запросами разных тенантов состояние утекало бы. scoped решает проблему.

namespace App\Tenancy;

final class TenantContext
{
    public function __construct(
        public readonly int $tenantId,
        public readonly ?int $userId,
        public readonly string $traceId,
        public readonly Carbon $startedAt,
    ) {}
}

// app/Providers/TenancyServiceProvider.php
use Illuminate\Support\ServiceProvider;

class TenancyServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->scoped(TenantContext::class, function (Container $app) {
            $resolver = $app->make(TenantResolver::class);

            return new TenantContext(
                tenantId: $resolver->currentTenantId() ?? throw new RuntimeException('Tenant not resolved'),
                userId:   auth()->id(),
                traceId:  (string) Str::uuid(),
                startedAt: now(),
            );
        });
    }
}

// Использование в коде
class AuditLogger
{
    public function __construct(private readonly TenantContext $context) {}

    public function record(string $action, array $payload = []): void
    {
        AuditEntry::create([
            'tenant_id' => $this->context->tenantId,
            'user_id'   => $this->context->userId,
            'trace_id'  => $this->context->traceId,
            'action'    => $action,
            'payload'   => $payload,
        ]);
    }
}

Поведение в трёх окружениях:

• PHP-FPM: процесс создаётся под запрос и уничтожается после ответа. Singleton и scoped работают одинаково.
• Octane: worker-процесс живёт долго. На каждый HTTP-запрос Octane вызывает app()->forgetScopedInstances(); TenantContext пересоздаётся с актуальным тенантом. Singleton сохранил бы первый созданный контекст и применял его ко всем последующим тенантам.
• Queue worker: длительный процесс, обрабатывающий jobs последовательно. Laravel сбрасывает scoped перед обработкой каждого job, поэтому job получает свой контекст.

Contextual binding (контекстное связывание) позволяет регистрировать разные реализации одного интерфейса для разных потребителей. Если двум классам нужен один и тот же интерфейс Filesystem, но первому — локальный диск, а второму — S3, контекстный binding это решает декларативно, без нагромождения условий внутри классов.

Без контекстного binding пришлось бы либо передавать конкретную реализацию вручную в каждый класс (нарушая DI), либо помещать логику выбора реализации внутрь самих классов через config('app.driver') или Service Locator. Контекстный binding выносит решение «какая реализация для какого класса» в провайдер, где оно концентрируется в одном месте.

Метод сложнее bind/singleton по синтаксису, но даёт мощную гибкость для архитектурных задач: разделение драйверов между разными частями приложения, разные конфигурации для контекстов «писатель/читатель», подмена реализаций в специальных контроллерах (например, admin-панели с расширенными правами).

В медиа-приложении одно и то же приложение работает с несколькими хранилищами: фото — в S3 bucket media-photos, видео — в media-videos (часто другой регион из-за объёмов), временные файлы — в локальной директории, экспортированные отчёты — в защищённом S3 bucket. Контроллеры и сервисы каждой подсистемы объявляют в конструкторе Filesystem, но получают разные реализации.

namespace App\Providers;

use App\Console\Commands\GenerateReports;
use App\Http\Controllers\PhotoController;
use App\Http\Controllers\VideoController;
use App\Jobs\ProcessImportFile;
use Illuminate\Contracts\Filesystem\Filesystem;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\ServiceProvider;

class StorageBindingsProvider extends ServiceProvider
{
    public function register(): void
    {
        // Фото-модуль: чтение и запись через PhotoController, PhotoUploadJob.
        $this->app->when([PhotoController::class, PhotoUploadJob::class])
            ->needs(Filesystem::class)
            ->give(fn () => Storage::disk('media-photos'));

        // Видео-модуль: отдельный bucket в другом регионе.
        $this->app->when(VideoController::class)
            ->needs(Filesystem::class)
            ->give(fn () => Storage::disk('media-videos'));

        // Импорт-задачи работают с локальной временной директорией.
        $this->app->when(ProcessImportFile::class)
            ->needs(Filesystem::class)
            ->give(fn () => Storage::disk('imports'));

        // Отчёты: защищённое хранилище с приватными ссылками.
        $this->app->when(GenerateReports::class)
            ->needs(Filesystem::class)
            ->give(fn () => Storage::disk('reports-private'));

        // Default для всех остальных потребителей — публичный диск.
        $this->app->bind(Filesystem::class, fn () => Storage::disk('public'));
    }
}

Каждый из контроллеров и job'ов в коде выглядит одинаково — они не знают о том, какой диск получают:

class PhotoController
{
    public function __construct(private readonly Filesystem $files) {}

    public function store(UploadedFile $file): JsonResponse
    {
        $path = $this->files->putFile('uploads', $file);
        // $this->files — это диск 'media-photos', хотя контроллер этого не знает.
    }
}

class VideoController
{
    public function __construct(private readonly Filesystem $files) {}
    // Тот же тип зависимости, но получит другой диск.
}

Достигнутые преимущества:

• Контроллеры остаются простыми и тестируемыми — в тесте подменяется только bind на in-memory диск.
• Изменение хранилища (например, перенос фото с S3 на CloudFront) затрагивает один провайдер, не контроллеры.
• Можно динамически менять биндинг для конкретного контекста в feature-flag сценариях.

Tagged services — механизм группировки нескольких сервисов под общим логическим тегом для последующего получения всей группы одним вызовом. Применяется, когда приложение содержит несколько однотипных компонентов, образующих коллекцию: набор валидаторов, цепочка обработчиков команд (chain of responsibility), плагины, генераторы отчётов, экспортёры различных форматов.

Без тегов получение всех реализаций интерфейса требовало бы поддержки явного списка в коде или конфиге. Например, для обработки команды чата нужно знать все доступные команды; для генерации Excel-отчёта — все экспортёры. Тегирование позволяет регистрировать новые компоненты декларативно: добавил класс, отметил тегом, и существующая логика автоматически его подхватит.

Тег — обычная строка-идентификатор. Контейнер хранит список abstracts, помеченных конкретным тегом. При запросе tagged($tag) возвращается ленивый итератор, разрешающий каждый abstract в полноценный сервис.

Приложение должно уметь экспортировать отчёт в несколько форматов: CSV, XLSX, JSON, PDF. Каждый формат реализован отдельным классом. Список форматов меняется со временем: добавляются новые, удаляются устаревшие. Главное требование — чтобы добавление нового формата не требовало правок в существующем коде, выбирающем формат.

namespace App\Reporting\Exporters;

interface ReportExporter
{
    public function format(): string;
    public function label(): string;
    public function export(Report $report): StreamedResponse;
}

class CsvExporter implements ReportExporter
{
    public function format(): string  { return 'csv'; }
    public function label(): string   { return 'CSV (Excel)'; }
    public function export(Report $report): StreamedResponse  { /* ... */ }
}

class XlsxExporter implements ReportExporter
{
    public function __construct(private readonly SpreadsheetEngine $engine) {}
    public function format(): string  { return 'xlsx'; }
    public function label(): string   { return 'Excel 2016+'; }
    public function export(Report $report): StreamedResponse  { /* ... */ }
}

// Аналогично JsonExporter, PdfExporter.

Регистрация и тегирование в провайдере:

class ReportingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Регистрируем каждый экспортёр как singleton (stateless по природе).
        $this->app->singleton(CsvExporter::class);
        $this->app->singleton(XlsxExporter::class);
        $this->app->singleton(JsonExporter::class);
        $this->app->singleton(PdfExporter::class);

        // Помечаем общим тегом для последующей итерации.
        $this->app->tag(
            [
                CsvExporter::class,
                XlsxExporter::class,
                JsonExporter::class,
                PdfExporter::class,
            ],
            'report-exporters'
        );

        // Менеджер экспорта получает всю группу через giveTagged.
        $this->app->when(ReportExportManager::class)
            ->needs('$exporters')
            ->giveTagged('report-exporters');
    }
}

Менеджер экспорта, использующий tagged-группу:

class ReportExportManager
{
    // Индексированный по формату массив экспортёров.
    private readonly array $byFormat;

    public function __construct(iterable $exporters)
    {
        $this->byFormat = collect($exporters)
            ->keyBy(fn (ReportExporter $e) => $e->format())
            ->all();
    }

    public function available(): array
    {
        return collect($this->byFormat)
            ->map(fn (ReportExporter $e) => $e->label())
            ->all();
        // → ['csv' => 'CSV (Excel)', 'xlsx' => 'Excel 2016+', 'json' => 'JSON', 'pdf' => 'PDF']
    }

    public function export(Report $report, string $format): StreamedResponse
    {
        if (! isset($this->byFormat[$format])) {
            throw new UnsupportedFormatException($format);
        }
        return $this->byFormat[$format]->export($report);
    }
}

Использование в контроллере:

class ReportController
{
    public function __construct(private readonly ReportExportManager $exporter) {}

    public function download(Report $report, Request $request): StreamedResponse
    {
        return $this->exporter->export($report, $request->input('format', 'csv'));
    }
}

Добавление нового формата (например, XML) сводится к: написать класс XmlExporter implements ReportExporter, зарегистрировать его в провайдере, дописать в массив tag(). Менеджер, контроллер, шаблон выбора формата — ничего из этого менять не нужно.

Resolution — процесс, в котором контейнер по запрошенному abstract создаёт готовый объект со всеми зависимостями. Autowiring — автоматическое разрешение зависимостей без явной регистрации, на основе анализа типов в сигнатуре конструктора. Эти два механизма работают вместе и определяют, насколько «легко» в коде получить сервис.

Понимание процесса разрешения важно, когда необходимо вызвать произвольный метод с инъекцией зависимостей (app()->call()), подмешать значения в существующий объект (resolving-колбэки), отладить почему контейнер выбрасывает BindingResolutionException. Большую часть времени разработчик не задумывается о деталях разрешения — всё работает «магически», но понимание превращает магию в инженерную предсказуемость.

Алгоритм разрешения детерминирован и пошаговый: проверка кеша инстансов, поиск registered binding, попытка autowiring через рефлексию, рекурсия по параметрам конструктора, применение контекстных biding, primitive resolution через дефолтные значения. Каждый шаг имеет осмысленную точку расширения для опытного пользователя.

Рассмотрим, как контейнер разрешает сложный граф зависимостей, и как влияют разные виды биндингов.

interface PaymentGateway { public function charge(int $cents): ChargeResult; }

class StripeGateway implements PaymentGateway
{
    public function __construct(
        private readonly HttpClient $http,        // типизированная — autowire
        private readonly string $apiKey,            // primitive — контекстный bind
        private readonly int $timeoutSec = 30,      // primitive с default
    ) {}
}

class CheckoutService
{
    public function __construct(
        private readonly PaymentGateway $gateway,
        private readonly OrderRepository $orders,
        private readonly EventDispatcher $events,
    ) {}
}

// Регистрация в провайдере:
app()->bind(PaymentGateway::class, StripeGateway::class);
app()->when(StripeGateway::class)
    ->needs('$apiKey')
    ->giveConfig('services.stripe.key');
app()->singleton(HttpClient::class);

Что происходит при app(CheckoutService::class):

1. Контейнер: запрошен CheckoutService. Binding не найден, но это конкретный класс — autowire через рефлексию.
2. Параметр $gateway: PaymentGateway. Это интерфейс. Найден binding PaymentGateway → StripeGateway. Рекурсивный make(StripeGateway::class).
3. Контейнер разрешает StripeGateway:
   • $http: HttpClient — найден singleton-binding, инстанцируется (или возвращается из кеша). Autowire его конструктора.
   • $apiKey: string — primitive. Найден контекстный binding с giveConfig('services.stripe.key'). Получаем значение из конфига.
   • $timeoutSec: int = 30 — primitive без binding, используется default 30.
4. Возврат к CheckoutService. Параметр $orders: OrderRepository — autowire (без явного binding).
5. Параметр $events: EventDispatcher — разрешён из встроенных биндингов фреймворка (Laravel регистрирует его в EventServiceProvider).
6. Конструктор CheckoutService вызывается со всеми тремя зависимостями. Объект готов.

Эту цепочку можно отладить, зарегистрировав глобальный resolving-колбэк:

app()->resolving(function ($object, Container $app) {
    logger()->debug('Resolved: ' . $object::class);
});

app(CheckoutService::class);
// В логе: Resolved: HttpClient, StripeGateway, OrderRepository, EventDispatcher, CheckoutService

Контейнер публикует события на ключевых моментах своей работы: разрешение зависимости (resolving, afterResolving) и перепривязка ранее зарегистрированного binding (rebinding). Эти точки расширения позволяют выполнить дополнительные действия над созданным объектом или отреагировать на смену реализации в runtime.

События контейнера — не то же самое, что Application events Laravel (UserCreated, OrderPlaced). Контейнерные события низкого уровня, относятся к самому процессу создания сервисов и регистрируются методами на контейнере, а не через систему Event/Listener.

Главные практические применения: централизованная настройка одного типа сервисов (например, добавить trace-id во все логгеры, навесить middleware на все HTTP-клиенты), отслеживание перерегистрации binding для каскадного обновления зависимых сервисов, аудит создаваемых объектов в dev-окружении.

Приложение использует HTTP-клиент для интеграций с тремя внешними API (Stripe, Twilio, Slack). Каждый клиент должен иметь общие настройки: retry с экспоненциальным бэкоффом, логирование запросов, trace-id в заголовках, метрики времени ответа. Без событий контейнера эту настройку пришлось бы дублировать в каждой регистрации; через resolving — в одном месте.

namespace App\Providers;

use App\Http\Middleware\Client\LoggingMiddleware;
use App\Http\Middleware\Client\MetricsMiddleware;
use App\Http\Middleware\Client\RetryMiddleware;
use App\Http\Middleware\Client\TraceMiddleware;
use GuzzleHttp\Client as HttpClient;
use Illuminate\Support\ServiceProvider;

class HttpClientServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Базовые конструкторы клиентов — без middleware.
        $this->app->singleton('http.stripe', fn () => new HttpClient(['base_uri' => 'https://api.stripe.com']));
        $this->app->singleton('http.twilio', fn () => new HttpClient(['base_uri' => 'https://api.twilio.com']));
        $this->app->singleton('http.slack', fn () => new HttpClient(['base_uri' => 'https://slack.com']));

        // Единая настройка через resolving — применится к каждому из трёх клиентов.
        foreach (['http.stripe', 'http.twilio', 'http.slack'] as $key) {
            $this->app->resolving($key, function (HttpClient $client, Container $app) {
                $stack = $client->getConfig('handler');

                $stack->push(new RetryMiddleware(maxAttempts: 3, backoffMs: 200));
                $stack->push(new TraceMiddleware($app->make(RequestContext::class)));
                $stack->push(new LoggingMiddleware($app->make(Logger::class)));
                $stack->push(new MetricsMiddleware($app->make(MetricsCollector::class)));
            });
        }
    }
}

Преимущества подхода: один источник истины для настройки HTTP-клиентов. Добавление нового middleware (например, circuit breaker) — одна строка в провайдере, применится ко всем клиентам автоматически. Добавление нового HTTP-клиента — одна регистрация плюс ключ в массиве, и все middleware подхватятся.

Альтернатива через extend — ещё более лаконичная, но создаёт цепочку декораторов вместо модификации существующего объекта:

foreach (['http.stripe', 'http.twilio', 'http.slack'] as $key) {
    $this->app->extend($key, function (HttpClient $client, Container $app) {
        return new DecoratedHttpClient($client, [
            new RetryDecorator(3),
            new TraceDecorator($app->make(RequestContext::class)),
            new LoggingDecorator($app->make(Logger::class)),
        ]);
    });
}

Service Provider — точка инициализации модуля приложения. Это класс, наследующий Illuminate\Support\ServiceProvider, в котором приложение или сторонний пакет сообщает фреймворку: «вот мои сервисы, маршруты, миграции, конфиг, observers». Провайдер выполняет роль композиционного корня (composition root) для своей подсистемы.

Laravel сам — набор провайдеров. Подключение к БД, событийная система, маршрутизация, авторизация, очереди, кэш — каждый из этих модулей фреймворка зарегистрирован отдельным провайдером в vendor/laravel/framework/src/Illuminate/.../<*ServiceProvider.php>. Этот же механизм доступен приложениям и пакетам.

Провайдеры решают две задачи. Первая — регистрация связок в контейнере (bind, singleton, контекстные binding) до того, как фреймворк начнёт обрабатывать запросы. Вторая — «boot»-инициализация: загрузка миграций, регистрация Blade-директив, объявление маршрутов, подписка на события — всё, что требует уже собранного контейнера.

Рассмотрим организацию крупного приложения как набора независимых модулей: Catalog, Orders, Billing, Notifications. Каждый модуль — набор сервисов, моделей, маршрутов, миграций, замкнутых на своей предметной области. Каждый модуль имеет один Service Provider, отвечающий за его инициализацию.

namespace App\Modules\Catalog\Providers;

use App\Modules\Catalog\Contracts\ProductRepository;
use App\Modules\Catalog\Repositories\EloquentProductRepository;
use App\Modules\Catalog\Services\PriceCalculator;
use App\Modules\Catalog\Observers\ProductObserver;
use App\Modules\Catalog\Models\Product;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\ServiceProvider;

class CatalogServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Слияние конфига модуля с пользовательской настройкой.
        $this->mergeConfigFrom(
            __DIR__ . '/../config/catalog.php', 'catalog'
        );

        // Регистрация контрактов и реализаций.
        $this->app->bind(ProductRepository::class, EloquentProductRepository::class);
        $this->app->singleton(PriceCalculator::class);
    }

    public function boot(): void
    {
        // Маршруты модуля.
        Route::middleware('web')
            ->prefix('catalog')
            ->group(__DIR__ . '/../routes/web.php');

        // Миграции и шаблоны.
        $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
        $this->loadViewsFrom(__DIR__ . '/../resources/views', 'catalog');

        // Observer для модели.
        Product::observe(ProductObserver::class);

        // Publishable: конфиг можно скопировать в config/ командой vendor:publish.
        $this->publishes([
            __DIR__ . '/../config/catalog.php' => config_path('catalog.php'),
        ], 'catalog-config');
    }
}

Структура файлов модуля:

Подключение модуля сводится к одной строке в bootstrap/providers.php:

return [
    App\Providers\AppServiceProvider::class,
    App\Modules\Catalog\Providers\CatalogServiceProvider::class,
    App\Modules\Orders\Providers\OrdersServiceProvider::class,
    App\Modules\Billing\Providers\BillingServiceProvider::class,
    App\Modules\Notifications\Providers\NotificationsServiceProvider::class,
];

Преимущества такой структуры:

• Каждый модуль автономен: его можно отключить (закомментировав провайдер) или перенести в отдельный пакет;
• Зависимости между модулями явные — через интерфейсы и контейнер, без прямых импортов классов другого модуля;
• Тестирование модуля отдельно от остальной системы упрощается;
• В крупных командах разные модули можно развивать параллельно без конфликтов в namespace.

Жизненный цикл загрузки приложения Laravel состоит из двух фаз: фаза регистрации и фаза boot. Каждый ServiceProvider может участвовать в обеих фазах, реализуя методы register() и boot(). Понимание разделения между ними критично: размещение кода в неправильной фазе приводит к ошибкам, неочевидным для начинающих, но прозрачным после знакомства с алгоритмом.

Принцип разделения: в фазе регистрации нельзя предполагать, что другие сервисы уже доступны — они могут быть зарегистрированы более поздними провайдерами. В фазе boot контейнер полностью собран — можно использовать любой сервис, регистрировать обработчики событий, маршруты, наблюдателей моделей.

Метод booted() — третья опция, выполняющаяся после всех boot() всех провайдеров. Используется для финальных инициализаций, требующих полной готовности приложения.

Рассмотрим провайдер модуля Notifications с разными типами инициализации, и покажем, какой код в какой фазе должен находиться.

namespace App\Modules\Notifications\Providers;

use App\Modules\Notifications\Channels\PushChannel;
use App\Modules\Notifications\Channels\SlackChannel;
use App\Modules\Notifications\Channels\SmsChannel;
use App\Modules\Notifications\Contracts\NotificationChannel;
use App\Modules\Notifications\Listeners\BroadcastUserEvent;
use App\Modules\Notifications\Models\NotificationLog;
use App\Modules\Notifications\Observers\NotificationLogObserver;
use App\Modules\Notifications\Routes;
use Illuminate\Contracts\Events\Dispatcher;
use Illuminate\Support\Facades\Blade;
use Illuminate\Support\Facades\Route;
use Illuminate\Support\ServiceProvider;

class NotificationsServiceProvider extends ServiceProvider
{
    // Простые ассоциации.
    public array $singletons = [
        PushChannel::class  => PushChannel::class,
        SlackChannel::class => SlackChannel::class,
        SmsChannel::class   => SmsChannel::class,
    ];

    public function register(): void
    {
        // Контекстный binding — выполняется при разрешении.
        $this->app->when([SmsChannel::class])
            ->needs('$apiKey')
            ->giveConfig('notifications.sms.api_key');

        // Слияние дефолтной конфигурации.
        $this->mergeConfigFrom(__DIR__ . '/../config/notifications.php', 'notifications');

        // Tagging — пометки в контейнере, не вызов сервисов.
        $this->app->tag([
            PushChannel::class,
            SlackChannel::class,
            SmsChannel::class,
        ], 'notification-channels');
    }

    public function boot(Dispatcher $events): void
    {
        // Маршруты — фасад Route доступен.
        Route::middleware('web')
            ->prefix('notifications')
            ->group(__DIR__ . '/../routes/web.php');

        // Миграции и шаблоны.
        $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');
        $this->loadViewsFrom(__DIR__ . '/../resources/views', 'notifications');

        // Observers — модель уже загружена и Eloquent готов.
        NotificationLog::observe(NotificationLogObserver::class);

        // Event listeners через method-injected dispatcher.
        $events->listen(
            \App\Events\UserRegistered::class,
            BroadcastUserEvent::class,
        );

        // Blade-директива.
        Blade::directive('notify', fn ($expr) =>
            "<?php echo notify($expr); ?>");

        // Финальная инициализация, когда все провайдеры загружены.
        $this->app->booted(function () {
            // Здесь гарантированно все сервисы готовы.
            \Illuminate\Notifications\ChannelManager::macro('allOf', function (array $channels) {
                // macro для удобного API.
            });
        });
    }
}

Сводно: register — декларация (что есть в контейнере); boot — реализация (что приложение делает при старте); booted — финальные коррекции, требующие готовности всех модулей.

Deferred Provider — провайдер, регистрация которого откладывается до момента, когда впервые понадобится один из зарегистрированных им сервисов. Это оптимизация холодного старта: вместо того чтобы инициализировать все модули на каждом запросе, фреймворк загружает только тот, чьи сервисы реально были запрошены.

Применяется для тяжёлых пакетов, используемых эпизодически: PDF-генератор, аналитический пайплайн, интеграция с внешним API, импорт/экспорт. На веб-запросах, где эти сервисы не нужны, провайдер вообще не выполняется — экономится время и ресурсы.

В обмен на оптимизацию deferred-провайдер обязан декларативно объявить, какие abstracts он будет регистрировать. Laravel хранит этот список в кеше (bootstrap/cache/services.php) и при запросе одного из этих abstracts знает, какой провайдер нужно загрузить.

Веб-приложение использует PDF-генерацию только в одной фиче (формирование счёт-фактур) и в одной Artisan-команде (массовая отправка отчётов). На остальных запросах эта подсистема не нужна. Делаем её deferred.

namespace App\Providers;

use App\Pdf\PdfEngine;
use App\Pdf\Compilers\BladePdfCompiler;
use App\Pdf\Renderers\DompdfRenderer;
use App\Pdf\Storage\PdfStorage;
use Illuminate\Contracts\Container\Container;
use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;

class PdfServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        // Компилятор Blade-шаблонов в HTML.
        $this->app->singleton(BladePdfCompiler::class);

        // Renderer на базе Dompdf — тяжёлая инициализация.
        $this->app->singleton(DompdfRenderer::class, function (Container $app) {
            $config = config('pdf');
            return new DompdfRenderer(
                paperSize: $config['paper_size'] ?? 'A4',
                fontPath:  $config['font_path'],
                enableRemote: $config['enable_remote'] ?? false,
            );
        });

        // Хранилище сгенерированных PDF.
        $this->app->singleton(PdfStorage::class, function (Container $app) {
            return new PdfStorage(
                disk: app('filesystem')->disk('pdf'),
                retention: config('pdf.retention_days', 30),
            );
        });

        // Высокоуровневый сервис, объединяющий всё.
        $this->app->singleton(PdfEngine::class);
    }

    public function provides(): array
    {
        return [
            BladePdfCompiler::class,
            DompdfRenderer::class,
            PdfStorage::class,
            PdfEngine::class,
        ];
    }
}

Использование — обычное. Контроллер счёта-фактуры объявляет в конструкторе PdfEngine, и фреймворк прозрачно загружает PdfServiceProvider при первом запросе:

class InvoiceController
{
    public function __construct(private readonly PdfEngine $pdf) {}
    // При первом обращении к /invoices/{id}/download:
    // 1. Laravel ищет PdfEngine в кеше services.php → находит PdfServiceProvider.
    // 2. Вызывает PdfServiceProvider::register().
    // 3. Разрешает все зависимости PdfEngine рекурсивно.
    // 4. Передаёт готовый engine в конструктор контроллера.

    public function download(Invoice $invoice): StreamedResponse
    {
        return $this->pdf->render('invoices.print', ['invoice' => $invoice]);
    }
}

На всех остальных запросах PdfServiceProvider не выполняется. На страницах списка товаров, поиска, корзины — нет инициализации Dompdf, не загружается несколько мегабайт классов, не создаётся временная директория. Это становится особенно заметным с десятком тяжёлых модулей в одном приложении.

Package Provider — ServiceProvider, поставляемый в составе Composer-пакета. По функциональности не отличается от приложенческого провайдера, но имеет ряд дополнительных задач: автоматическая регистрация через mechanism Laravel auto-discovery, публикация ресурсов (конфиги, миграции, assets, views) в приложение пользователя пакета, слияние дефолтной конфигурации с пользовательской переопределённой.

Package Providers — основной механизм расширения Laravel: spatie-пакеты, Nova, Sanctum, Telescope, Pulse — всё это пакеты со своими провайдерами. Понимание устройства таких провайдеров критично для двух задач: использования сторонних пакетов с осознанным выбором (включить только нужное, не зарегистрировать всё подряд) и написания собственных пакетов под нужды команды.

Provider пакета должен быть «вежливым»: не перетирать пользовательские настройки, давать возможность точечной публикации только нужных частей, поддерживать config:cache в production, не делать heavy work на каждом запросе. Эти ожидания формируют конкретные паттерны кода в register() и boot().

Рассмотрим небольшой пакет acme/audit-log — журналирование операций с прокрутки моделей. Он содержит: одну модель AuditEntry, миграцию, фасад Audit, конфиг с настройкой подключения и retention-политикой, две Artisan-команды для очистки.

// composer.json пакета
{
    "name": "acme/audit-log",
    "description": "Domain-agnostic audit logging for Laravel",
    "autoload": { "psr-4": { "Acme\\AuditLog\\\\": "src/" } },
    "extra": {
        "laravel": {
            "providers": ["Acme\\AuditLog\\AuditLogServiceProvider"],
            "aliases":  { "Audit": "Acme\\AuditLog\\Facades\\Audit" }
        }
    }
}

// src/AuditLogServiceProvider.php
namespace Acme\AuditLog;

use Acme\AuditLog\Console\PruneAuditCommand;
use Acme\AuditLog\Console\ExportAuditCommand;
use Acme\AuditLog\Contracts\AuditRecorder;
use Acme\AuditLog\Services\DatabaseAuditRecorder;
use Illuminate\Contracts\Container\Container;
use Illuminate\Support\ServiceProvider;

class AuditLogServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // 1. Сливаем дефолтный конфиг пакета.
        $this->mergeConfigFrom(
            __DIR__ . '/../config/audit.php', 'audit'
        );

        // 2. Связываем контракт с реализацией. Singleton — recorder stateless.
        $this->app->singleton(AuditRecorder::class, function (Container $app) {
            return new DatabaseAuditRecorder(
                connection: config('audit.connection') ?? config('database.default'),
                table:      config('audit.table', 'audit_entries'),
            );
        });

        // 3. Регистрируем alias для удобства: app('audit').
        $this->app->alias(AuditRecorder::class, 'audit');
    }

    public function boot(): void
    {
        // 4. Объявляем публикуемые ресурсы с раздельными тегами.
        $this->publishes([
            __DIR__ . '/../config/audit.php' => config_path('audit.php'),
        ], 'audit-config');

        $this->publishes([
            __DIR__ . '/../database/migrations' => database_path('migrations'),
        ], 'audit-migrations');

        // 5. Загружаем миграции «из пакета» — обновляются с пакетом.
        // (Альтернатива: пусть пользователь публикует и контролирует сам.)
        $this->loadMigrationsFrom(__DIR__ . '/../database/migrations');

        // 6. Регистрируем Artisan-команды только в CLI-окружении.
        if ($this->app->runningInConsole()) {
            $this->commands([
                PruneAuditCommand::class,
                ExportAuditCommand::class,
            ]);
        }
    }
}

Использование на стороне пользователя:

# Установка
composer require acme/audit-log

# Опционально: опубликовать конфиг для кастомизации.
php artisan vendor:publish --tag=audit-config

# Миграции уже автоматически подхватятся следующим artisan migrate.
php artisan migrate

// В коде пользователя
use Acme\AuditLog\Contracts\AuditRecorder;

class OrderController
{
    public function __construct(private readonly AuditRecorder $audit) {}

    public function cancel(Order $order): Response
    {
        $order->cancel();

        $this->audit->record('order.cancelled', [
            'order_id' => $order->id,
            'reason'   => request('reason'),
        ]);

        return response(...);
    }
}

// Или через фасад:
Audit::record('order.cancelled', [...]);

Достоинства пакетной структуры: возможность переиспользования между проектами без копипасты, версионирование через Composer, понятная история обновлений, явные публичные контракты в виде интерфейсов.

Задача — собрать модуль Billing, демонстрирующий все рассмотренные техники контейнера в одном сценарии. Требования к модулю:

• контракт PaymentGateway с двумя реализациями: StripeGateway (продакшен) и FakeGateway (тесты, локальная разработка);
• сервис SubscriptionService работает только со Stripe (фиксированно по бизнес-требованию);
• сервис CheckoutService выбирает реализацию по конфигурации мерчанта (контекстуально на уровне арендатора);
• набор правил риска (RiskRule) подключается через теги — их количество растёт независимо от ядра;
• в рамках одного HTTP-запроса используется общий BillingContext (идемпотентность операций) — scoped биндинг;
• провайдер модуля — deferred, потому что биллинг затрагивает только маршруты checkout/subscription;
• модуль оформлен как отдельный пакет acme/billing с auto-discovery, публикацией конфигурации и миграциями.

packages/acme/billing/
├── composer.json
├── config/
│   └── billing.php
├── database/
│   └── migrations/
│       └── 2026_05_22_000001_create_billing_charges_table.php
├── routes/
│   └── web.php
├── src/
│   ├── Contracts/
│   │   └── PaymentGateway.php
│   ├── Gateways/
│   │   ├── StripeGateway.php
│   │   └── FakeGateway.php
│   ├── Risk/
│   │   ├── RiskRule.php
│   │   ├── VelocityRule.php
│   │   ├── GeoMismatchRule.php
│   │   ├── BlocklistRule.php
│   │   └── RiskEngine.php
│   ├── Services/
│   │   ├── BillingContext.php
│   │   ├── CheckoutService.php
│   │   └── SubscriptionService.php
│   └── Providers/
│       └── BillingServiceProvider.php
└── tests/
    └── ...

// packages/acme/billing/src/Contracts/PaymentGateway.php
namespace Acme\Billing\Contracts;

interface PaymentGateway
{
    public function charge(int $amountMinor, string $currency, string $idempotencyKey): string;
    public function refund(string $chargeId, ?int $amountMinor = null): void;
}

// packages/acme/billing/src/Gateways/StripeGateway.php
namespace Acme\Billing\Gateways;

use Acme\Billing\Contracts\PaymentGateway;
use Stripe\StripeClient;

final class StripeGateway implements PaymentGateway
{
    public function __construct(private StripeClient $stripe) {}

    public function charge(int $amountMinor, string $currency, string $idempotencyKey): string
    {
        $intent = $this->stripe->paymentIntents->create(
            ['amount' => $amountMinor, 'currency' => $currency],
            ['idempotency_key' => $idempotencyKey],
        );

        return $intent->id;
    }

    public function refund(string $chargeId, ?int $amountMinor = null): void
    {
        $this->stripe->refunds->create(['payment_intent' => $chargeId, 'amount' => $amountMinor]);
    }
}

// packages/acme/billing/src/Gateways/FakeGateway.php — детерминированная реализация для тестов
namespace Acme\Billing\Gateways;

use Acme\Billing\Contracts\PaymentGateway;

final class FakeGateway implements PaymentGateway
{
    public array $calls = [];

    public function charge(int $amountMinor, string $currency, string $idempotencyKey): string
    {
        $this->calls[] = compact('amountMinor', 'currency', 'idempotencyKey');
        return 'fake_' . substr(sha1($idempotencyKey), 0, 12);
    }

    public function refund(string $chargeId, ?int $amountMinor = null): void {}
}

Каждое правило риска реализует общий контракт. Новое правило добавляется без правок ядра — провайдер тегирует его, а RiskEngine получает все теги одной выборкой.

// packages/acme/billing/src/Risk/RiskRule.php
namespace Acme\Billing\Risk;

interface RiskRule
{
    public function code(): string;
    public function evaluate(array $payload): int; // 0..100 — вклад в общий риск-скор
}

// packages/acme/billing/src/Risk/RiskEngine.php
namespace Acme\Billing\Risk;

final class RiskEngine
{
    /** @param iterable<RiskRule> $rules */
    public function __construct(private iterable $rules) {}

    public function score(array $payload): int
    {
        $total = 0;
        foreach ($this->rules as $rule) {
            $total += $rule->evaluate($payload);
        }
        return min(100, $total);
    }
}

// packages/acme/billing/src/Services/BillingContext.php
namespace Acme\Billing\Services;

final class BillingContext
{
    public string $correlationId;
    public array  $idempotencyKeys = [];

    public function __construct()
    {
        $this->correlationId = bin2hex(random_bytes(8));
    }

    public function keyFor(string $operation): string
    {
        return $this->idempotencyKeys[$operation] ??= bin2hex(random_bytes(16));
    }
}

// packages/acme/billing/src/Providers/BillingServiceProvider.php
namespace Acme\Billing\Providers;

use Acme\Billing\Contracts\PaymentGateway;
use Acme\Billing\Gateways\FakeGateway;
use Acme\Billing\Gateways\StripeGateway;
use Acme\Billing\Risk\BlocklistRule;
use Acme\Billing\Risk\GeoMismatchRule;
use Acme\Billing\Risk\RiskEngine;
use Acme\Billing\Risk\VelocityRule;
use Acme\Billing\Services\BillingContext;
use Acme\Billing\Services\CheckoutService;
use Acme\Billing\Services\SubscriptionService;
use Illuminate\Contracts\Support\DeferrableProvider;
use Illuminate\Support\ServiceProvider;
use Stripe\StripeClient;

final class BillingServiceProvider extends ServiceProvider implements DeferrableProvider
{
    public function register(): void
    {
        $this->mergeConfigFrom(__DIR__ . '/../../config/billing.php', 'billing');

        // 1. Stripe-клиент — singleton, чтобы переиспользовать соединение.
        $this->app->singleton(StripeClient::class, fn () =>
            new StripeClient(config('billing.stripe.secret')));

        // 2. Дефолтная реализация контракта зависит от окружения.
        $this->app->singleton(PaymentGateway::class, function ($app) {
            return $app->environment('testing', 'local')
                ? new FakeGateway()
                : $app->make(StripeGateway::class);
        });

        // 3. Подписки всегда обслуживает Stripe — независимо от настроек мерчанта.
        $this->app->when(SubscriptionService::class)
            ->needs(PaymentGateway::class)
            ->give(StripeGateway::class);

        // 4. Контекст запроса — scoped, общий для всех потребителей в рамках запроса.
        $this->app->scoped(BillingContext::class);

        // 5. Правила риска тегируем — RiskEngine получит iterable через все теги.
        $this->app->tag([
            VelocityRule::class,
            GeoMismatchRule::class,
            BlocklistRule::class,
        ], 'billing.risk-rules');

        $this->app->singleton(RiskEngine::class, fn ($app) =>
            new RiskEngine($app->tagged('billing.risk-rules')));
    }

    public function boot(): void
    {
        $this->loadMigrationsFrom(__DIR__ . '/../../database/migrations');
        $this->loadRoutesFrom(__DIR__ . '/../../routes/web.php');

        if ($this->app()->runningInConsole()) {
            $this->publishes([
                __DIR__ . '/../../config/billing.php' => config_path('billing.php'),
            ], 'billing-config');
        }
    }

    public function provides(): array
    {
        return [
            PaymentGateway::class,
            StripeClient::class,
            BillingContext::class,
            RiskEngine::class,
        ];
    }
}

• singleton для StripeClient — дорогой ресурс с состоянием соединения, переиспользуется в рамках процесса;
• зависимая фабрика для PaymentGateway — реализация выбирается на основании окружения, контейнер прячет ветвление от потребителей;
• contextual переопределение для SubscriptionService — жёстко гарантирует одну реализацию вне зависимости от глобального дефолта;
• scoped биндинг BillingContext — единый correlationId по всем потребителям одного запроса, в очередях контекст создаётся заново;
• tag/tagged — RiskEngine расширяется новыми правилами без правки конструктора и без указания провайдера-агрегатора;
• DeferrableProvider — модуль не загружается на запросах, не затрагивающих биллинг, что снижает накладные расходы на «холодных» маршрутах;
• publishes с уникальным тегом billing-config — конфиг можно опубликовать, не задевая другие пакеты;
• composer.json + auto-discovery — провайдер регистрируется автоматически после composer require acme/billing.

// app/Http/Controllers/CheckoutController.php — потребитель пакета
final class CheckoutController
{
    public function store(
        CheckoutRequest $request,
        CheckoutService $checkout,
        RiskEngine $risk,
        BillingContext $ctx,
    ) {
        $score = $risk->score($request->validated());
        abort_if($score >= 80, 422, 'High-risk transaction');

        $chargeId = $checkout->charge(
            amountMinor:    $request->integer('amount_minor'),
            currency:       $request->string('currency'),
            idempotencyKey: $ctx->keyFor('checkout'),
        );

        return response()->json(['charge_id' => $chargeId, 'correlation' => $ctx->correlationId]);
    }
}

В тестах app()->instance(PaymentGateway::class, $fake) подменяет шлюз на изолированный мок без модификации провайдера. Запросный BillingContext и RiskEngine остаются собственными — именно так контейнер делает тестируемыми даже сложные модули.

Каждый из камней относится к одной из подсекций KB_13 и приведён здесь в дайджест-форме для быстрого аудита провайдеров и сервисов.