Laravel Service Container Explained — Bindings, Resolution & Real-World Internals

<?php

// File: app/Services/CurrencyConverter.php
namespace App\Services;

class CurrencyConverter
{
    private string $baseCurrency;

    public function __construct(string $baseCurrency = 'USD')
    {
        $this->baseCurrency = $baseCurrency;
    }

    public function convert(float $amount, string $targetCurrency): float
    {
        // Simplified — real implementation would call an API
        $rates = ['EUR' => 0.92, 'GBP' => 0.79, 'JPY' => 149.5];
        return $amount * ($rates[$targetCurrency] ?? 1.0);
    }

    public function getBase(): string
    {
        return $this->baseCurrency;
    }
}

// File: app/Services/InvoiceService.php
namespace App\Services;

class InvoiceService
{
    // Container sees this type-hint and auto-resolves CurrencyConverter
    public function __construct(
        private readonly CurrencyConverter $currencyConverter
    ) {}

    public function generateTotal(float $amountInUsd, string $clientCurrency): string
    {
        $converted = $this->currencyConverter->convert($amountInUsd, $clientCurrency);
        return number_format($converted, 2) . ' ' . $clientCurrency;
    }
}

// File: routes/web.php  (or a tinker session)
use App\Services\InvoiceService;

// The container resolves InvoiceService AND CurrencyConverter automatically.
// No manual `new InvoiceService(new CurrencyConverter())` needed.
$invoiceService = app(InvoiceService::class);

echo $invoiceService->generateTotal(500.00, 'EUR'); // 460.00 EUR
echo PHP_EOL;
echo $invoiceService->generateTotal(500.00, 'GBP'); // 395.00 GBP

// Proving reflection is doing the work — the container inspects the constructor:
$reflection = new ReflectionClass(InvoiceService::class);
$params = $reflection->getConstructor()->getParameters();

foreach ($params as $param) {
    // Outputs the type-hint the container uses to resolve each dependency
    echo 'Dependency: ' . $param->getType()->getName() . PHP_EOL;
}

<?php

// File: app/Providers/NotificationServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\NotifierInterface;
use App\Contracts\ReportGeneratorInterface;
use App\Services\EmailNotifier;
use App\Services\SmsNotifier;
use App\Services\PdfReportGenerator;
use App\Services\CsvReportGenerator;
use App\Http\Controllers\OrderController;
use App\Http\Controllers\SupportController;
use App\Jobs\WeeklyDigestJob;

class NotificationServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // BIND — fresh instance every resolution.
        // CartBuilder accumulates state, so sharing it between callers would corrupt totals.
        $this->app->bind(
            \App\Services\CartBuilder::class,
            fn ($app) => new \App\Services\CartBuilder(
                $app->make(\App\Repositories\ProductRepository::class)
            )
        );

        // SINGLETON — built once, reused for the container's lifetime.
        // DatabaseConnectionPool is expensive to initialise; we want one pool, not fifty.
        $this->app->singleton(
            \App\Services\DatabaseConnectionPool::class,
            fn ($app) => new \App\Services\DatabaseConnectionPool(
                config('database.connections.mysql')
            )
        );

        // SCOPED — singleton within a request/job, auto-flushed between them.
        // Perfect for Octane: AuthenticatedUser holds per-request identity.
        $this->app->scoped(
            \App\Services\AuthenticatedUser::class,
            fn ($app) => new \App\Services\AuthenticatedUser(
                $app->make(\Illuminate\Http\Request::class)
            )
        );

        // CONTEXTUAL BINDING — same interface, different implementations.
        // OrderController gets email notifications (customers expect email receipts).
        $this->app
            ->when(OrderController::class)
            ->needs(NotifierInterface::class)
            ->give(EmailNotifier::class);

        // SupportController gets SMS (support staff work from phones).
        $this->app
            ->when(SupportController::class)
            ->needs(NotifierInterface::class)
            ->give(SmsNotifier::class);

        // WeeklyDigestJob gets both — tagged binding returns a collection.
        $this->app->tag(
            [EmailNotifier::class, SmsNotifier::class],
            'notifiers'
        );

        // Bind the report generator with a closure for runtime config
        $this->app
            ->when(\App\Console\Commands\ExportCommand::class)
            ->needs(ReportGeneratorInterface::class)
            ->give(fn ($app) => new CsvReportGenerator(
                separator: config('exports.csv_separator', ','),
                includeHeaders: true
            ));
    }
}

// File: app/Http/Controllers/OrderController.php
namespace App\Http\Controllers;

use App\Contracts\NotifierInterface;

class OrderController extends Controller
{
    // Container automatically injects EmailNotifier here — no conditional logic needed
    public function __construct(
        private readonly NotifierInterface $notifier
    ) {}

    public function store(\Illuminate\Http\Request $request): \Illuminate\Http\JsonResponse
    {
        // ... order creation logic ...
        $this->notifier->send('Your order has been placed!');
        return response()->json(['status' => 'created'], 201);
    }
}

// File: app/Http/Controllers/SupportController.php
namespace App\Http\Controllers;

use App\Contracts\NotifierInterface;

class SupportController extends Controller
{
    // Container automatically injects SmsNotifier here
    public function __construct(
        private readonly NotifierInterface $notifier
    ) {}

    public function escalate(int $ticketId): \Illuminate\Http\JsonResponse
    {
        $this->notifier->send("Ticket #{$ticketId} escalated to Level 2.");
        return response()->json(['escalated' => true]);
    }
}

<?php

// File: app/Providers/AppServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\PaymentGatewayInterface;
use App\Services\StripePaymentGateway;
use App\Services\CachedPaymentGateway;
use App\Services\ReportExporter;
use Illuminate\Support\Facades\Log;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register the real Stripe implementation as a singleton
        $this->app->singleton(
            PaymentGatewayInterface::class,
            fn ($app) => new StripePaymentGateway(
                apiKey: config('services.stripe.secret'),
                webhookSecret: config('services.stripe.webhook_secret')
            )
        );

        // EXTEND — transparently wrap StripePaymentGateway with a caching decorator.
        // Code that depends on PaymentGatewayInterface has no idea caching exists.
        $this->app->extend(
            PaymentGatewayInterface::class,
            function (PaymentGatewayInterface $gateway, $app) {
                // Wrap the resolved Stripe instance in our caching layer
                return new CachedPaymentGateway(
                    inner: $gateway,                      // the real gateway
                    cache: $app->make('cache.store'),     // Laravel's cache
                    ttlSeconds: 300                        // cache fee lookups for 5 min
                );
            }
        );

        // RESOLVING callback — fires every time ReportExporter is built.
        // We set the timezone here because it comes from authenticated user context,
        // which isn't available at container-build time.
        $this->app->resolving(
            ReportExporter::class,
            function (ReportExporter $exporter, $app) {
                $userTimezone = $app->make('auth')->user()?->timezone ?? 'UTC';
                // Configure the exporter with the authenticated user's timezone
                $exporter->setTimezone($userTimezone);
            }
        );

        // AFTER RESOLVING — runs after all resolving() callbacks.
        // Useful for cross-cutting concerns like audit logging.
        $this->app->afterResolving(
            ReportExporter::class,
            function (ReportExporter $exporter, $app) {
                Log::debug('ReportExporter instantiated', [
                    'timezone' => $exporter->getTimezone(),
                    'memory_peak_mb' => round(memory_get_peak_usage(true) / 1048576, 2),
                ]);
            }
        );
    }
}

// File: app/Services/CachedPaymentGateway.php
namespace App\Services;

use App\Contracts\PaymentGatewayInterface;
use Illuminate\Contracts\Cache\Repository as CacheRepository;

class CachedPaymentGateway implements PaymentGatewayInterface
{
    public function __construct(
        private readonly PaymentGatewayInterface $inner,
        private readonly CacheRepository $cache,
        private readonly int $ttlSeconds
    ) {}

    public function charge(float $amountInCents, string $currency, string $token): array
    {
        // Charges are never cached — idempotency must be handled at a higher level
        return $this->inner->charge($amountInCents, $currency, $token);
    }

    public function getFees(string $currency): array
    {
        $cacheKey = "payment_fees_{$currency}";

        // Cache the fee schedule — this rarely changes and is expensive to fetch
        return $this->cache->remember(
            $cacheKey,
            $this->ttlSeconds,
            fn () => $this->inner->getFees($currency)
        );
    }
}

// Anywhere in your app:
$gateway = app(PaymentGatewayInterface::class);
// $gateway is now a CachedPaymentGateway wrapping StripePaymentGateway.
// Calling getFees() hits cache first — no Stripe API call if cached.
$fees = $gateway->getFees('USD');
print_r($fees);

<?php

// File: tests/Feature/PaymentControllerTest.php
namespace Tests\Feature;

use Tests\TestCase;
use App\Contracts\PaymentGatewayInterface;
use App\Models\Order;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;

class PaymentControllerTest extends TestCase
{
    use RefreshDatabase;

    public function test_successful_charge_creates_order_and_returns_201(): void
    {
        // Arrange: build a mock that simulates a successful Stripe charge
        $fakeGateway = $this->createMock(PaymentGatewayInterface::class);
        $fakeGateway
            ->expects($this->once())
            ->method('charge')
            ->with(4999, 'USD', 'tok_test_visa') // assert the right args are passed
            ->willReturn([
                'id'     => 'ch_test_abc123',
                'status' => 'succeeded',
                'amount' => 4999,
            ]);

        // Swap the real gateway in the container with our fake.
        // $this->swap() registers cleanup so the real gateway is restored after this test.
        $this->swap(PaymentGatewayInterface::class, $fakeGateway);

        $user = User::factory()->create();

        // Act: hit the endpoint as an authenticated user
        $response = $this->actingAs($user)
            ->postJson('/api/payments/charge', [
                'amount_cents' => 4999,
                'currency'     => 'USD',
                'token'        => 'tok_test_visa',
            ]);

        // Assert: correct HTTP status and database state
        $response->assertStatus(201)
                 ->assertJsonFragment(['status' => 'succeeded']);

        $this->assertDatabaseHas('orders', [
            'user_id'          => $user->id,
            'stripe_charge_id' => 'ch_test_abc123',
            'amount_cents'     => 4999,
        ]);
    }

    public function test_failed_charge_returns_422_and_does_not_create_order(): void
    {
        $fakeGateway = $this->createMock(PaymentGatewayInterface::class);
        $fakeGateway
            ->method('charge')
            ->willThrowException(
                // Simulate a declined card from Stripe
                new \App\Exceptions\PaymentDeclinedException('Your card was declined.')
            );

        $this->swap(PaymentGatewayInterface::class, $fakeGateway);

        $user = User::factory()->create();

        $response = $this->actingAs($user)
            ->postJson('/api/payments/charge', [
                'amount_cents' => 9999,
                'currency'     => 'USD',
                'token'        => 'tok_test_declined',
            ]);

        $response->assertStatus(422)
                 ->assertJsonFragment(['message' => 'Your card was declined.']);

        // Critical: no order should exist if payment failed
        $this->assertDatabaseMissing('orders', ['user_id' => $user->id]);
    }
}

<?php

// File: app/Providers/PaymentServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\PaymentGatewayInterface;
use App\Services\StripePaymentGateway;

class PaymentServiceProvider extends ServiceProvider
{
    // DEFERRED — only loads when PaymentGatewayInterface is actually requested.
    // Reduces boot time for requests that don't involve payments.
    protected $defer = true;

    public function register(): void
    {
        // SAFE: register() is where bindings go.
        // No other provider needs to be loaded for this to work.
        $this->app->singleton(
            PaymentGatewayInterface::class,
            fn ($app) => new StripePaymentGateway(
                apiKey: config('services.stripe.secret'),
                webhookSecret: config('services.stripe.webhook_secret')
            )
        );
    }

    public function boot(): void
    {
        // SAFE: boot() runs after all register() phases.
        // We can now safely use other services.

        // Publish config file
        $this->publishes([
            __DIR__.'/../../config/payment.php' => config_path('payment.php'),
        ], 'payment-config');

        // Register a macro on the Response factory
        \Illuminate\Http\Response::macro('paymentError', function ($message, $code) {
            return response()->json(['error' => $message, 'code' => $code], 422);
        });
    }

    public function provides(): array
    {
        // Required for deferred providers — tells the container which services this provides.
        return [PaymentGatewayInterface::class];
    }
}

<?php

// File: app/Providers/NotificationServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\NotifierInterface;
use App\Services\EmailNotifier;
use App\Services\SmsNotifier;
use App\Services\PushNotifier;
use App\Services\NotificationDispatcher;

class NotificationServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Tag all notifier implementations
        $this->app->tag(
            [EmailNotifier::class, SmsNotifier::class, PushNotifier::class],
            'notifiers'
        );

        // NotificationDispatcher receives ALL notifiers via tagged binding
        $this->app->bind(
            NotificationDispatcher::class,
            fn ($app) => new NotificationDispatcher(
                notifiers: $app->tagged('notifiers')->all()
            )
        );
    }
}

// File: app/Services/NotificationDispatcher.php
namespace App\Services;

use App\Contracts\NotifierInterface;
use Illuminate\Support\Collection;

class NotificationDispatcher
{
    /** @param Collection<int, NotifierInterface> $notifiers */
    public function __construct(
        private readonly Collection $notifiers
    ) {}

    public function dispatch(string $message, array $channels = []): void
    {
        $targets = $channels
            ? $this->notifiers->filter(fn ($n) => in_array($n->channel(), $channels))
            : $this->notifiers;

        $targets->each(fn (NotifierInterface $notifier) => $notifier->send($message));
    }
}