حذف بدهی معماری: پیاده‌سازی اصول SOLID و الگوهای Repository در PHP و Laravel مدرن

کنترلر Laravel معمولی (سال ۳):
  ┌─────────────────────────────────────────────────────────┐
  │  class OrderController                                  │
  │  {                                                      │
  │      public function store(Request $request)            │
  │      {                                                  │
  │          // اعتبارسنجی (باید جدا باشد)                  │
  │          // منطق کسب‌وکار (باید در دامنه باشد)          │
  │          // پرس‌وجوهای پایگاه داده (باید در Repository) │
  │          // ارسال ایمیل (باید در Service باشد)          │
  │          // پردازش پرداخت (باید در Service باشد)        │
  │          // Logging (باید فرابخشی باشد)                 │
  │          // قالب‌بندی پاسخ (باید در Resource باشد)      │
  │      }                                                  │
  │  }                                                      │
  └─────────────────────────────────────────────────────────┘

App/
├── Http/
│   ├── Controllers/      ← فقط پردازش HTTP
│   ├── Requests/         ← فقط اعتبارسنجی
│   └── Resources/        ← فقط قالب‌بندی پاسخ
├── Actions/              ← عملیات کسب‌وکار واحد
├── Services/             ← منطق کسب‌وکار چندمرحله‌ای
├── Repositories/         ← فقط دسترسی داده
└── Models/               ← فقط Entityهای Eloquent

// قبل: کنترلر همه کار را انجام می‌دهد
class OrderController {
    public function store(Request $request) {
        $validated = $request->validate([...]);
        $order = Order::create($validated);
        Mail::to($order->customer)->send(new OrderConfirmation($order));
        return new OrderResource($order);
    }
}

// بعد: تک مسئولیت به ازای هر کلاس
class OrderController {
    public function store(StoreOrderRequest $request, CreateOrderAction $action) {
        $order = $action->execute($request->validated());
        return new OrderResource($order);
    }
}

class CreateOrderAction {
    public function __construct(
        private OrderRepository $orders,
        private OrderConfirmationMailer $mailer
    ) {}
    
    public function execute(array $data): Order {
        $order = $this->orders->create($data);
        $this->mailer->send($order);
        return $order;
    }
}

interface PaymentGateway {
    public function charge(Order $order): PaymentResult;
}

class StripeGateway implements PaymentGateway { ... }
class PayPalGateway implements PaymentGateway { ... }
class CryptoGateway implements PaymentGateway { ... }

// افزودن Gateway جدید = افزودن کلاس، نه تغییر کد موجود

interface UserRepository {
    public function find(int $id): ?User;  // باید null برگرداند، هرگز Exception ندهد
}

class EloquentUserRepository implements UserRepository { ... }
class CachedUserRepository implements UserRepository { ... }

// قبل: Interface چاق
interface RepositoryInterface {
    public function all();
    public function find($id);
    public function create(array $data);
    public function update($id, array $data);
    public function delete($id);
    public function paginate($perPage);
    public function search($query);
    // ... ۲۰ متد دیگر
}

// بعد: Interfaceهای تفکیک‌شده
interface ReadableRepository {
    public function find(int $id): ?Model;
    public function findBy(array $criteria): Collection;
}

interface WritableRepository {
    public function create(array $data): Model;
    public function update(int $id, array $data): Model;
    public function delete(int $id): bool;
}

// قبل: وابستگی مستقیم
class OrderService {
    public function create(array $data) {
        return Order::create($data);  // محکم به Eloquent جفت‌شده
    }
}

// بعد: وابستگی معکوس‌شده
class OrderService {
    public function __construct(
        private OrderRepository $orders  // Interface، نه Eloquent
    ) {}
    
    public function create(array $data) {
        return $this->orders->create($data);
    }
}

// Bind در Service Provider
$this->app->bind(OrderRepository::class, EloquentOrderRepository::class);

App/
├── Contracts/
│   └── Repositories/
│       └── OrderRepositoryInterface.php
├── Repositories/
│   └── EloquentOrderRepository.php
└── Providers/
    └── RepositoryServiceProvider.php

namespace App\Contracts\Repositories;

interface OrderRepositoryInterface
{
    public function find(int $id): ?Order;
    public function findByCustomer(int $customerId): Collection;
    public function create(array $data): Order;
    public function update(int $id, array $data): Order;
    public function delete(int $id): bool;
    public function paginate(int $perPage = 15): LengthAwarePaginator;
}

namespace App\Repositories;

use App\Contracts\Repositories\OrderRepositoryInterface;

class EloquentOrderRepository implements OrderRepositoryInterface
{
    public function __construct(
        private Order $model
    ) {}
    
    public function find(int $id): ?Order
    {
        return $this->model->find($id);
    }
    
    public function findByCustomer(int $customerId): Collection
    {
        return $this->model->where('customer_id', $customerId)
            ->orderBy('created_at', 'desc')
            ->get();
    }
    
    public function create(array $data): Order
    {
        return $this->model->create($data);
    }
    
    public function paginate(int $perPage = 15): LengthAwarePaginator
    {
        return $this->model->paginate($perPage);
    }
}

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\Repositories\OrderRepositoryInterface;
use App\Repositories\EloquentOrderRepository;

class RepositoryServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(
            OrderRepositoryInterface::class,
            EloquentOrderRepository::class
        );
    }
}

class CreateOrderAction
{
    public function __construct(
        private OrderRepositoryInterface $orders,
        private PaymentGateway $payment,
        private OrderConfirmationMailer $mailer
    ) {}
    
    public function execute(array $data): Order
    {
        $order = $this->orders->create($data);
        $this->payment->charge($order);
        $this->mailer->send($order);
        return $order;
    }
}

// app/Providers/AppServiceProvider.php
public function register(): void
{
    $this->app->bind(OrderRepositoryInterface::class, EloquentOrderRepository::class);
    $this->app->bind(PaymentGateway::class, StripeGateway::class);
    $this->app->singleton(OrderConfirmationMailer::class);
}

$this->app->when(AdminOrderService::class)
    ->needs(OrderRepositoryInterface::class)
    ->give(AdminOrderRepository::class);

$this->app->when(CustomerOrderService::class)
    ->needs(OrderRepositoryInterface::class)
    ->give(CustomerOrderRepository::class);

        ┌─────────────┐
        │   E2E /     │  ← کم: HTTP + DB + خارجی کامل
        │   Feature   │
        ├─────────────┤
        │ Integration │  ← برخی: Repository + DB
        ├─────────────┤
        │    Unit     │  ← بسیاری: Actionها، Serviceها، منطق دامنه
        └─────────────┘

class CreateOrderActionTest extends TestCase
{
    public function test_it_creates_order_and_sends_confirmation(): void
    {
        // Arrange
        $order = new Order(['id' => 1]);
        
        $orders = $this->createMock(OrderRepositoryInterface::class);
        $orders->expects($this->once())
            ->method('create')
            ->willReturn($order);
        
        $payment = $this->createMock(PaymentGateway::class);
        $payment->expects($this->once())
            ->method('charge')
            ->with($order);
        
        $mailer = $this->createMock(OrderConfirmationMailer::class);
        $mailer->expects($this->once())
            ->method('send')
            ->with($order);
        
        $action = new CreateOrderAction($orders, $payment, $mailer);
        
        // Act
        $result = $action->execute(['customer_id' => 42]);
        
        // Assert
        $this->assertSame($order, $result);
    }
}

class OrderControllerTest extends TestCase
{
    use RefreshDatabase;
    
    public function test_it_creates_order_via_api(): void
    {
        $this->postJson('/api/orders', [
            'customer_id' => 42,
            'items' => [['sku' => 'ABC', 'qty' => 2]]
        ])
        ->assertStatus(201)
        ->assertJsonStructure(['id', 'customer_id', 'total']);
        
        $this->assertDatabaseHas('orders', ['customer_id' => 42]);
    }
}

class EloquentOrderRepositoryTest extends TestCase
{
    use RefreshDatabase;
    
    public function test_it_finds_orders_by_customer(): void
    {
        Order::factory()->count(3)->create(['customer_id' => 42]);
        Order::factory()->create(['customer_id' => 99]);
        
        $repo = new EloquentOrderRepository(new Order());
        $results = $repo->findByCustomer(42);
        
        $this->assertCount(3, $results);
    }
}

┌─────────────────────────────────────────────────────────────────────────────┐
│                         لایه HTTP                                           │
│  کنترلرها (نازک) │ Form Requestها (اعتبارسنجی) │ Resourceها (پاسخ)         │
├─────────────────────────────────────────────────────────────────────────────┤
│                         لایه اپلیکیشن                                       │
│  Actionها (عملیات واحد) │ Serviceها (جریان‌های چندمرحله‌ای)                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                         لایه دامنه                                          │
│  Interfaceها (قراردادها) │ Value Objectها │ Domain Eventها                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                         لایه زیرساخت                                        │
│  Repositoryها (دسترسی داده) │ سرویس‌های خارجی │ Mailerها │ Payment          │
├─────────────────────────────────────────────────────────────────────────────┤
│                         لایه فریم‌ورک                                       │
│  Laravel │ Eloquent │ Service Container │ Queue │ Cache                     │
└─────────────────────────────────────────────────────────────────────────────┘