Il problema: query SQL sparse ovunque
In un progetto PHP che cresce, le query al database tendono a disperdersi: nel controller, nel service, a volte persino nella view. Un
SELECT * FROM orders WHERE status = 'pending' AND created_at > ...
appare in tre file diversi con variazioni minime. Quando lo schema cambia — una colonna rinominata, una tabella normalizzata — devi cercare e aggiornare ogni occorrenza. Se ne dimentichi una, il bug si manifesta in produzione su un percorso che nessuno testa spesso.
Il problema non e la SQL in se — e il fatto che la logica di persistenza e mescolata con la logica di business. Il controller che decide cosa mostrare all'utente non dovrebbe sapere come i dati sono organizzati nel database. Questa separazione di responsabilità e il cuore del Repository Pattern.
Cos'e il Repository Pattern: definizione e struttura
Martin Fowler descrive il Repository come "un mediatore tra il dominio e i layer di mapping dati, usando un'interfaccia simile a una collection per accedere agli oggetti del dominio". In pratica: il repository fa finta di essere una collezione in memoria, ma sotto il cofano parla con il database. Il codice di business chiede "dammi tutti gli ordini pendenti" senza sapere se la risposta viene da PostgreSQL, da un'API REST, o da un file JSON.
La struttura tipica prevede: un'interfaccia Repository (es. OrderRepositoryInterface) che dichiara metodi come findById(), findByStatus(), save(), delete(); una implementazione concreta (es. PgsqlOrderRepository) che esegue le query effettive; e il codice di dominio che dipende solo dall'interfaccia, mai dall'implementazione.
Esempio teorico: un repository per gli ordini
Immagina un e-commerce. L'interfaccia OrderRepositoryInterface dichiara:
-
findById(int $id): ?Order— restituisce un ordine o null -
findByStatus(string $status): array— tutti gli ordini con un dato stato -
findRecent(int $days): array— ordini degli ultimi N giorni -
save(Order $order): void— persiste un ordine nuovo o aggiornato -
delete(Order $order): void— rimuove un ordine -
countByCustomer(int $customerId): int— conta gli ordini di un cliente
L'implementazione PgsqlOrderRepository traduce ogni metodo in query PostgreSQL. Il findByStatus() diventa un SELECT ... WHERE status = :status. Il save() decide se fare INSERT o UPDATE in base all'esistenza dell'ID. Ma il service che gestisce la logica degli ordini non sa nulla di SQL: chiama $this->orders->findByStatus('pending') e riceve oggetti Order.
Grammar
Oggi con il Grammar non è più necessario dover svolgere una interfaccia per ogni driver database. Basti pensare che Laravel sfrutta un sistema architetturale nel builder che permette di cambiare sintassi alle query semplicemente cambiando driver nel file .env
Permettendo flessibilità al progetto di poter cambiare sistema senza problemi.
Il vantaggio del testing
Uno dei vantaggi più concreti del Repository Pattern e la testabilita. Per i test unitari del service puoi creare un InMemoryOrderRepository che implementa la stessa interfaccia usando un semplice array PHP. I test girano in millisecondi, senza database, senza setup, senza cleanup. E testano la logica di business pura, non la capacità di PHP di parlare con PostgreSQL.
Questo non elimina la necessita dei test di integrazione — servono comunque per verificare che le query funzionino — ma separa due preoccupazioni diverse: "la logica di business e corretta?" e "le query sono corrette?". Testare entrambe insieme rende impossibile distinguere dove sta il bug quando un test fallisce.
Repository vs Active Record vs Query Builder
Nel mondo PHP ci sono tre approcci principali all'accesso dati:
-
Active Record (Eloquent, il Model di Soft PHP MVC): l'oggetto e il record.
$user->save()persiste se stesso. Semplice per CRUD, ma mescola dominio e persistenza nella stessa classe. -
Query Builder: costruisci query fluentemente.
DB::table('users')->where('active', true)->get(). Flessibile ma sparge la logica di accesso dati ovunque venga usato. - Repository: centralizza l'accesso dati dietro un'interfaccia. Più codice iniziale, ma isolamento completo tra dominio e persistenza.
Non c'e una scelta universalmente giusta. Per un CRUD semplice, Active Record e perfetto. Per un dominio complesso con regole di business articolate, il Repository Pattern evita che la logica si disperda. La chiave e capire quando la complessità del dominio giustifica il layer aggiuntivo.
Repository Pattern e Domain-Driven Design
Nel DDD, il Repository e uno dei building block fondamentali. Ogni Aggregate Root ha il proprio repository. L'Aggregate Root e l'unico punto di ingresso per modificare un cluster di oggetti correlati: se Order e l'aggregate root che contiene OrderLine, il repository gestisce l'intero aggregato, non le singole righe.
Questo significa che OrderRepository::save(Order $order) persiste l'ordine e tutte le sue righe in una transazione atomica. Il codice di dominio non deve preoccuparsi di salvare le righe separatamente o di gestire le transazioni: il repository incapsula questa complessità.
Pattern complementari
Il Repository si combina naturalmente con altri pattern:
-
Specification Pattern: invece di aggiungere un metodo per ogni query, passi un oggetto Specification al repository.
$orders->findAll(new PendingOrdersOlderThan(30))e più flessibile difindPendingOlderThan(30). - Unit of Work: traccia tutte le modifiche agli oggetti e le persiste in un'unica transazione alla fine. Il repository registra le modifiche nel Unit of Work invece di scriverle immediatamente.
- Data Mapper: mappa oggetti del dominio a righe del database. Il repository usa il mapper per tradurre tra i due mondi.
Quando usare il Repository Pattern
- Usa il Repository quando la business logic e complessa e vuoi testarla senza database
- Usa il Repository quando più parti del codice accedono agli stessi dati con le stesse query
- Usa il Repository quando potresti cambiare il backend di persistenza in futuro (da MySQL a un'API, da file a database)
- Non usare il Repository per CRUD banali: il layer aggiuntivo sarebbe solo burocrazia senza beneficio
- Non usare il Repository se hai un solo modo di accedere ai dati e il testing diretto sul database e sufficiente
Il Repository Pattern non e un dogma: e uno strumento. Come ogni strumento, ha un costo (più codice, più astrazioni) e un beneficio (isolamento, testabilita, centralizzazione). La decisione su quando adottarlo dipende dalla complessità del dominio e dalla longevita prevista del progetto.