Service container

Cos’è il service container

Il service container di Laravel è il meccanismo che gestisce le dipendenze delle classi ed esegue la dependency injection. Per “dependency injection” si intende “iniettare” nella classe le sue dipendenze attraverso il costruttore o, in alcuni casi, un setter. Vediamo un esempio.

<?php

namespace App\Http\Controllers;

use App\Services\AppleMusic;
use Illuminate\View\View;

class PodcastController extends Controller
{
    /**
     * Crea una nuova istanza del controller
     */
    public function __construct(
        protected AppleMusic $apple,
    ) {}

    /**
     * Mostra le informazioni sul podcast indicato
     */
    public function show(string $id): View
    {
        return view('podcasts.show', [
            'podcast' => $this->apple->findPodcast($id)
        ]);
    }
}

PodcastController deve recuperare un podcast da una fonte dati come Apple Music. Iniettiamo quindi il servizio che sa recuperarlo. Grazie all’injection, in test possiamo sostituire facilmente AppleMusic con un mock (implementazione fittizia).

Capire a fondo il service container è indispensabile per costruire grandi applicazioni Laravel. Ti aiuta anche a contribuire al core di Laravel stesso.

Risoluzione zero-configuration

Se una classe dipende solo da altre classi concrete (non interfacce), non devi dire al container come risolverla. Ad esempio, questo codice in routes/web.php:

<?php

class Service
{
    // ...
}

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

L’esempio definisce la classe direttamente nel file di route a scopo dimostrativo. In un’applicazione reale, le classi di servizio vanno nella directory app/Services.

Accedendo a questa route, Laravel risolve automaticamente Service e lo inietta nell’handler della route. Beneficerai della dependency injection senza scrivere alcuna configurazione. Nella maggior parte delle classi di un’app Laravel — controller, event listener, middleware ecc. — le dipendenze vengono iniettate automaticamente dal container.

Binding

Binding di base

La maggior parte dei binding si registra all’interno dei service provider. Nel provider puoi accedere al container tramite $this->app.

bind

Con bind registri un binding passando un nome di classe o interfaccia e una closure.

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

La closure riceve come argomento il container stesso, con cui puoi risolvere le sub-dipendenze. Fuori da un service provider puoi operare sul container tramite la facade App.

use App\Services\Transistor;
use Illuminate\Contracts\Foundation\Application;
use Illuminate\Support\Facades\App;

App::bind(Transistor::class, function (Application $app) {
    // ...
});

Le classi che non dipendono da interfacce non hanno bisogno di essere bindate. Il container le risolve automaticamente tramite reflection.

singleton

Il metodo singleton registra un binding che verrà risolto una sola volta. Una volta risolto, tutte le chiamate successive restituiranno la stessa istanza.

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

Con singletonIf registri il binding singleton solo se il tipo non è già bindato.

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

Attributo Singleton

Puoi indicare al container di risolvere una sola volta anche applicando l’attributo #[Singleton] alla classe o interfaccia.

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Singleton;

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

Binding scoped

Con scoped bindi una classe o interfaccia a un’istanza risolta una sola volta all’interno del ciclo di vita di una richiesta / job. Simile a singleton, ma le istanze registrate con scoped vengono scartate ogni volta che l’applicazione avvia un nuovo “ciclo di vita” — ad esempio quando un worker di Laravel Octane processa una nuova richiesta o un queue worker elabora un nuovo job.

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

Con scopedIf registri il binding scoped solo se non è già registrato.

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

Attributo Scoped

Puoi ottenere lo stesso comportamento applicando l’attributo #[Scoped] alla classe o interfaccia.

<?php

namespace App\Services;

use Illuminate\Container\Attributes\Scoped;

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

instance

Puoi bindare un’istanza già esistente con instance. Tutte le chiamate successive restituiscono quella stessa istanza.

use App\Services\Transistor;
use App\Services\PodcastParser;

$service = new Transistor(new PodcastParser);

$this->app->instance(Transistor::class, $service);

Bindare un’interfaccia a un’implementazione

Una delle potenzialità del service container è la possibilità di bindare un’interfaccia a un’implementazione specifica. Ad esempio, dati l’interfaccia EventPusher e la sua implementazione RedisEventPusher:

use App\Contracts\EventPusher;
use App\Services\RedisEventPusher;

$this->app->bind(EventPusher::class, RedisEventPusher::class);

Il container inietterà RedisEventPusher in tutte le classi che dipendono da EventPusher. Basta usare il type hint dell’interfaccia nel costruttore.

use App\Contracts\EventPusher;

/**
 * Crea una nuova istanza della classe
 */
public function __construct(
    protected EventPusher $pusher,
) {}

Dipendere dall’interfaccia permette di sostituire l’implementazione senza modificare il codice. Rende più semplici test e futuri cambiamenti.

Attributo Bind

Laravel offre anche il pratico attributo Bind. Applicandolo all’interfaccia, dici a Laravel quale implementazione iniettare automaticamente quando quell’interfaccia viene richiesta. Con Bind non serve registrare il binding nel service provider. Puoi mettere più Bind sulla stessa interfaccia per iniettare implementazioni diverse a seconda dell’ambiente.

<?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
{
    // ...
}

Per binding basati su condizioni arbitrarie, usa l’attributo BindWhen. La closure riceve il container e restituisce true quando il binding va applicato. Bind e BindWhen sono valutati nell’ordine di dichiarazione.

use App\Services\BetaEventPusher;
use Illuminate\Container\Attributes\BindWhen;
use Laravel\Pennant\Feature;

#[BindWhen(BetaEventPusher::class, static fn () => Feature::active('beta-events'))]
interface EventPusher
{
    // ...
}

Per usare BindWhen serve PHP 8.5 o superiore.

Combinandoli con gli attributi Singleton o Scoped indichi se il binding va risolto una sola volta o una volta per richiesta / job.

use App\Services\RedisEventPusher;
use Illuminate\Container\Attributes\Bind;
use Illuminate\Container\Attributes\Singleton;

#[Bind(RedisEventPusher::class)]
#[Singleton]
interface EventPusher
{
    // ...
}

Risoluzione automatica (DI tramite type hint)

Nella risoluzione di classi come controller, event listener e middleware, il service container guarda i type hint del costruttore e inietta automaticamente le dipendenze.

<?php

namespace App\Http\Controllers;

use App\Repositories\UserRepository;

class UserController extends Controller
{
    /**
     * Crea una nuova istanza del controller
     */
    public function __construct(
        protected UserRepository $users,
    ) {}
}

Se UserRepository non dipende da un’interfaccia, non serve registrarla nel container: basta accedere a una route che usi il controller e il container risolve e inietta le dipendenze.

Risolvere dal container

Metodo make

Con make risolvi un’istanza dal container.

use App\Services\Transistor;

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

Se una dipendenza non può essere risolta dal container, puoi passare argomenti aggiuntivi con makeWith.

$transistor = $this->app->makeWith(Transistor::class, ['id' => 1]);

Injection automatica

In pratica, quasi non chiamerai mai make direttamente. Basta aggiungere i type hint al costruttore delle classi che il container risolve (controller, event listener, middleware ecc.) e il container inietterà automaticamente le dipendenze.

Facade e container

Le facade di Laravel sono un’interfaccia statica agli oggetti del container. Ad esempio, Cache::get() recupera internamente il servizio Cache dal container e ne chiama il metodo.

use Illuminate\Support\Facades\Cache;

// chiamata tramite facade
Cache::get('key');

// chiamata equivalente sul container
app('cache')->get('key');

Le facade sono comodi wrapper del container. Nei test puoi sostituire una facade con un mock.

use Illuminate\Support\Facades\Cache;

Cache::shouldReceive('get')
    ->once()
    ->with('key')
    ->andReturn('value');

Esempio pratico di constructor injection

Vediamo un pattern tipico in un’applicazione reale.

Definisci l'interfaccia

<?php

namespace App\Contracts;

interface PaymentGateway
{
    public function charge(int $amount, string $token): bool;
}

Crea la classe di implementazione

<?php

namespace App\Services;

use App\Contracts\PaymentGateway;

class StripePaymentGateway implements PaymentGateway
{
    public function charge(int $amount, string $token): bool
    {
        // logica di pagamento con l'API Stripe...
        return true;
    }
}

Registra il binding nel service provider

use App\Contracts\PaymentGateway;
use App\Services\StripePaymentGateway;

$this->app->singleton(PaymentGateway::class, StripePaymentGateway::class);

Ricevi l'injection nel controller

<?php

namespace App\Http\Controllers;

use App\Contracts\PaymentGateway;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    public function __construct(
        protected PaymentGateway $payment,
    ) {}

    public function store(Request $request)
    {
        $this->payment->charge(
            $request->amount,
            $request->payment_token
        );

        // ...
    }
}

Con questo pattern, se passi da Stripe a un altro provider di pagamento, basta cambiare il binding in un unico punto.

Prossimi passi

Service provider

Come registrare i binding usando i service provider.

Architettura

Database

Eloquent

Sicurezza

Eventi

Mail e notifiche

Pagamenti

Elaborazione asincrona

Comunicazione in tempo reale

Scheduling

Cache e ottimizzazione

Internazionalizzazione

File e storage

Debug e monitoraggio

Console e CLI

Performance

Frontend

Sviluppo con AI

Ambiente di sviluppo

Cos’è il service container

Risoluzione zero-configuration

Binding

Binding di base

bind

singleton

Attributo Singleton

Binding scoped

Attributo Scoped

instance

Bindare un’interfaccia a un’implementazione

Attributo Bind

Risoluzione automatica (DI tramite type hint)

Risolvere dal container

Metodo make

Injection automatica

Facade e container

Esempio pratico di constructor injection

Prossimi passi

Service provider

​Cos’è il service container

​Risoluzione zero-configuration

​Binding

​Binding di base

​bind

​singleton

​Attributo Singleton

​Binding scoped

​Attributo Scoped

​instance

​Bindare un’interfaccia a un’implementazione

​Attributo Bind

​Risoluzione automatica (DI tramite type hint)

​Risolvere dal container

​Metodo make

​Injection automatica

​Facade e container

​Esempio pratico di constructor injection

​Prossimi passi

Service provider

Cos’è il service container

Risoluzione zero-configuration

Binding

Binding di base

bind

singleton

Attributo Singleton

Binding scoped

Attributo Scoped

instance

Bindare un’interfaccia a un’implementazione

Attributo Bind

Risoluzione automatica (DI tramite type hint)

Risolvere dal container

Metodo make

Injection automatica

Facade e container

Esempio pratico di constructor injection

Prossimi passi