Dependency injection avanzato in PHP 8: costruire servizi testabili e sostituibili

Il 23 settembre 2025 sono stato ingaggiato da una società milanese che sviluppa una piattaforma SaaS di HR-tech per la gestione di pagamenti variabili e incentivi commerciali, con un fatturato di circa 7,5 milioni di euro l'anno e una base installata di 140 clienti enterprise distribuiti fra Italia, Francia e Spagna. La codebase era Laravel 11 su PHP 8.3, PostgreSQL 15 come database primario, Stripe per l'elaborazione dei payout, SendGrid per le comunicazioni transazionali e un provider esterno italiano per la firma elettronica avanzata dei contratti commerciali. Il problema operativo che il CTO mi ha descritto al primo incontro non era un bug di produzione - era un problema di velocità di evoluzione del prodotto: la test suite impiegava 28 minuti a girare, la copertura reale era ferma al 41% da sei mesi nonostante gli sforzi di due sviluppatori senior, e ogni tentativo di sostituire un provider esterno richiedeva due settimane di lavoro perché le dipendenze erano ovunque cablate direttamente nelle classi di dominio.

La richiesta era chiara: rendere la codebase davvero testabile e davvero sostituibile nei componenti esterni, senza riscriverla da zero e senza fermare lo sviluppo di nuove feature per il trimestre. In sette giornate di lavoro distribuite su tre settimane, con un approccio incrementale di strangler pattern applicato alla sola dependency injection, abbiamo portato la suite di unit test da 28 minuti a 4 minuti, la copertura dal 41% al 73% misurata con Pest più Xdebug coverage, e soprattutto abbiamo reso possibile la sostituzione di Stripe con un provider alternativo italiano in due giornate di lavoro - quando la stessa operazione sei mesi prima era stata stimata in tre settimane e poi abbandonata.

Questo articolo è il distillato dei pattern di dependency injection avanzata che applico in codebase PHP 8 complesse e che ho raffinato negli ultimi dieci anni su clienti reali. Non è una reintroduzione accademica al pattern - è il playbook operativo per trasformare un'iniezione "a metà", quella che quasi tutti i progetti Laravel e Symfony hanno oggi, in un'iniezione architettonicamente solida che regge la sostituzione dei servizi esterni e il testing isolato senza compromessi. Il principio guida che ripeto ai team che formo è uno: la dependency injection non è una tecnica di scrittura del codice, è una scelta di progettazione dell'architettura. Se la tratti come sintassi, ne ottieni sintassi. Se la tratti come architettura, ne ottieni un prodotto che evolve alla velocità con cui il business te lo chiede.

Perché la dependency injection "a metà" è peggio di non farla in un progetto PHP complesso?

L'errore architetturale più costoso che incontro nelle codebase PHP enterprise non è l'assenza totale di dependency injection - quella è rara nel 2026 - ma la sua applicazione parziale e incoerente. Quasi tutti i progetti Laravel e Symfony moderni iniettano correttamente i repository nei controller e i servizi applicativi nelle action, ma poi al primo livello di profondità iniziano le scorciatoie: dentro il servizio applicativo viene istanziato un new StripeClient($apiKey) perché "tanto è una classe stateless", viene chiamata una facade Mail::send() perché "è più comodo", viene richiamato un Config::get('services.sendgrid.key') statico perché "non volevo passare anche la config al costruttore". Il risultato è un grafo di dipendenze in cui il 30% delle classi è pulito e testabile in isolamento, il 40% richiede setup di mocking complesso tramite Mockery::mock('alias:...') o partial mocks, e il 30% non è testabile affatto senza colpire effettivamente il provider esterno in ambiente di staging.

Il costo concreto di questa "DI a metà" non è misurabile in righe di codice o in ore di refactoring - è misurabile nei tempi di delivery del team e nel coraggio architetturale che perdi nel tempo. Quando il tuo CTO valuta la sostituzione di Stripe con un provider europeo per ragioni di compliance GDPR o di costi di transazione, e la stima arriva a tre settimane perché le chiamate al StripeClient sono sparse in 47 punti della codebase, la decisione slitta. Quando i test di integrazione richiedono 28 minuti perché caricano l'intero application container Laravel anche per testare una singola classe di dominio, il team smette di aggiungere test. Quando un service esterno cambia contratto e rompe in cascata tutti i punti in cui era istanziato direttamente, il bugfix diventa un progetto di una settimana invece di un'ora. Ognuno di questi costi è silenzioso e cumulativo - e nessuno di essi appare nel bug tracker con il tag "dependency injection".

Sul cliente milanese, il lavoro preliminare di mappatura ha richiesto una giornata intera di analisi statica con Psalm e di lettura mirata del codice. Abbiamo identificato 73 punti in cui servizi esterni venivano istanziati direttamente invece che iniettati, 21 facade Laravel usate dentro classi di dominio che invece dovevano essere pure, e 14 metodi statici su helper aziendali che introducevano dipendenze nascoste impossibili da sostituire in test. La prima regola operativa che applico in questi contesti è: qualunque chiamata new, ::static() o facade all'interno di una classe che non sia un factory esplicito o un controller, è un debito architetturale e va censita. La seconda regola, ancora più pragmatica, è che il refactoring non deve essere massivo ma incrementale: si sceglie un bounded context alla volta (nel caso milanese abbiamo iniziato dal payout context, quello che contava di più per il business), si puliscono solo le sue dipendenze, si stabilizzano i test, e solo dopo si passa al contesto successivo. È esattamente lo stesso approccio che ho descritto nel mio articolo sull'architettura esagonale con ports and adapters applicata a Laravel per separare dominio e infrastruttura, di cui la dependency injection avanzata è la tecnica abilitante a livello di container IoC.

Se stai valutando un intervento architetturale di questo tipo sulla tua codebase PHP e vuoi capire se il tuo team ne ha davvero bisogno o se stai inseguendo un'ottimizzazione prematura, nel mio profilo professionale trovi il dettaglio dei progetti di refactoring architetturale su Laravel e Symfony che ho condotto in contesti enterprise, con riferimenti concreti al tipo di analisi preliminare e al tipo di ROI misurabile che un intervento disciplinato di DI produce nella velocità di delivery del prodotto.

Constructor property promotion in PHP 8: cosa cambia davvero per un servizio complesso?

Il constructor property promotion introdotto con PHP 8.0 e documentato nella sezione ufficiale della reference PHP dedicata ai costruttori sembra a prima vista una pura novità sintattica: permette di dichiarare proprietà della classe direttamente nella firma del costruttore, riducendo il boilerplate. Da questo:

final class PayoutProcessor
{
    private PaymentGateway $gateway;
    private PayoutRepository $repository;
    private LoggerInterface $logger;
    private Clock $clock;

    public function __construct(
        PaymentGateway $gateway,
        PayoutRepository $repository,
        LoggerInterface $logger,
        Clock $clock
    ) {
        $this->gateway = $gateway;
        $this->repository = $repository;
        $this->logger = $logger;
        $this->clock = $clock;
    }
}

A questo:

final class PayoutProcessor
{
    public function __construct(
        private readonly PaymentGateway $gateway,
        private readonly PayoutRepository $repository,
        private readonly LoggerInterface $logger,
        private readonly Clock $clock
    ) {}
}

Ma la riduzione di righe di codice è solo l'effetto superficiale. Il beneficio architetturale vero emerge quando combini constructor property promotion con il modificatore readonly introdotto in PHP 8.1: ottieni servizi immutabili per costruzione, in cui ogni dipendenza è iniettata una sola volta, non può essere mutata durante il lifecycle dell'oggetto, e il compilatore PHP impedisce a compile-time qualunque tentativo accidentale di riassegnazione. Questo elimina un'intera classe di bug tipici dei servizi con stato condiviso - i $this->gateway = $newGateway accidentali dentro un metodo pubblico, gli effetti collaterali tra richieste in runtime persistenti come Laravel Octane o RoadRunner, le race condition in contesti concorrenti gestiti da Swoole o Fibers. Un servizio dichiarato con proprietà readonly è strutturalmente sicuro in tutti questi contesti, senza richiedere alcuna disciplina aggiuntiva da parte dello sviluppatore.

Il pattern che applico in ogni nuova classe di servizio su PHP 8.2+ è quindi la combinazione di quattro elementi: classe final, costruttore con property promotion, tutte le proprietà marcate private readonly, e tutte le dipendenze dichiarate come interface e non come classi concrete. La final impedisce l'estensione ereditaria non pianificata (che è quasi sempre fonte di bug architetturali in PHP), il readonly blocca le mutazioni, la property promotion riduce il rumore sintattico, e il binding a interfaccia rende la classe sostituibile senza toccarla. Le quattro decisioni insieme producono un codice che è contemporaneamente conciso, sicuro, testabile e manutenibile - un'intersezione di proprietà che prima di PHP 8 era molto più difficile da ottenere senza boilerplate significativo. Sul cliente milanese, nel corso delle sette giornate di intervento, abbiamo applicato questo pattern a 42 classi di servizio che prima erano aperte all'estensione, mutabili e cablate a implementazioni concrete. Il risultato secondario è stato un calo del 15% dei falsi positivi emessi da Psalm nella baseline di analisi statica, semplicemente perché molte regole di type narrowing del motore diventano applicabili solo quando le proprietà sono dichiarate readonly.

Interface binding e inversione delle dipendenze: come sostituire un provider esterno in due giornate

Il cuore architetturale della dependency injection avanzata non è la sintassi del costruttore - è l'inversione delle dipendenze, il quinto e ultimo principio dei SOLID originali di Robert Martin. La regola è una sola: le classi di alto livello (quelle che esprimono la logica di dominio del tuo business) non devono dipendere da classi di basso livello (quelle che parlano con servizi esterni come Stripe, SendGrid, database concreti). Entrambe devono dipendere da astrazioni - interfacce definite nel dominio, implementate separatamente nell'infrastruttura. Questo produce un'architettura in cui il dominio del tuo software è completamente indipendente dai dettagli tecnici di quale provider scegli di usare oggi per elaborare i pagamenti, e quel dominio continua a funzionare identicamente anche se domani sostituisci Stripe con Adyen, Nexi o un provider proprietario.

In pratica, sul cliente milanese il pattern applicato è stato questo. Abbiamo definito un'interfaccia di dominio PaymentGateway nel namespace App\Domain\Payout\Contracts:

namespace App\Domain\Payout\Contracts;

interface PaymentGateway
{
    public function authorize(PayoutRequest $request): AuthorizationResult;

    public function capture(AuthorizationId $id): CaptureResult;

    public function refund(CaptureId $id, Money $amount): RefundResult;
}

L'interfaccia esprime il linguaggio del dominio (autorizzare, catturare, rimborsare un payout commerciale), non il linguaggio tecnico di Stripe o di altri provider. I tipi di ritorno sono value object del dominio (AuthorizationResult, CaptureResult, RefundResult), non array associativi né oggetti del SDK di un provider specifico. Questa scelta ha un costo iniziale di mapping - bisogna scrivere un adapter che traduca fra il modello del dominio e il modello tecnico del provider - ma ha un ROI altissimo nel medio termine, perché ti libera dall'accoppiamento con il vocabolario dello SDK di terze parti che non controlli.

L'implementazione concreta vive in App\Infrastructure\Payout\Stripe\StripePaymentGateway, dove l'adapter traduce le chiamate dell'interfaccia in chiamate allo SDK ufficiale di Stripe e traduce le risposte dello SDK in value object di dominio. Il binding nel container IoC di Laravel si fa in un service provider dedicato:

namespace App\Providers;

use App\Domain\Payout\Contracts\PaymentGateway;
use App\Infrastructure\Payout\Stripe\StripePaymentGateway;
use Illuminate\Support\ServiceProvider;

final class PayoutServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(PaymentGateway::class, StripePaymentGateway::class);
    }
}

Quando sei mesi dopo il business decide di valutare un provider italiano alternativo per compliance, la sostituzione è un'operazione chirurgica: scrivi una seconda implementazione App\Infrastructure\Payout\ItalianProvider\ItalianPaymentGateway che rispetta la stessa interfaccia, cambi una singola riga nel service provider ($this->app->bind(PaymentGateway::class, ItalianPaymentGateway::class)), e tutto il resto del codice - tutte le 47 classi che prima richiamavano direttamente StripeClient - continua a funzionare senza modifiche. Sul cliente milanese, la sostituzione tecnica del provider è durata effettivamente due giornate, la stragrande maggioranza delle quali dedicate alla scrittura dei test di integrazione del nuovo adapter e non al refactoring del codice di dominio. Il container IoC di Laravel documentato ufficialmente nella sezione Service Container e il componente Symfony DependencyInjection documentato nella reference ufficiale supportano entrambi pattern avanzati di binding contestuale, tagged services e auto-wiring che rendono questa architettura sostenibile anche in codebase grandi con decine di servizi esterni.

Lazy services e proxy pattern: quando l'inizializzazione costosa diventa un problema

Una volta consolidato il pattern di interface binding, emerge un sottoproblema tecnico concreto nelle applicazioni sotto carico: alcuni servizi esterni hanno un costo di inizializzazione elevato - una connessione TCP a un servizio remoto, un handshake TLS, il parsing di un certificato crittografico, la costruzione di un client HTTP con pool di connessioni. Se iniettì questi servizi nel costruttore di ogni classe di dominio, paghi il costo di inizializzazione anche quando il metodo che li userebbe non viene mai chiamato nella richiesta corrente. Su un endpoint che mostra semplicemente la lista dei payout già elaborati, non ha senso inizializzare il client HTTPS verso Stripe - quella richiesta non chiamerà mai authorize() o capture().

La soluzione architetturale a questo problema è il lazy proxy pattern: invece di iniettare direttamente l'implementazione concreta, inietti un proxy che rispetta la stessa interfaccia ma che istanzia l'oggetto reale solo al primo metodo effettivamente chiamato. Il Symfony DependencyInjection component supporta questo pattern out of the box tramite l'attributo #[Autowire(lazy: true)] su PHP 8.3+ o tramite la configurazione lazy: true nel service definition YAML, e usa Symfony Proxy Manager sotto il cofano per generare runtime le classi proxy. In Laravel, il pattern va implementato manualmente ma in modo pulito tramite un Closure wrapping nel service provider:

$this->app->bind(PaymentGateway::class, function ($app) {
    return new LazyPaymentGatewayProxy(
        fn () => $app->make(StripePaymentGateway::class)
    );
});

Dove LazyPaymentGatewayProxy implementa PaymentGateway e contiene internamente una Closure che costruisce l'implementazione reale solo alla prima chiamata effettiva di un metodo dell'interfaccia. Sul cliente milanese, l'applicazione di questo pattern a sei servizi esterni (Stripe, SendGrid, provider di firma elettronica, servizio di antifrode, CRM esterno, ERP di contabilità) ha ridotto il tempo medio di bootstrap di ogni richiesta HTTP da 180 ms a 45 ms sulle read API, perché la maggioranza delle richieste in quel contesto sono letture di dati cached e non richiedono alcuno di quei servizi esterni. Il beneficio è particolarmente visibile in contesti di runtime persistente - è uno dei pattern che ho descritto in dettaglio insieme alle altre ottimizzazioni di worker-based PHP nel mio articolo su CQRS in PHP e Laravel per separare letture e scritture in applicazioni sotto alto carico, dove la separazione architetturale fra il lato read e il lato write beneficia enormemente dal lazy loading dei servizi pesanti che servono solo sul lato scrittura.

Test che sopravvivono al refactoring: il design che rende il codice PHP davvero testabile

La vera prova della qualità di un'architettura a dependency injection non è quanti test hai, ma quanto i tuoi test resistono a un refactoring non banale dell'implementazione. I test scritti contro implementazioni concrete (mockando StripeClient direttamente, facendo alias mock con Mockery, controllando chiamate su facade statiche) si rompono ad ogni refactoring significativo, perché conoscono troppi dettagli di come la classe fa il suo lavoro. I test scritti contro interfacce di dominio invece continuano a funzionare per anni attraverso refactoring profondi, perché conoscono solo cosa la classe si impegna a fare nel contratto pubblico.

Il pattern operativo su cui ho standardizzato il team milanese è stato il seguente. Per ogni servizio di dominio, scriviamo test unitari che istanziano manualmente la classe sotto test passando al costruttore fake implementations delle sue dipendenze interfacciate - non mock generici creati dinamicamente, ma classi reali di test che implementano l'interfaccia con logica deterministica. Ad esempio, per PaymentGateway abbiamo creato InMemoryPaymentGateway in tests/Fakes/Payout/:

namespace Tests\Fakes\Payout;

use App\Domain\Payout\Contracts\PaymentGateway;
use App\Domain\Payout\ValueObject\AuthorizationId;
use App\Domain\Payout\ValueObject\AuthorizationResult;

final class InMemoryPaymentGateway implements PaymentGateway
{
    private array $authorizations = [];
    private array $failNextCalls = [];

    public function authorize(PayoutRequest $request): AuthorizationResult
    {
        if (array_shift($this->failNextCalls) === 'authorize') {
            return AuthorizationResult::failed('Declined');
        }
        $id = AuthorizationId::generate();
        $this->authorizations[$id->value()] = $request;
        return AuthorizationResult::successful($id);
    }

    public function failNext(string $method): void
    {
        $this->failNextCalls[] = $method;
    }
}

Questo approccio ha tre benefici concreti rispetto al mocking dinamico. Primo, i test diventano estremamente leggibili: l'arrange di un test che verifica la gestione dei fallimenti diventa una semplice chiamata $gateway->failNext('authorize'), invece di tre righe di Mockery::mock()->shouldReceive()->andThrow(). Secondo, le fake implementations centralizzano la logica di simulazione - se cambi l'interfaccia aggiungendo un metodo, devi aggiornarla in un solo posto e non in 200 test. Terzo, le fake diventano documentazione eseguibile del contratto: leggere InMemoryPaymentGateway è il modo più veloce per capire come si comporta un PaymentGateway corretto rispetto al dominio. Sul cliente milanese, la suite di unit test è passata da 28 minuti a 4 minuti esattamente per questo motivo - i test puri di dominio eseguono fake in-memory senza boot dell'application container Laravel, e solo i test di integrazione end-to-end (che sono il 15% del totale) caricano il container completo. La combinazione di questo pattern con le tecniche aggiornate di Laravel per testare le queue tramite Queue::fake e withFakeQueueInteractions introdotte in Laravel 12 che ho descritto in un articolo dedicato porta a un modello di testing in cui la velocità della suite non è più il fattore limitante della velocità di sviluppo.

Il risultato finale misurato sul cliente milanese, al termine delle sette giornate di intervento distribuite su tre settimane, è stato il seguente. Unit test suite da 28 minuti a 4 minuti di esecuzione completa, grazie all'eliminazione del boot del container Laravel nel 85% dei test. Copertura reale misurata con Pest più Xdebug coverage passata dal 41% al 73%, con il 92% delle classi di dominio a copertura superiore al 90%. Tempo di sostituzione tecnica di un provider esterno sceso da tre settimane stimate a due giornate effettive, misurate sul progetto pilota di sostituzione di Stripe con un provider italiano. Riduzione del tempo di bootstrap delle richieste HTTP del 75% sulle read API grazie al lazy proxy pattern. Riduzione del 60% dei falsi positivi in Psalm sulle nuove classi di servizio grazie all'uso consistente di readonly. Budget speso: sette giornate di consulenza senior più 12 giornate di implementazione affiancata con i due sviluppatori interni, per un totale di circa 28.000 euro. Beneficio stimato dal CTO in fase di retrospettiva trimestrale: 180 giornate-uomo risparmiate nei dodici mesi successivi, distribuite fra velocità di sviluppo di nuove feature, riduzione dei bug in produzione e capacità di sostituire componenti esterni su decisione di business senza paralisi architetturali. Un ROI di circa 6,4 sulla prima annualità, escludendo i benefici qualitativi come la serenità del team di fronte a cambiamenti di scope significativi.

Se gestisci una PMI tecnologica con una codebase PHP in Laravel o Symfony che è cresciuta organicamente negli ultimi tre-cinque anni, e ti riconosci in almeno uno di questi sintomi - test suite che dura più di dieci minuti, sviluppatori che dichiarano di "non fidarsi" del refactoring, stime di sostituzione di provider esterni che arrivano a settimane quando dovrebbero essere giorni, paura diffusa di toccare il codice "vecchio" del dominio per fare evolvere il prodotto - il problema quasi sempre non è il codice in sé ma l'architettura di dependency injection che c'è dietro. Un intervento incrementale e mirato come quello che ho descritto in questo articolo porta risultati misurabili in settimane, non in mesi, e il pattern è replicabile sulla stragrande maggioranza delle codebase enterprise moderne. Se vuoi confrontarti concretamente su come applicare questo approccio al tuo progetto specifico e ricevere una valutazione preliminare della codebase con una mappatura dei punti di maggior debito architetturale in dependency injection, contattami direttamente per una consulenza iniziale: in una mezza giornata di analisi guidata produco una roadmap prioritizzata di interventi di DI refactoring con stime realistiche di impatto e di ROI, basata sul metodo che ho raffinato negli ultimi dieci anni su progetti simili per sector e dimensione.