Architettura pulita per applicazioni Laravel: guida al refactoring da Fat Controller in L9/L10 a Service e Repository Pattern in L12

Nello sviluppo di applicazioni con il framework PHP Laravel, uno degli anti-pattern più comuni in cui ci si può imbattere, specialmente in progetti Laravel 9 o Laravel 10 con una certa evoluzione storica o sviluppati rapidamente, è il cosiddetto "Controller Grasso" (Fat Controller). Questo si verifica quando i controller si assumono troppe responsabilità: non solo gestiscono le richieste HTTP e restituiscono risposte, ma contengono anche complessa logica di business, interazioni dirette e articolate con il database tramite Eloquent ORM, invio di notifiche, dispatch di eventi e altro ancora. Il risultato è un codice difficile da leggere, mantenere, testare e riutilizzare, che viola palesemente principi SOLID come il Single Responsibility Principle (SRP).

Per le imprese che mirano a costruire applicazioni Laravel 12 robuste, scalabili e manutenibili a lungo termine, è fondamentale adottare un'architettura più pulita. Questo articolo tecnico ti guiderà attraverso un processo di refactoring strategico, mostrando come trasformare i Fat Controller introducendo due design pattern fondamentali: il Service Layer (Strato dei Servizi) e il Repository Pattern. Esploreremo anche come i nuovi comandi make introdotti in Laravel 11 possano facilitare la creazione di queste strutture.

Stai cercando un programmatore PHP Laravel esperto e consolidato per implementare tecniche sicure e professionali di sviluppo e refactoring di vecchie applicazioni Legacy verso le più recenti versioni di Laravel 11 e Laravel 12? Contattami per una consulenza e scopri come posso aiutare la tua impresa a modernizzare le applicazioni. Affidarsi a un esperto è la chiave per garantire un passaggio fluido e sicuro, corroborato da anni di esperienza e una profonda conoscenza delle best practice di Laravel e della Ingegneria del Software.

Analisi di un Fat Controller: lo scenario comune in Laravel 9/10

Immaginiamo un OrderController in un'applicazione e-commerce Laravel 9/10 che gestisce la creazione di un nuovo ordine.

// app/Http/Controllers/LegacyOrderController.php (Esempio di Fat Controller L9/L10)
namespace App\Http\Controllers;

use App\Models\Order;
use App\Models\Product;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\DB; // Per transazioni
use Illuminate\Support\Facades\Log;
use App\Notifications\OrderPlacedNotification; // Ipotetica notifica
use Illuminate\Validation\ValidationException;

class LegacyOrderController extends Controller
{
    public function store(Request $request)
    {
        // 1. Validazione (spesso inline o in una FormRequest basilare)
        try {
            $validatedData = $request->validate([
                'user_id' => 'required|exists:users,id',
                'products' => 'required|array|min:1',
                'products.*.id' => 'required|exists:products,id',
                'products.*.quantity' => 'required|integer|min:1',
                'shipping_address' => 'required|string|max:255',
            ]);
        } catch (ValidationException $e) {
            return response()->json(['errors' => $e->errors()], 422);
        }

        $user = User::findOrFail($validatedData['user_id']);
        $totalAmount = 0;
        $orderItemsData = [];

        DB::beginTransaction(); // Inizio transazione

        try {
            // 2. Logica di business: calcolo totali, controllo disponibilità prodotti
            foreach ($validatedData['products'] as $productInput) {
                $product = Product::findOrFail($productInput['id']);

                if ($product->stock < $productInput['quantity']) {
                    throw new Exception("Prodotto {$product->name} non disponibile in quantità sufficiente.");
                }

                $itemPrice = $product->price * $productInput['quantity'];
                $totalAmount += $itemPrice;
                $orderItemsData[] = [
                    'product_id' => $product->id,
                    'quantity' => $productInput['quantity'],
                    'price_at_purchase' => $product->price, // Salva il prezzo al momento dell'acquisto
                ];

                // 3. Interazione diretta con Eloquent per aggiornare lo stock
                $product->decrement('stock', $productInput['quantity']);
            }

            // Ulteriore logica di business: applicare sconti, calcolare spedizione...
            // $shippingCost = $this->calculateShipping($validatedData['shipping_address'], $totalAmount);
            // $totalAmount += $shippingCost;

            // 4. Creazione dell'ordine e degli item (ancora interazione Eloquent)
            $order = Order::create([
                'user_id' => $user->id,
                'total_amount' => $totalAmount,
                'shipping_address' => $validatedData['shipping_address'],
                'status' => 'pending',
            ]);

            $order->items()->createMany($orderItemsData);

            // 5. Invio notifiche/eventi
            $user->notify(new OrderPlacedNotification($order));
            // event(new \App\Events\OrderWasSuccessfullyPlaced($order)); // Esempio

            DB::commit(); // Conferma transazione

            Log::info("Ordine #{$order->id} creato con successo per utente {$user->id}");

            return response()->json(['message' => 'Ordine creato con successo!', 'order_id' => $order->id], 201);

        } catch (Exception $e) {
            DB::rollBack(); // Annulla transazione in caso di errore
            Log::error("Errore durante la creazione dell'ordine: " . $e->getMessage());
            return response()->json(['error' => 'Impossibile creare l\'ordine: ' . $e->getMessage()], 500);
        }
    }

    // Altri metodi del controller potrebbero contenere logica simile...
}

Problemi evidenti di questo LegacyOrderController:

• Molteplici responsabilità: gestisce la validazione, il calcolo dei totali, l'aggiornamento dello stock, la creazione di record nel database, l'invio di notifiche. Troppe per un controller.
• Difficile da testare unitariamente: per testare la logica di calcolo del totale o l'aggiornamento dello stock, devi simulare una richiesta HTTP completa o mockare molte dipendenze di Laravel.
• Scarsa riutilizzabilità: se la logica di creazione ordine o di aggiornamento stock serve altrove (es. un comando Artisan, un job in coda), devi duplicare il codice o fare un refactoring complesso.
• Accoppiamento stretto con Eloquent: il controller è intimamente legato ai Model Eloquent e alla struttura del database. Qualsiasi modifica allo schema o all'ORM potrebbe richiedere modifiche al controller.
• Leggibilità compromessa: il metodo store è lungo e fa troppe cose.

Il refactoring verso un'architettura pulita in Laravel 12: Service Layer e Repository Pattern

Per risolvere questi problemi, introduciamo due pattern architetturali: il Repository Pattern per l'accesso ai dati e il Service Layer per la logica di business.

1. Il Repository Pattern: astrarre l'accesso ai dati

Il Repository Pattern media tra il dominio dell'applicazione e i meccanismi di mappatura dei dati (nel nostro caso, Eloquent). Fornisce una collezione di metodi orientati agli oggetti per accedere ai dati, nascondendo i dettagli dell'implementazione della persistenza.

A. Creare l'Interfaccia del Repository Definiamo un contratto per come interagiremo con i dati dei prodotti e degli ordini. Laravel 11+ facilita la creazione di interfacce con php artisan make:interface Repositories/Contracts/OrderRepositoryInterface.

// app/Repositories/Contracts/OrderRepositoryInterface.php
namespace App\Repositories\Contracts;

use App\Models\Order;
use App\Models\User;

interface OrderRepositoryInterface
{
    public function create(User $user, array $orderData, array $itemsData, float $totalAmount): Order;
    public function findById(int|string $id): ?Order;
    // Altri metodi come: updateStatus, findByUser, etc.
}

// app/Repositories/Contracts/ProductRepositoryInterface.php
namespace App\Repositories\Contracts;

use App\Models\Product;
interface ProductRepositoryInterface
{
    public function findOrFail(int|string $id): Product;
    public function decrementStock(Product $product, int $quantity): bool;
    // ...
}

B. Creare l'Implementazione Eloquent del Repository Questa classe implementerà l'interfaccia usando Eloquent.

// app/Repositories/Eloquent/EloquentOrderRepository.php
namespace App\Repositories\Eloquent;

use App\Models\Order;
use App\Models\User;
use App\Repositories\Contracts\OrderRepositoryInterface;

class EloquentOrderRepository implements OrderRepositoryInterface
{
    public function create(User $user, array $orderData, array $itemsData, float $totalAmount): Order
    {
        $order = $user->orders()->create([
            'total_amount' => $totalAmount,
            'shipping_address' => $orderData['shipping_address'],
            'status' => 'pending', // Status iniziale
        ]);
        $order->items()->createMany($itemsData);
        return $order;
    }

    public function findById(int|string $id): ?Order
    {
        return Order::with('items', 'user')->find($id); // Esempio con eager loading
    }
}

// app/Repositories/Eloquent/EloquentProductRepository.php
namespace App\Repositories\Eloquent;

use App\Models\Product;
use App\Repositories\Contracts\ProductRepositoryInterface;
class EloquentProductRepository implements ProductRepositoryInterface
{
    public function findOrFail(int|string $id): Product
    {
        return Product::findOrFail($id);
    }

    public function decrementStock(Product $product, int $quantity): bool
    {
        if ($product->stock < $quantity) {
            return false; // Non sufficiente stock
        }
        return $product->decrement('stock', $quantity);
    }
}

C. Binding nel Service Provider Registriamo le nostre implementazioni nel Service Container, preferibilmente in un RepositoryServiceProvider dedicato (creabile con php artisan make:provider RepositoryServiceProvider e poi registrato in config/app.php o in bootstrap/app.php per Laravel 11+).

// app/Providers/RepositoryServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Repositories\Contracts\OrderRepositoryInterface;
use App\Repositories\Eloquent\EloquentOrderRepository;
use App\Repositories\Contracts\ProductRepositoryInterface;
use App\Repositories\Eloquent\EloquentProductRepository;

class RepositoryServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(OrderRepositoryInterface::class, EloquentOrderRepository::class);
        $this->app->bind(ProductRepositoryInterface::class, EloquentProductRepository::class);
        // ... altri binding per repository ...
    }
}

2. Il Service Layer: incapsulare la logica di business

Il Service Layer si frappone tra i controller e i repository (o altri servizi). Contiene la logica di business pura, orchestrando le operazioni e utilizzando i repository per l'accesso ai dati. Laravel 11+ facilita la creazione di classi generiche con php artisan make:class Services/OrderProcessingService.

// app/Services/OrderProcessingService.php
namespace App\Services;

use App\Repositories\Contracts\OrderRepositoryInterface;
use App\Repositories\Contracts\ProductRepositoryInterface;
use App\Models\User;
use App\Models\Product; // Per type-hinting se necessario
use App\Notifications\OrderPlacedNotification;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Exception; // Per l'eccezione custom o generica

class OrderProcessingService
{
    protected ProductRepositoryInterface $productRepository;
    protected OrderRepositoryInterface $orderRepository;
    // Potremmo iniettare anche un NotificationService, EventDispatcher, etc.

    public function __construct(
        ProductRepositoryInterface $productRepository,
        OrderRepositoryInterface $orderRepository
    ) {
        $this->productRepository = $productRepository;
        $this->orderRepository = $orderRepository;
    }

    /**
     * Processa la creazione di un nuovo ordine.
     * @param User $user
     * @param array $validatedOrderData (include 'products' e 'shipping_address')
     * @return \App\Models\Order
     * @throws Exception (o eccezioni più specifiche)
     */
    public function placeOrder(User $user, array $validatedOrderData): \App\Models\Order
    {
        return DB::transaction(function () use ($user, $validatedOrderData) {
            $totalAmount = 0;
            $orderItemsData = [];

            foreach ($validatedOrderData['products'] as $productInput) {
                $product = $this->productRepository->findOrFail($productInput['id']);

                if (!$this->productRepository->decrementStock($product, $productInput['quantity'])) {
                    throw new Exception("Prodotto {$product->name} non disponibile in quantità sufficiente.");
                }

                $itemPrice = $product->price * $productInput['quantity']; // Assumendo che product->price sia il prezzo unitario
                $totalAmount += $itemPrice;
                $orderItemsData[] = [
                    'product_id' => $product->id,
                    'quantity' => $productInput['quantity'],
                    'price_at_purchase' => $product->price,
                ];
            }

            // Logica di sconti, spedizione, etc., potrebbe essere in altri metodi o servizi
            // $totalAmount = $this->applyDiscounts($totalAmount, $user);
            // $totalAmount += $this->calculateShipping($validatedOrderData['shipping_address'], $totalAmount);

            $order = $this->orderRepository->create($user, $validatedData['order_details_for_repo'] ?? $validatedOrderData, $orderItemsData, $totalAmount);

            $user->notify(new OrderPlacedNotification($order));
            // event(new \App\Events\OrderWasSuccessfullyPlaced($order));

            Log::info("Servizio Ordini: Ordine #{$order->id} creato con successo per utente {$user->id}");
            return $order;
        });
    }

    // Altri metodi di business: cancelOrder, updateOrderStatus, applyDiscounts...
}

Nota sulla Validazione: La validazione dei dati in input dovrebbe avvenire prima di chiamare il servizio, tipicamente tramite una FormRequest nel controller. Il servizio riceve dati già validati. Una gestione pulita della logica di business si accompagna spesso a una gestione della validazione altrettanto robusta e disaccoppiata, come quella ottenibile con i Rule Objects.

Il Controller Refactorato: snello e focalizzato

Con Service Layer e Repository al loro posto, il nostro OrderController diventa molto più semplice:

// app/Http/Controllers/OrderController.php (Laravel 12 style - refactorato)
namespace App\Http\Controllers;

use App\Services\OrderProcessingService;
use App\Http\Requests\StoreOrderRequest; // Nuova FormRequest per validazione
use App\Http\Resources\OrderResource;   // Per formattare la risposta API
use Illuminate\Http\JsonResponse;
use Illuminate\Support\Facades\Auth;    // Per ottenere l'utente autenticato
use Illuminate\Support\Facades\Log;

class OrderController extends Controller
{
    protected OrderProcessingService $orderService;

    public function __construct(OrderProcessingService $orderService)
    {
        $this->orderService = $orderService;
        // $this->middleware('auth:api'); // Esempio di middleware
    }

    /**
     * Crea un nuovo ordine.
     */
    public function store(StoreOrderRequest $request): JsonResponse // Usa la FormRequest per la validazione
    {
        try {
            $user = Auth::user(); // O $request->user() se si usa Sanctum/Passport
            if (!$user) {
                return response()->json(['error' => 'Utente non autenticato.'], 401);
            }

            // La $request->validated() contiene i dati già validati dalla FormRequest
            $order = $this->orderService->placeOrder($user, $request->validated());

            return (new OrderResource($order))
                        ->response()
                        ->setStatusCode(201); // HTTP 201 Created

        } catch (\Illuminate\Validation\ValidationException $e) {
            // Questo è gestito automaticamente dalla FormRequest, ma per completezza se non la usassi
            return response()->json(['errors' => $e->errors()], 422);
        } catch (\App\Exceptions\ProductOutOfStockException $e) { // Esempio eccezione custom dal service
            Log::warning("Tentativo creazione ordine fallito: " . $e->getMessage());
            return response()->json(['error' => $e->getMessage()], 409); // Conflict
        } catch (\Exception $e) {
            Log::error("Errore critico durante la creazione dell'ordine: " . $e->getMessage());
            return response()->json(['error' => 'Si è verificato un errore imprevisto durante la creazione dell\'ordine.'], 500);
        }
    }

    public function show(string $orderId): JsonResponse // Potrebbe usare Route Model Binding per $order
    {
        // Esempio: recuperare un ordine tramite il servizio (che usa il repository)
        // $order = $this->orderService->getOrderDetails($orderId);
        // if (!$order) {
        //     return response()->json(['error' => 'Ordine non trovato'], 404);
        // }
        // return (new OrderResource($order))->response();
        // Per questo esempio, lasceremo questo metodo semplice
        $order = \App\Models\Order::with('items', 'user')->find($orderId); // Uso diretto per semplicità qui
        if (!$order) return response()->json(['error' => 'Ordine non trovato'], 404);
        return (new OrderResource($order))->response();

    }
}

Testare l'architettura a Layer

Questa architettura è molto più testabile:

• Repository: puoi testare i metodi del tuo EloquentProductRepository usando un database di test in memoria (RefreshDatabase trait) per verificare che le query Eloquent siano corrette.

• Service: puoi testare la logica di business del tuo OrderProcessingService mockando le interfacce dei repository. In questo modo, testi la logica del servizio in isolamento, senza toccare il database.

    // tests/Unit/Services/OrderProcessingServiceTest.php
    use App\Services\OrderProcessingService;
    use App\Repositories\Contracts\OrderRepositoryInterface;
    use App\Repositories\Contracts\ProductRepositoryInterface;
    use App\Models\User;
    use App\Models\Product;
    use App\Models\Order;
    use App\Notifications\OrderPlacedNotification;
    use Illuminate\Support\Facades\Notification;
    use Illuminate\Support\Facades\DB; // Per mockare la transazione
    use Mockery;
    use Tests\TestCase;
  
    class OrderProcessingServiceTest extends TestCase
    {
        public function test_place_order_successfully(): void
        {
            $user = User::factory()->make(['id' => 1]); // Non salvato, solo per il test
            $product1 = Product::factory()->make(['id' => 10, 'price' => 100, 'stock' => 5]);
            
            $validatedData = [
                'products' => [['id' => 10, 'quantity' => 2]],
                'shipping_address' => 'Via Roma 1, 00100 Roma',
            ];
  
            // Mock dei Repository
            $productRepoMock = Mockery::mock(ProductRepositoryInterface::class);
            $productRepoMock->shouldReceive('findOrFail')->with(10)->once()->andReturn($product1);
            $productRepoMock->shouldReceive('decrementStock')->with($product1, 2)->once()->andReturn(true);
  
            $orderRepoMock = Mockery::mock(OrderRepositoryInterface::class);
            $orderRepoMock->shouldReceive('create')
                ->once()
                // Verifica che i dati passati per la creazione dell'ordine siano corretti
                ->with(
                    $user,
                    Mockery::on(function($orderPassedData) use ($validatedData) {
                        return $orderPassedData['shipping_address'] === $validatedData['shipping_address'];
                    }),
                    Mockery::type('array'), // itemsData
                    200.00 // totalAmount (100 * 2)
                )
                ->andReturn(Order::factory()->make(['id' => 1, 'user_id' => $user->id, 'total_amount' => 200.00]));
  
            // Mock per DB::transaction()
            DB::shouldReceive('transaction')->once()->andReturnUsing(function ($callback) {
                return $callback(); // Esegui la closure passata a transaction
            });
  
            Notification::fake(); // Fai il fake delle notifiche
  
            $service = new OrderProcessingService($productRepoMock, $orderRepoMock);
            $order = $service->placeOrder($user, $validatedData);
  
            $this->assertInstanceOf(Order::class, $order);
            $this->assertEquals(200.00, $order->total_amount);
            Notification::assertSentTo($user, OrderPlacedNotification::class, function ($notification) use ($order) {
                return $notification->order->id === $order->id;
            });
        }
    }

• Controller: puoi effettuare feature test (HTTP test) mockando il Service Layer per isolare il controller e verificare che gestisca correttamente la richiesta/risposta, oppure testare l'integrazione fino al servizio (o anche fino al database se necessario).

Benefici del Refactoring per le Applicazioni Aziendali

L'adozione di Service Layer e Repository Pattern porta a:

• Separazione delle Responsabilità (SoC): Ogni componente (controller, service, repository) ha un compito ben definito.
• Migliore Testabilità: Ogni layer può essere testato in isolamento, portando a test più veloci, affidabili e unitari.
• Maggiore Riutilizzabilità: La logica di business nei servizi e l'accesso ai dati nei repository possono essere facilmente riutilizzati da diversi controller, comandi Artisan, job in coda, ecc.
• Manutenibilità Semplificata: Le modifiche a un layer (es. cambiare la logica di business o l'ORM) hanno un impatto minore sugli altri layer.
• Flessibilità: Ad esempio, è teoricamente più facile cambiare l'ORM sottostante (da Eloquent a qualcos'altro) modificando solo l'implementazione del repository, senza toccare il Service Layer o i controller.

Il ruolo del programmatore Laravel esperto

Ristrutturare un'applicazione Laravel "grassa" per implementare correttamente questi pattern richiede una solida comprensione dei principi di architettura software, dei design pattern e delle sfumature di Laravel. Come sviluppatore Laravel con una vasta esperienza nella progettazione di architetture complesse e nel refactoring di codice legacy (puoi trovare maggiori dettagli sul mio approccio nella pagina Chi Sono), posso aiutare la tua impresa a:

• Analizzare l'architettura esistente e identificare i Fat Controller.
• Progettare e implementare Service Layer e Repository su misura per le esigenze del tuo business.
• Guidare il processo di refactoring in modo incrementale e sicuro.
• Scrivere test efficaci per garantire la qualità e prevenire regressioni.

Un'architettura pulita non è un lusso accademico, ma un fondamento essenziale per la crescita, la stabilità e l'evoluzione a lungo termine delle applicazioni della tua impresa. È un investimento che ripaga in termini di efficienza di sviluppo e robustezza del software.

Se i controller della tua applicazione Laravel 9/10 stanno diventando ingestibili e vuoi modernizzare la tua architettura in vista di Laravel 12, contattami per una consulenza approfondita. Insieme, possiamo snellire il tuo codice e renderlo pronto per il futuro.