DEV Community: Anas Hussain

High Cohesion, Low Coupling: The Foundation of Good Object Design

Anas Hussain — Thu, 30 Jul 2026 16:44:35 +0000

1. Hook & Problem Statement

You've inherited a Laravel project. It's a mess. Making a change to one part of the codebase breaks three other parts. Adding a new feature feels like performing surgery on a living patient. You're terrified to touch anything.

You open a class. It's 2,000 lines long. It does everything: validates data, sends emails, processes payments, generates reports, and connects to the database. It has 45 dependencies. Changing one method requires understanding the entire class.

This isn't just bad code. This is a design problem. And the two metrics that reveal the problem are cohesion and coupling.

Every developer has worked on a codebase like this. We call it "spaghetti code" or a "big ball of mud." But the technical terms are much more precise:

Low Cohesion: A class does too many unrelated things.
High Coupling: A class knows too much about other classes.

When cohesion is low and coupling is high, your codebase is rigid, fragile, and hard to maintain. It's a system designed to fail.

Cohesion and coupling are the vital signs of your codebase. They tell you if your software is healthy or dying.

2. Why This Pattern/Concept Exists

The Software Engineering Problem It Solves

Cohesion and coupling are metrics that help you evaluate the quality of your object design. They answer two fundamental questions:

Cohesion: How well do the elements inside a module (class, method, package) belong together?
Coupling: How much does a module depend on other modules?

Large applications eventually fail if cohesion is low and coupling is high because:

Changes are expensive: Changing one class requires changing many others.
Testing is difficult: You can't test a class without its dependencies.
Understanding is hard: You need to understand the entire system to understand one part.
Reuse is impossible: You can't reuse a class without bringing its baggage.

The Pain That Existed Before

Before developers understood cohesion and coupling (and in codebases that ignore them):

God Classes: Single classes that do everything (low cohesion).
Ripple Effects: Changing one class caused a cascade of changes (high coupling).
Fragile Codebases: Tests broke for seemingly unrelated reasons.
Fear of Change: Developers were afraid to touch code.
Abandoned Projects: Codebases were rewritten because they were "too hard to maintain."

Why Large Applications Need It

As applications scale, the cost of poor design compounds. A 100-line class with low cohesion might be manageable. A 10,000-line class with low cohesion is impossible.

The core insight: Modular design isn't just about separating code. It's about managing dependencies. High cohesion and low coupling are the characteristics of well-structured software. They're the difference between a system that's easy to evolve and one that collapses under its own weight.

3. Real World Analogy

The Restaurant Kitchen

Imagine a restaurant kitchen.

Low Cohesion:
One chef does everything: takes orders, cooks, washes dishes, manages inventory, and balances the books. This chef is a "God Object." They're overwhelmed. If they're sick, the entire restaurant stops.

High Coupling:
The kitchen is tightly connected. The oven's temperature is controlled by the same system as the dishwasher. The sous chef can't prep vegetables without knowing what the line cook is doing. Everything is interdependent. Changing one thing breaks everything else.

High Cohesion:
The kitchen is organized into stations:

Prep chef: Prepares ingredients.
Line cook: Cooks the food.
Saucier: Makes sauces.
Pastry chef: Makes desserts.
Dishwasher: Washes dishes.
Manager: Handles inventory and ordering.

Each station has a clear, focused responsibility. They don't overlap.

Low Coupling:
The stations are loosely connected through defined interfaces:

The prep chef preps ingredients and puts them in a labeled container (interface).
The line cook takes ingredients from the container (interface).
They don't need to know how the prep chef works. They just need the prepared ingredients.

When the restaurant is busy, they can swap stations without chaos. When one station is slow, it doesn't block the others.

Analogy Mapping:

Kitchen Station: A class (focus on one responsibility).
Chef's Specific Role: Methods that implement that responsibility.
Labeled Container: Interface (standardized communication).
Order System: The application flow.
Inventory Manager: Configuration or service provider.

4. The Pain (Bad Design)

Let's look at a typical "God Class" in a Laravel application.

namespace App\Services;

use App\Models\Order;
use App\Models\User;
use App\Models\Product;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Queue;
use Stripe\StripeClient;
use Twilio\Rest\Client;

class OrderService
{
    private StripeClient $stripe;
    private Client $twilio;
    private array $config;

    public function __construct()
    {
        $this->stripe = new StripeClient(config('services.stripe.secret'));
        $this->twilio = new Client(
            config('services.twilio.sid'),
            config('services.twilio.token')
        );
        $this->config = config('order');
    }

    // 1. Handles order creation
    public function createOrder(array $data): Order
    {
        // Validate data
        if (!isset($data['user_id']) || !isset($data['items'])) {
            throw new \Exception('Invalid order data');
        }

        // Check product availability
        $total = 0;
        foreach ($data['items'] as $item) {
            $product = Product::find($item['product_id']);
            if (!$product || $product->stock < $item['quantity']) {
                throw new \Exception("Product unavailable: {$item['product_id']}");
            }

            $total += $product->price * $item['quantity'];

            // Update stock
            $product->stock -= $item['quantity'];
            $product->save();
        }

        // Create order
        $order = new Order();
        $order->user_id = $data['user_id'];
        $order->items = json_encode($data['items']);
        $order->total = $total;
        $order->status = 'pending';
        $order->save();

        // Send confirmation email
        $user = User::find($data['user_id']);
        Mail::to($user->email)->send(new OrderConfirmation($order));

        // Send SMS
        if ($user->phone) {
            $this->twilio->messages->create(
                $user->phone,
                [
                    'from' => config('services.twilio.from'),
                    'body' => "Order #{$order->id} created!"
                ]
            );
        }

        // Log
        Log::info('Order created', ['order_id' => $order->id]);

        return $order;
    }

    // 2. Handles payment processing
    public function processPayment(Order $order): array
    {
        if ($order->status !== 'pending') {
            throw new \Exception('Order cannot be paid');
        }

        // Use Stripe
        $intent = $this->stripe->paymentIntents->create([
            'amount' => $order->total * 100,
            'currency' => 'usd',
            'payment_method_types' => ['card'],
        ]);

        $order->payment_intent_id = $intent->id;
        $order->save();

        Log::info('Payment initiated', ['order' => $order->id]);

        return ['client_secret' => $intent->client_secret];
    }

    // 3. Handles order fulfillment
    public function fulfillOrder(Order $order): void
    {
        if ($order->status !== 'paid') {
            throw new \Exception('Order must be paid to fulfill');
        }

        $items = json_decode($order->items, true);

        foreach ($items as $item) {
            // Prepare shipping labels
            $this->generateShippingLabel($item, $order);
        }

        $order->status = 'shipped';
        $order->save();

        // Update inventory in cache
        Cache::put("order_{$order->id}_shipped", true, 3600);

        // Queue follow-up email
        Queue::push(new SendFollowUpEmail($order));

        Log::info('Order fulfilled', ['order' => $order->id]);
    }

    // 4. Handles returns
    public function processReturn(Order $order, array $items): void
    {
        if ($order->status !== 'shipped') {
            throw new \Exception('Order must be shipped to return');
        }

        $returnedItems = [];
        $refundAmount = 0;

        $orderItems = json_decode($order->items, true);

        foreach ($items as $returnItem) {
            foreach ($orderItems as &$orderItem) {
                if ($orderItem['product_id'] === $returnItem['product_id']) {
                    $orderItem['returned'] = true;
                    $product = Product::find($returnItem['product_id']);
                    $refundAmount += $product->price * $returnItem['quantity'];
                    $returnedItems[] = $returnItem;
                }
            }
        }

        // Process refund
        $this->stripe->refunds->create([
            'payment_intent' => $order->payment_intent_id,
            'amount' => $refundAmount * 100,
        ]);

        // Update order
        $order->items = json_encode($orderItems);
        $order->status = 'returned';
        $order->save();

        // Send return confirmation
        Mail::to($order->user->email)->send(new ReturnConfirmation($order, $returnedItems));

        Log::info('Return processed', ['order' => $order->id]);
    }

    // 5. Generates shipping labels
    private function generateShippingLabel(array $item, Order $order): void
    {
        // 30 lines of shipping label logic
        // Connects to shipping API
    }

    // 6. Handles notifications
    public function sendStatusUpdate(Order $order): void
    {
        // Send email and SMS based on status
        $user = $order->user;

        Mail::to($user->email)->send(new OrderStatusUpdate($order));

        if ($user->phone) {
            $this->twilio->messages->create(
                $user->phone,
                [
                    'from' => config('services.twilio.from'),
                    'body' => "Order #{$order->id} status: {$order->status}",
                ]
            );
        }
    }

    // 7. Generates reports
    public function generateReport(string $type, array $filters): array
    {
        // 50 lines of report generation
        // Different logic for each report type
        return [];
    }

    // 8. Handles inventory management
    public function getInventory(): array
    {
        // 30 lines of inventory logic
        return [];
    }

    public function updateInventory(int $productId, int $quantity): void
    {
        // 20 lines of inventory update
    }

    // 9. Handles customer management
    public function getCustomerOrders(int $userId): array
    {
        // 10 lines
        return [];
    }

    public function updateCustomerProfile(int $userId, array $data): void
    {
        // 20 lines
    }
}

Why This Is Terrible

Low Cohesion:
- The class handles order creation, payments, fulfillment, returns, shipping labels, notifications, reports, inventory, and customers.
- 7+ unrelated responsibilities in one class.
High Coupling:
- The class knows about Stripe, Twilio, Mail, Log, Cache, Queue, DB.
- It's tightly coupled to concrete implementations.
- It uses facades directly (hidden dependencies).
Difficult Testing:
- To test createOrder(), you need Stripe, Twilio, Mail, DB, and Product models.
- You're testing a thousand lines of code for one method.
Difficult Change:
- Want to switch from Twilio to Vonage? Change everything.
- Want to change the notification flow? Find all the places.
Violates SOLID:
- SRP: Violated massively (7+ responsibilities).
- OCP: Adding a new feature requires modifying this giant class.
- DIP: Depends on concretions, not abstractions.
- ISP: Users of this class get all methods, even if they only need one.

Why Developers Write Code Like This

We write code like this because:

It's fast to prototype.
We think "it's just one class."
We don't recognize the warning signs.
We haven't internalized SRP.
The class "works" so we don't refactor.

5. Solution Overview

Cohesion measures how well the elements inside a module (class, method, package) belong together. High cohesion means all elements work together toward a single purpose. Low cohesion means elements are unrelated.

Coupling measures how much a module depends on other modules. Low coupling means modules are independent. High coupling means modules are dependent on each other.

Core Idea

High Cohesion: A class should do one thing and do it well. All methods should contribute to a single responsibility.
Low Coupling: A class should have minimal dependencies on other classes. Dependencies should be through interfaces.

Main Participants

High Cohesion:
- Each class has one clear responsibility.
- Methods within the class all support that responsibility.
- The class is focused and understandable.
Low Coupling:
- Classes depend on abstractions (interfaces), not concretions.
- Changes to one class don't require changes to others.
- Dependencies are injected, not created internally.

How Objects Collaborate

High Cohesion (Each class has one job):
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│OrderService │    │PaymentService│    │Notification │
│(Create/     │    │(Process     │    │Service      │
│ Fulfill     │───▶│ Payments,   │───▶│(Send Emails,│
│ Orders)     │    │ Refunds)    │    │ SMS, Slack) │
└─────────────┘    └─────────────┘    └─────────────┘
        │                  │                  │
        ▼                  ▼                  ▼
┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│Inventory    │    │PaymentGateway│    │MessageQueue │
│Service      │    │Interface    │    │Interface    │
└─────────────┘    └─────────────┘    └─────────────┘

Low Coupling (Each class depends on interfaces):

OrderService
    ↓ (depends on)
PaymentGatewayInterface
    ↑ (implemented by)
StripeGateway  │  PayPalGateway  (swap implementations)

Mental Model

Think of a well-organized toolbox.

High Cohesion: Each tool has one job. A hammer doesn't also function as a screwdriver. A wrench doesn't cut wood. Each tool is specialized.
Low Coupling: Tools are stored in separate slots. You can remove one tool without affecting the others. The hammer doesn't need to know about the wrench.
Low Cohesion + High Coupling: A multitool with everything built in. If you break the scissors, the whole tool is compromised. To add a new tool, you must redesign the entire multitool.

Benefits

Maintainability: Changes are localized to specific classes.
Testability: Test each class independently.
Readability: Classes are small and focused.
Reusability: Classes can be reused in different contexts.
Scalability: Teams can work on different classes simultaneously.

Trade-offs

More Classes: High cohesion means more classes.
More Files: Each class gets its own file.
More Dependencies: Classes need to be wired together.
Learning Curve: Developers need to understand the architecture.

6. UML Diagram

Laravel Cohesion and Coupling Mermaid Diagram

Diagram Explanation

High Cohesion: Each service has a single responsibility.
Low Coupling: OrderService depends on interfaces, not concretions.
Replaceable Components: StripeGateway and PayPalGateway can be swapped.
Clear Dependencies: Each class declares what it needs.

7. Vanilla PHP Example

Let's refactor the OrderService using high cohesion and low coupling.

Before Refactoring (Low Cohesion, High Coupling)

(The terrible code shown above)

After Refactoring (High Cohesion, Low Coupling)

Step 1: Define Interfaces (Low Coupling)

interface PaymentGatewayInterface
{
    public function charge(float $amount, string $currency, string $paymentMethodId): array;
    public function refund(string $transactionId, float $amount): array;
    public function createPaymentIntent(float $amount, string $currency): array;
}

interface NotificationInterface
{
    public function send(User $user, string $message, string $channel): void;
    public function getAvailableChannels(): array;
}

interface InventoryInterface
{
    public function checkAvailability(int $productId, int $quantity): bool;
    public function reserveStock(int $productId, int $quantity): void;
    public function releaseStock(int $productId, int $quantity): void;
    public function getStock(int $productId): int;
}

interface OrderRepositoryInterface
{
    public function save(Order $order): void;
    public function find(int $id): ?Order;
    public function findByUser(int $userId): array;
}

Step 2: Implement Services (High Cohesion)

// 1. Payment Service
class StripeGateway implements PaymentGatewayInterface
{
    private StripeClient $stripe;

    public function __construct(string $secretKey)
    {
        $this->stripe = new StripeClient($secretKey);
    }

    public function charge(float $amount, string $currency, string $paymentMethodId): array
    {
        $intent = $this->stripe->paymentIntents->create([
            'amount' => (int)($amount * 100),
            'currency' => $currency,
            'payment_method' => $paymentMethodId,
            'confirm' => true,
        ]);

        return [
            'transaction_id' => $intent->id,
            'status' => $intent->status,
            'client_secret' => $intent->client_secret,
        ];
    }

    public function refund(string $transactionId, float $amount): array
    {
        $refund = $this->stripe->refunds->create([
            'payment_intent' => $transactionId,
            'amount' => (int)($amount * 100),
        ]);

        return [
            'refund_id' => $refund->id,
            'status' => $refund->status,
        ];
    }

    public function createPaymentIntent(float $amount, string $currency): array
    {
        $intent = $this->stripe->paymentIntents->create([
            'amount' => (int)($amount * 100),
            'currency' => $currency,
            'payment_method_types' => ['card'],
        ]);

        return [
            'intent_id' => $intent->id,
            'client_secret' => $intent->client_secret,
        ];
    }
}

// 2. Notification Service
class NotificationService implements NotificationInterface
{
    private array $channels = [];

    public function __construct(array $channels)
    {
        $this->channels = $channels;
    }

    public function send(User $user, string $message, string $channel): void
    {
        if (!isset($this->channels[$channel])) {
            throw new \Exception("Channel '{$channel}' not available");
        }

        $this->channels[$channel]->send($user, $message);
    }

    public function getAvailableChannels(): array
    {
        return array_keys($this->channels);
    }
}

class EmailChannel
{
    public function send(User $user, string $message): void
    {
        Mail::to($user->email)->send(new NotificationMessage($user, $message));
    }
}

class SmsChannel
{
    private Client $twilio;

    public function __construct(Client $twilio)
    {
        $this->twilio = $twilio;
    }

    public function send(User $user, string $message): void
    {
        $this->twilio->messages->create(
            $user->phone,
            [
                'from' => config('services.twilio.from'),
                'body' => $message,
            ]
        );
    }
}

// 3. Inventory Service
class InventoryService implements InventoryInterface
{
    private ProductRepositoryInterface $productRepository;
    private CacheManager $cache;

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

    public function checkAvailability(int $productId, int $quantity): bool
    {
        $stock = $this->getStock($productId);
        return $stock >= $quantity;
    }

    public function reserveStock(int $productId, int $quantity): void
    {
        $product = $this->productRepository->find($productId);

        if (!$product || $product->stock < $quantity) {
            throw new \Exception("Insufficient stock for product {$productId}");
        }

        $product->stock -= $quantity;
        $this->productRepository->save($product);
        $this->cache->forget("product_stock_{$productId}");
    }

    public function releaseStock(int $productId, int $quantity): void
    {
        $product = $this->productRepository->find($productId);

        if (!$product) {
            throw new \Exception("Product {$productId} not found");
        }

        $product->stock += $quantity;
        $this->productRepository->save($product);
        $this->cache->forget("product_stock_{$productId}");
    }

    public function getStock(int $productId): int
    {
        $cacheKey = "product_stock_{$productId}";

        return $this->cache->remember($cacheKey, 3600, function () use ($productId) {
            $product = $this->productRepository->find($productId);
            return $product ? $product->stock : 0;
        });
    }
}

// 4. Order Repository
class EloquentOrderRepository implements OrderRepositoryInterface
{
    public function save(Order $order): void
    {
        $order->save();
    }

    public function find(int $id): ?Order
    {
        return Order::find($id);
    }

    public function findByUser(int $userId): array
    {
        return Order::where('user_id', $userId)->get()->all();
    }
}

Step 3: The Refactored Order Service (High Cohesion, Low Coupling)

class OrderService
{
    public function __construct(
        private readonly OrderRepositoryInterface $orderRepository,
        private readonly PaymentGatewayInterface $paymentGateway,
        private readonly NotificationInterface $notificationService,
        private readonly InventoryInterface $inventoryService,
        private readonly LoggerInterface $logger
    ) {}

    public function createOrder(int $userId, array $items): Order
    {
        $this->logger->info('Creating order', ['user_id' => $userId]);

        // Validate and reserve inventory
        $total = 0;
        foreach ($items as $item) {
            if (!$this->inventoryService->checkAvailability($item['product_id'], $item['quantity'])) {
                throw new \Exception("Product {$item['product_id']} unavailable");
            }

            $product = Product::find($item['product_id']);
            $total += $product->price * $item['quantity'];

            $this->inventoryService->reserveStock($item['product_id'], $item['quantity']);
        }

        // Create order
        $order = new Order();
        $order->user_id = $userId;
        $order->items = json_encode($items);
        $order->total = $total;
        $order->status = 'pending';

        $this->orderRepository->save($order);

        // Send notifications
        $user = User::find($userId);
        $this->notificationService->send($user, "Order #{$order->id} created!", 'email');
        $this->notificationService->send($user, "Order #{$order->id} created!", 'sms');

        $this->logger->info('Order created successfully', ['order_id' => $order->id]);

        return $order;
    }

    public function processPayment(Order $order, string $paymentMethodId): array
    {
        if ($order->status !== 'pending') {
            throw new \Exception("Cannot process payment for order with status: {$order->status}");
        }

        $this->logger->info('Processing payment', ['order_id' => $order->id]);

        $result = $this->paymentGateway->charge(
            $order->total,
            'usd',
            $paymentMethodId
        );

        $order->payment_intent_id = $result['transaction_id'];
        $order->status = 'paid';
        $this->orderRepository->save($order);

        $this->logger->info('Payment processed', [
            'order_id' => $order->id,
            'transaction_id' => $result['transaction_id'],
        ]);

        return $result;
    }

    public function fulfillOrder(Order $order): void
    {
        if ($order->status !== 'paid') {
            throw new \Exception("Only paid orders can be fulfilled");
        }

        $this->logger->info('Fulfilling order', ['order_id' => $order->id]);

        // Generate shipping labels
        $items = json_decode($order->items, true);
        foreach ($items as $item) {
            $this->generateShippingLabel($item, $order);
        }

        $order->status = 'shipped';
        $this->orderRepository->save($order);

        $user = User::find($order->user_id);
        $this->notificationService->send($user, "Order #{$order->id} shipped!", 'email');

        $this->logger->info('Order fulfilled', ['order_id' => $order->id]);
    }

    private function generateShippingLabel(array $item, Order $order): void
    {
        // Shipping label logic (focused)
        // Could be extracted to a ShippingService
    }
}

Step 4: Wiring Everything Together (Factory or DI Container)

// Service Provider (Laravel)
class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Bind interfaces to concretions
        $this->app->bind(PaymentGatewayInterface::class, StripeGateway::class);
        $this->app->bind(OrderRepositoryInterface::class, EloquentOrderRepository::class);
        $this->app->bind(InventoryInterface::class, InventoryService::class);

        // Bind notification channels
        $this->app->bind(NotificationInterface::class, function ($app) {
            return new NotificationService([
                'email' => $app->make(EmailChannel::class),
                'sms' => $app->make(SmsChannel::class),
            ]);
        });

        // Bind OrderService with all dependencies
        $this->app->bind(OrderService::class, function ($app) {
            return new OrderService(
                $app->make(OrderRepositoryInterface::class),
                $app->make(PaymentGatewayInterface::class),
                $app->make(NotificationInterface::class),
                $app->make(InventoryInterface::class),
                $app->make(LoggerInterface::class)
            );
        });
    }
}

What We Improved

High Cohesion:
- Each service has one clear responsibility.
- OrderService only handles order orchestration.
- StripeGateway only handles Stripe API calls.
- InventoryService only handles inventory operations.
Low Coupling:
- OrderService depends on interfaces, not concretions.
- Services can be swapped without changing OrderService.
- Dependencies are injected.
Testability:
- Test OrderService with mocks.
- Test StripeGateway independently.
- Test InventoryService independently.
Maintainability:
- Changes to Stripe only affect StripeGateway.
- Changes to notifications only affect NotificationService.
Extensibility:
- Add PayPal by implementing PaymentGatewayInterface.
- Add Slack by adding a new channel to NotificationService.

8. Laravel Internal Example

Laravel is a masterclass in high cohesion and low coupling. Let's look at how the framework applies these principles.

The HTTP Kernel (Separation of Concerns)

// Illuminate\Foundation\Http\Kernel
class Kernel implements KernelContract
{
    // High cohesion: Each middleware has one job
    protected $middleware = [
        \Illuminate\Session\Middleware\StartSession::class,      // Session management
        \Illuminate\View\Middleware\ShareErrorsFromSession::class, // Error sharing
        \App\Http\Middleware\Authenticate::class,                 // Authentication
        \App\Http\Middleware\VerifyCsrfToken::class,              // CSRF protection
    ];

    // Low coupling: Middleware are independent
    // They communicate through the request/response interface
    public function handle($request)
    {
        // The pipeline handles middleware composition
        return (new Pipeline($this->app))
            ->send($request)
            ->through($this->middleware)
            ->then(function ($request) {
                return $this->router->dispatch($request);
            });
    }
}

Why This Is Elegant:

High Cohesion: Each middleware has one responsibility.
Low Coupling: Middleware don't know about each other.
Extensibility: Add a new middleware without changing others.
Testability: Test each middleware independently.

Service Providers (Configuration Cohesion)

// App\Providers\AppServiceProvider
class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Cohesion: Register services
        $this->app->bind(PaymentGatewayInterface::class, StripeGateway::class);
        $this->app->bind(NotificationInterface::class, NotificationService::class);
    }

    public function boot(): void
    {
        // Cohesion: Boot services
        $this->loadMigrationsFrom(database_path('migrations'));
        $this->loadRoutesFrom(base_path('routes/api.php'));
    }
}

Why This Is Elegant:

High Cohesion: Each provider focuses on a specific domain.
Low Coupling: Providers don't depend on each other.
Organization: You can have multiple providers for different concerns.

Eloquent Model (Data Cohesion)

// Illuminate\Database\Eloquent\Model
abstract class Model implements Arrayable, ArrayAccess, Jsonable
{
    // High cohesion: All methods relate to data operations
    public function save() { /* ... */ }
    public function delete() { /* ... */ }
    public function update() { /* ... */ }
    public function find() { /* ... */ }

    // Low coupling: Depends on QueryBuilder interface
    protected $queryBuilder;
    protected $connection;
}

Why This Is Elegant:

High Cohesion: All model methods relate to data.
Low Coupling: Model doesn't know about the database implementation.
Extensibility: You can use different connections.

Events and Listeners (Loose Coupling)

// Event (one responsibility)
class OrderShipped
{
    public function __construct(public Order $order) {}
}

// Listener (one responsibility)
class SendShipmentNotification
{
    public function handle(OrderShipped $event): void
    {
        // Send notification
    }
}

Why This Is Elegant:

High Cohesion: Each event/listener has one purpose.
Low Coupling: The event system connects them loosely.
Extensibility: Add a listener without changing the event.

Facades (Simplified Coupling)

class Cache extends Facade
{
    // High cohesion: All cache operations
    // Low coupling: The facade connects to the actual service
    protected static function getFacadeAccessor()
    {
        return 'cache';
    }
}

Why This Is Elegant:

The facade provides a simple, cohesive interface.
It decouples the client from the implementation.

The Service Container (Coupling Manager)

// The container manages dependencies, reducing coupling
app()->bind(PaymentGatewayInterface::class, StripeGateway::class);
app()->make(OrderService::class); // All dependencies resolved

Why This Is Elegant:

The container handles wiring, reducing coupling.
Classes declare their dependencies, the container provides them.

9. Real Laravel Application Example

Let's build a Customer Support Ticket System with high cohesion and low coupling.

Scenario

Your SaaS application needs a ticket system for customer support. Tickets can be created, assigned, escalated, resolved, and closed. Each action triggers notifications, logging, and updates to metrics.

Implementation

Step 1: Define Interfaces (Contracts)

// app/Contracts/TicketRepositoryInterface.php
namespace App\Contracts;

use App\Models\Ticket;

interface TicketRepositoryInterface
{
    public function save(Ticket $ticket): void;
    public function find(int $id): ?Ticket;
    public function findByUser(int $userId): array;
    public function findByStatus(string $status): array;
    public function assignToAgent(Ticket $ticket, int $agentId): void;
}

// app/Contracts/NotificationServiceInterface.php
namespace App\Contracts;

use App\Models\User;
use App\Models\Ticket;

interface NotificationServiceInterface
{
    public function notifyCreated(Ticket $ticket, User $assignee): void;
    public function notifyAssigned(Ticket $ticket, User $agent): void;
    public function notifyEscalated(Ticket $ticket, string $reason): void;
    public function notifyResolved(Ticket $ticket): void;
    public function notifyClosed(Ticket $ticket): void;
}

// app/Contracts/TicketMetricsInterface.php
namespace App\Contracts;

use App\Models\Ticket;

interface TicketMetricsInterface
{
    public function trackCreated(Ticket $ticket): void;
    public function trackResolved(Ticket $ticket): void;
    public function trackEscalated(Ticket $ticket): void;
    public function getStatistics(array $filters): array;
}

// app/Contracts/TicketEscalationInterface.php
namespace App\Contracts;

use App\Models\Ticket;

interface TicketEscalationInterface
{
    public function shouldEscalate(Ticket $ticket): bool;
    public function escalate(Ticket $ticket): void;
    public function getEscalationLevel(Ticket $ticket): int;
}

Step 2: Implement Services (High Cohesion)

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

use App\Contracts\TicketRepositoryInterface;
use App\Models\Ticket;

class EloquentTicketRepository implements TicketRepositoryInterface
{
    public function save(Ticket $ticket): void
    {
        $ticket->save();
    }

    public function find(int $id): ?Ticket
    {
        return Ticket::find($id);
    }

    public function findByUser(int $userId): array
    {
        return Ticket::where('user_id', $userId)->get()->all();
    }

    public function findByStatus(string $status): array
    {
        return Ticket::where('status', $status)->get()->all();
    }

    public function assignToAgent(Ticket $ticket, int $agentId): void
    {
        $ticket->assigned_to = $agentId;
        $ticket->assigned_at = now();
        $ticket->save();
    }
}

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

use App\Contracts\NotificationServiceInterface;
use App\Models\User;
use App\Models\Ticket;
use Illuminate\Support\Facades\Mail;

class NotificationService implements NotificationServiceInterface
{
    public function notifyCreated(Ticket $ticket, User $assignee): void
    {
        Mail::to($assignee->email)->send(new TicketCreatedNotification($ticket));

        // Also send Slack notification if agent has Slack
        if ($assignee->slack_id) {
            // Send Slack message
        }
    }

    public function notifyAssigned(Ticket $ticket, User $agent): void
    {
        // Notify the agent
        Mail::to($agent->email)->send(new TicketAssignedNotification($ticket));

        // Notify the customer
        Mail::to($ticket->user->email)->send(new TicketAssignedCustomerNotification($ticket));
    }

    public function notifyEscalated(Ticket $ticket, string $reason): void
    {
        // Escalate to team lead
        $lead = User::role('team_lead')->first();
        Mail::to($lead->email)->send(new TicketEscalatedNotification($ticket, $reason));
    }

    public function notifyResolved(Ticket $ticket): void
    {
        // Notify the customer
        Mail::to($ticket->user->email)->send(new TicketResolvedNotification($ticket));

        // Notify all agents
        $agents = User::role('agent')->get();
        foreach ($agents as $agent) {
            Mail::to($agent->email)->send(new TicketResolvedAgentNotification($ticket));
        }
    }

    public function notifyClosed(Ticket $ticket): void
    {
        Mail::to($ticket->user->email)->send(new TicketClosedNotification($ticket));
    }
}

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

use App\Contracts\TicketMetricsInterface;
use App\Models\Ticket;
use Illuminate\Support\Facades\DB;

class TicketMetrics implements TicketMetricsInterface
{
    public function trackCreated(Ticket $ticket): void
    {
        DB::table('ticket_metrics')->insert([
            'ticket_id' => $ticket->id,
            'event' => 'created',
            'data' => json_encode([
                'user_id' => $ticket->user_id,
                'category' => $ticket->category,
                'priority' => $ticket->priority,
            ]),
            'created_at' => now(),
        ]);

        // Increment daily count
        $this->incrementDailyMetric('tickets_created');
    }

    public function trackResolved(Ticket $ticket): void
    {
        $timeToResolve = $ticket->resolved_at->diffInHours($ticket->created_at);

        DB::table('ticket_metrics')->insert([
            'ticket_id' => $ticket->id,
            'event' => 'resolved',
            'data' => json_encode([
                'time_to_resolve' => $timeToResolve,
                'agent_id' => $ticket->resolved_by,
            ]),
            'created_at' => now(),
        ]);

        $this->incrementDailyMetric('tickets_resolved');
    }

    public function trackEscalated(Ticket $ticket): void
    {
        DB::table('ticket_metrics')->insert([
            'ticket_id' => $ticket->id,
            'event' => 'escalated',
            'data' => json_encode([
                'reason' => $ticket->escalation_reason,
                'level' => $ticket->escalation_level,
            ]),
            'created_at' => now(),
        ]);

        $this->incrementDailyMetric('tickets_escalated');
    }

    public function getStatistics(array $filters): array
    {
        $query = DB::table('ticket_metrics')
            ->select('event', DB::raw('count(*) as count'))
            ->groupBy('event');

        if (isset($filters['from'])) {
            $query->where('created_at', '>=', $filters['from']);
        }
        if (isset($filters['to'])) {
            $query->where('created_at', '<=', $filters['to']);
        }

        return $query->get()->toArray();
    }

    private function incrementDailyMetric(string $key): void
    {
        $today = now()->toDateString();
        DB::table('daily_metrics')->updateOrInsert(
            ['key' => $key, 'date' => $today],
            ['value' => DB::raw('value + 1'), 'updated_at' => now()]
        );
    }
}

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

use App\Contracts\TicketEscalationInterface;
use App\Models\Ticket;

class TicketEscalation implements TicketEscalationInterface
{
    private const MAX_HOURS_OPEN = 24;
    private const MAX_AGENT_TICKETS = 10;

    public function shouldEscalate(Ticket $ticket): bool
    {
        // Escalate if ticket has been open too long
        if ($ticket->created_at->diffInHours(now()) > self::MAX_HOURS_OPEN) {
            return true;
        }

        // Escalate if agent has too many tickets
        if ($ticket->assigned_to) {
            $agentTickets = Ticket::where('assigned_to', $ticket->assigned_to)
                ->where('status', 'open')
                ->count();

            if ($agentTickets > self::MAX_AGENT_TICKETS) {
                return true;
            }
        }

        return false;
    }

    public function escalate(Ticket $ticket): void
    {
        $ticket->escalation_level = $this->getEscalationLevel($ticket) + 1;
        $ticket->escalation_reason = $this->determineEscalationReason($ticket);
        $ticket->escalated_at = now();
        $ticket->status = 'escalated';
        $ticket->save();
    }

    public function getEscalationLevel(Ticket $ticket): int
    {
        return $ticket->escalation_level ?? 0;
    }

    private function determineEscalationReason(Ticket $ticket): string
    {
        if ($ticket->created_at->diffInHours(now()) > self::MAX_HOURS_OPEN) {
            return "Ticket open for more than " . self::MAX_HOURS_OPEN . " hours";
        }

        if ($ticket->assigned_to) {
            $agentTickets = Ticket::where('assigned_to', $ticket->assigned_to)
                ->where('status', 'open')
                ->count();

            if ($agentTickets > self::MAX_AGENT_TICKETS) {
                return "Agent has {$agentTickets} open tickets (max " . self::MAX_AGENT_TICKETS . ")";
            }
        }

        return "Escalated due to unspecified reason";
    }
}

Step 3: The Orchestrator (High Cohesion, Low Coupling)

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

use App\Contracts\TicketRepositoryInterface;
use App\Contracts\NotificationServiceInterface;
use App\Contracts\TicketMetricsInterface;
use App\Contracts\TicketEscalationInterface;
use App\Models\Ticket;
use App\Models\User;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\DB;

class TicketService
{
    public function __construct(
        private readonly TicketRepositoryInterface $repository,
        private readonly NotificationServiceInterface $notification,
        private readonly TicketMetricsInterface $metrics,
        private readonly TicketEscalationInterface $escalation,
        private readonly LoggerInterface $logger
    ) {}

    public function create(array $data): Ticket
    {
        DB::beginTransaction();

        try {
            $ticket = new Ticket();
            $ticket->user_id = $data['user_id'];
            $ticket->subject = $data['subject'];
            $ticket->description = $data['description'];
            $ticket->category = $data['category'];
            $ticket->priority = $data['priority'];
            $ticket->status = 'open';
            $ticket->created_at = now();

            $this->repository->save($ticket);

            // Auto-assign to available agent
            $agent = $this->findAvailableAgent();
            if ($agent) {
                $this->repository->assignToAgent($ticket, $agent->id);
                $this->notification->notifyAssigned($ticket, $agent);
            }

            // Track metrics
            $this->metrics->trackCreated($ticket);

            // Notify user
            $this->notification->notifyCreated($ticket, $ticket->user);

            $this->logger->info('Ticket created', ['ticket_id' => $ticket->id]);

            DB::commit();

            return $ticket;

        } catch (\Exception $e) {
            DB::rollBack();
            $this->logger->error('Ticket creation failed', ['error' => $e->getMessage()]);
            throw $e;
        }
    }

    public function resolve(Ticket $ticket, User $agent, string $resolution): void
    {
        if ($ticket->status === 'closed') {
            throw new \Exception("Ticket already closed");
        }

        DB::beginTransaction();

        try {
            $ticket->status = 'resolved';
            $ticket->resolved_at = now();
            $ticket->resolved_by = $agent->id;
            $ticket->resolution = $resolution;

            $this->repository->save($ticket);

            // Track metrics
            $this->metrics->trackResolved($ticket);

            // Notify customer
            $this->notification->notifyResolved($ticket);

            $this->logger->info('Ticket resolved', [
                'ticket_id' => $ticket->id,
                'agent_id' => $agent->id,
            ]);

            DB::commit();

        } catch (\Exception $e) {
            DB::rollBack();
            $this->logger->error('Ticket resolution failed', ['error' => $e->getMessage()]);
            throw $e;
        }
    }

    public function checkAndEscalate(Ticket $ticket): void
    {
        if ($ticket->status !== 'open' && $ticket->status !== 'in_progress') {
            return;
        }

        if ($this->escalation->shouldEscalate($ticket)) {
            DB::beginTransaction();

            try {
                $this->escalation->escalate($ticket);
                $this->repository->save($ticket);

                // Track metrics
                $this->metrics->trackEscalated($ticket);

                // Notify team lead
                $this->notification->notifyEscalated($ticket, $ticket->escalation_reason);

                $this->logger->warning('Ticket escalated', [
                    'ticket_id' => $ticket->id,
                    'level' => $ticket->escalation_level,
                    'reason' => $ticket->escalation_reason,
                ]);

                DB::commit();

            } catch (\Exception $e) {
                DB::rollBack();
                $this->logger->error('Ticket escalation failed', ['error' => $e->getMessage()]);
                throw $e;
            }
        }
    }

    public function getMetrics(array $filters): array
    {
        return $this->metrics->getStatistics($filters);
    }

    private function findAvailableAgent(): ?User
    {
        // Find agent with fewest open tickets
        $agent = User::role('agent')
            ->withCount('tickets')
            ->orderBy('tickets_count')
            ->first();

        return $agent;
    }
}

Step 4: Controller (Thin Client)

// app/Http/Controllers/TicketController.php
namespace App\Http\Controllers;

use App\Models\Ticket;
use App\Services\TicketService;
use Illuminate\Http\Request;

class TicketController extends Controller
{
    public function __construct(
        private readonly TicketService $ticketService
    ) {}

    public function store(Request $request)
    {
        try {
            $ticket = $this->ticketService->create($request->validated());
            return response()->json($ticket, 201);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }

    public function resolve(Request $request, Ticket $ticket)
    {
        try {
            $this->ticketService->resolve($ticket, $request->user(), $request->input('resolution'));
            return response()->json(['message' => 'Ticket resolved']);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }

    public function metrics(Request $request)
    {
        return response()->json(
            $this->ticketService->getMetrics($request->only(['from', 'to']))
        );
    }
}

Why This Design Works

High Cohesion:
- Each class has one clear responsibility.
- TicketRepository: Data persistence.
- NotificationService: Sending notifications.
- TicketMetrics: Tracking statistics.
- TicketEscalation: Escalation rules.
- TicketService: Orchestration.
Low Coupling:
- TicketService depends on interfaces, not concretions.
- Services are independently testable.
- Changes to notification logic don't affect ticket logic.
Extensibility:
- Add a new notification channel (e.g., Slack) by implementing the interface.
- Change escalation rules by modifying TicketEscalation.
- Add new metrics by extending TicketMetrics.

10. SOLID Principles Mapping

S - Single Responsibility Principle (SRP)

Cohesion is the direct measure of SRP. Each class in the refactored design has one responsibility:

TicketService: Orchestrates ticket operations.
TicketRepository: Manages data persistence.
NotificationService: Handles notifications.
TicketMetrics: Tracks statistics.
TicketEscalation: Manages escalation rules.

O - Open/Closed Principle (OCP)

Low coupling enables OCP. You can add new implementations without changing existing code:

Add a new payment gateway: Implement PaymentGatewayInterface.
Add a new notification channel: Implement NotificationChannel.

L - Liskov Substitution Principle (LSP)

With low coupling through interfaces, any implementation can be substituted:

function process(OrderService $service) {
    // Works with any implementation
}

D - Dependency Inversion Principle (DIP)

High-level modules (TicketService) depend on abstractions (interfaces), not concretions. This is the definition of DIP.

I - Interface Segregation Principle (ISP)

Interfaces are focused and minimal:

TicketRepositoryInterface: Only repository methods.
NotificationServiceInterface: Only notification methods.
No class implements methods it doesn't need.

11. Trade-offs

Benefits

Maintainability: Changes are localized.
Testability: Test each class independently.
Readability: Classes are small and focused.
Reusability: Classes can be reused.
Extensibility: Add new features without changing existing code.
Parallel Development: Teams can work on different classes.

Costs

More Classes: High cohesion means more classes.
More Files: Each class gets its own file.
More Complexity: More moving parts to understand.
Setup Overhead: More configuration to wire everything together.
Learning Curve: Developers need to understand the architecture.

When Is Complexity Justified?

Use high cohesion and low coupling when:

The application is large and complex.
The codebase is likely to grow.
Multiple teams work on the codebase.
You need to test components independently.
You want to adhere to SOLID principles.

Avoid over-engineering when:

The application is small and simple.
The logic is unlikely to change.
The complexity of abstraction isn't justified.

12. When NOT To Use It

3 Green Flags (AIM FOR HIGH COHESION, LOW COUPLING)

Large Codebases: The application is growing or complex.
Multiple Teams: Different teams work on different modules.
Frequent Changes: Requirements change often, requiring flexibility.

3 Red Flags (AVOID OVER-ENGINEERING)

Small Projects: The application is small and simple.
Prototype: You're building a proof of concept.
Stable Logic: The logic is simple and unlikely to change.

13. Common Mistakes

1. Creating "Utility" Classes (Low Cohesion)

// BAD: Utility class with unrelated methods
class StringHelper
{
    public static function slug(string $str): string { /* ... */ }
    public static function generatePassword(): string { /* ... */ }
    public static function validateEmail(string $email): bool { /* ... */ }
    public static function encrypt(string $str): string { /* ... */ }
}

Problem: These methods are unrelated. The class has low cohesion.

Fix: Separate into focused classes: SlugGenerator, PasswordGenerator, EmailValidator, Encrypter.

2. God Objects (Low Cohesion)

// BAD: God object
class UserService
{
    public function createUser() { /* ... */ }
    public function updateUser() { /* ... */ }
    public function deleteUser() { /* ... */ }
    public function sendEmail() { /* ... */ }
    public function generateReport() { /* ... */ }
    public function processPayment() { /* ... */ }
}

Problem: The class does too many things.

Fix: Split into UserService, EmailService, ReportService, PaymentService.

3. Procedural Static Methods (Low Cohesion)

// BAD: All static, no state
class OrderHelper
{
    public static function calculateTotal($items) { /* ... */ }
    public static function applyDiscount($total, $code) { /* ... */ }
    public static function formatCurrency($amount) { /* ... */ }
    public static function generateInvoiceNumber() { /* ... */ }
}

Problem: This is procedural code masquerading as OOP.

Fix: Create focused classes with state: OrderCalculator, DiscountApplier, CurrencyFormatter.

4. Deeply Nested Dependencies (High Coupling)

// BAD: Tight coupling
class OrderService
{
    private StripePayment $payment;
    private TwilioClient $sms;
    private Mailer $mail;
    private Logger $log;

    public function __construct()
    {
        $this->payment = new StripePayment(config('stripe'));
        $this->sms = new TwilioClient(config('twilio'));
        $this->mail = new Mailer(config('mail'));
        $this->log = new Logger(config('log'));
    }
}

Problem: The class is tightly coupled to all dependencies.

Fix: Inject dependencies through the constructor.

5. Law of Demeter Violations (High Coupling)

// BAD: Talking to strangers
$city = $user->getAddress()->getCity()->getName();
$street = $user->getAddress()->getStreet()->getNumber();

// GOOD: Tell the user what you need
$city = $user->getCityName();
$address = $user->getFullAddress();

Problem: You're reaching through multiple objects.

Fix: Each object should provide its own information.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is cohesion in object-oriented design?
A: Cohesion measures how well the elements inside a module (class, method) belong together. High cohesion means the module is focused and has a single responsibility.
Q: What is coupling in object-oriented design?
A: Coupling measures how much a module depends on other modules. Low coupling means modules are independent and communicate through well-defined interfaces.
Q: Why is high cohesion desirable?
A: High cohesion makes code easier to understand, test, maintain, and reuse. Changes are localized to specific classes.
Q: Why is low coupling desirable?
A: Low coupling makes code more flexible, maintainable, and testable. Changing one module doesn't require changing others.
Q: What's the relationship between cohesion, coupling, and SOLID?
A: High cohesion and low coupling are the goals of SOLID principles. Each SOLID principle helps achieve these goals.

Senior/Architect

Q: How do you measure cohesion and coupling in a codebase?
A: Cohesion can be measured by the number of responsibilities per class. Coupling can be measured by the number of dependencies, the number of imports, or using tools like PHP Metrics.
Q: What's the ideal balance between cohesion and coupling?
A: There's no single "ideal." It depends on the application. But the goal is high cohesion (classes that do one thing) and low coupling (classes that don't depend on each other).
Q: How does the Law of Demeter relate to coupling?
A: The Law of Demeter (Don't Talk to Strangers) reduces coupling by restricting which objects you can interact with. It prevents "train wrecks" like $user->getAddress()->getCity()->getName().
Q: How do you refactor a codebase with low cohesion and high coupling?
A: Start by identifying responsibilities. Extract them into separate classes. Define interfaces for communication. Use dependency injection to wire everything together.
Q: What metrics tools can you use to measure cohesion and coupling in PHP?
A: PHP Metrics (PHPMetrics), PHPStan, Psalm, and Scrutinizer. They can detect high coupling and low cohesion.

15. Interactive Practice Challenge

The Requirement

You're building a Blog Management System. The current code is a mess of low cohesion and high coupling.

The Code (POOR DESIGN)

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

use App\Models\Post;
use App\Models\User;
use App\Models\Category;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;

class BlogService
{
    // 1. Handles post creation
    public function createPost(array $data, User $author): Post
    {
        // Validate
        if (empty($data['title']) || empty($data['content'])) {
            throw new \Exception('Title and content are required');
        }

        // Generate slug
        $slug = Str::slug($data['title']);
        $existing = Post::where('slug', $slug)->first();
        if ($existing) {
            $slug = $slug . '-' . time();
        }

        // Create post
        $post = new Post();
        $post->title = $data['title'];
        $post->slug = $slug;
        $post->content = $data['content'];
        $post->user_id = $author->id;
        $post->status = 'draft';
        $post->views = 0;
        $post->save();

        // Handle categories
        if (isset($data['categories'])) {
            $categoryIds = Category::whereIn('slug', $data['categories'])->pluck('id');
            $post->categories()->sync($categoryIds);
        }

        // Cache
        Cache::forget('recent_posts');
        Cache::forget('popular_posts');

        // Log
        Log::info('Post created', ['post_id' => $post->id, 'author' => $author->id]);

        // Notify subscribers
        $subscribers = User::where('subscribed', true)->get();
        foreach ($subscribers as $subscriber) {
            Mail::to($subscriber->email)->send(new NewPostNotification($post));
        }

        return $post;
    }

    // 2. Handles post publishing
    public function publishPost(Post $post): void
    {
        if ($post->status === 'published') {
            throw new \Exception('Post already published');
        }

        $post->status = 'published';
        $post->published_at = now();
        $post->save();

        // Update cache
        Cache::forget('recent_posts');
        Cache::forget('popular_posts');

        // Send to social media
        $this->postToSocialMedia($post);

        // Send to newsletter
        $this->sendToNewsletter($post);

        Log::info('Post published', ['post_id' => $post->id]);
    }

    // 3. Handles post deletion
    public function deletePost(Post $post): void
    {
        // Remove comments
        $post->comments()->delete();

        // Detach categories
        $post->categories()->detach();

        // Delete post
        $post->delete();

        // Update cache
        Cache::forget('recent_posts');
        Cache::forget('popular_posts');

        Log::info('Post deleted', ['post_id' => $post->id]);
    }

    // 4. Handles post viewing
    public function viewPost(string $slug): ?Post
    {
        $post = Post::with(['user', 'categories', 'comments'])
            ->where('slug', $slug)
            ->where('status', 'published')
            ->first();

        if (!$post) {
            return null;
        }

        // Increment views
        $post->views++;
        $post->save();

        // Cache recent post
        Cache::put("post_{$slug}", $post, 3600);

        // Track analytics
        $this->trackView($post);

        return $post;
    }

    // 5. Handles post search
    public function searchPosts(string $query): array
    {
        // Simple search
        return Post::where('title', 'LIKE', "%{$query}%")
            ->orWhere('content', 'LIKE', "%{$query}%")
            ->where('status', 'published')
            ->limit(50)
            ->get()
            ->all();
    }

    // 6. Handles popular posts
    public function getPopularPosts(int $limit = 10): array
    {
        return Cache::remember('popular_posts', 3600, function () use ($limit) {
            return Post::where('status', 'published')
                ->orderBy('views', 'desc')
                ->limit($limit)
                ->get()
                ->all();
        });
    }

    // 7. Handles related posts
    public function getRelatedPosts(Post $post, int $limit = 5): array
    {
        $categories = $post->categories->pluck('id');

        return Post::where('id', '!=', $post->id)
            ->where('status', 'published')
            ->whereHas('categories', function ($query) use ($categories) {
                $query->whereIn('category_id', $categories);
            })
            ->limit($limit)
            ->get()
            ->all();
    }

    // 8. Handles analytics
    private function trackView(Post $post): void
    {
        // Track view in analytics system
        $this->sendAnalyticsEvent('post_viewed', [
            'post_id' => $post->id,
            'user_id' => auth()->id(),
            'timestamp' => now(),
        ]);
    }

    private function sendAnalyticsEvent(string $event, array $data): void
    {
        // Send to analytics service
        Log::debug('Analytics event', ['event' => $event, 'data' => $data]);
    }

    // 9. Handles social media
    private function postToSocialMedia(Post $post): void
    {
        // Post to Twitter
        // Post to Facebook
        // Post to LinkedIn
        Log::info('Posted to social media', ['post_id' => $post->id]);
    }

    // 10. Handles newsletter
    private function sendToNewsletter(Post $post): void
    {
        // Send to newsletter service
        Log::info('Sent to newsletter', ['post_id' => $post->id]);
    }
}

The Challenges

The BlogService is a God Class with 10+ responsibilities. It has:

Low cohesion: Handles creation, publishing, deletion, viewing, searching, popular posts, related posts, analytics, social media, and newsletters.
High coupling: Depends on Post, User, Category, Cache, Log, Mail, DB, and Str.

New requirements are coming:

"We need to schedule posts for future publication."
"We need to save drafts and autosave."
"We need to moderate comments before they appear."
"We need to add SEO metadata."
"We need to export posts to JSON, XML, and RSS."
"We need to track post performance with detailed analytics."
"We need to add multiple authors and review workflows."

Your Task

Refactor this system using high cohesion and low coupling. Specifically:

Identify all responsibilities in the BlogService.
Create focused classes for each responsibility:
- PostCreator
- PostPublisher
- PostDeleter
- PostViewer
- PostSearcher
- PostQueries
- SocialMediaPublisher
- NewsletterService
- AnalyticsService
- CacheManager
- PostRepository
Define interfaces for each service.
Implement services with high cohesion.
Wire everything together using dependency injection.
Update the controller to use the new services.

Questions to Consider

How should you handle the relationships between services?
Should PostPublisher depend on SocialMediaPublisher and NewsletterService?
How do you handle caching across services?
How do you test each service independently?
Where should you put the orchestration logic?

(We won't provide the solution—refactor this code and master cohesion and coupling!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Cohesion measures how well a class's methods belong together; coupling measures how much a class depends on others.
One-sentence intuition: High cohesion means each class does one thing; low coupling means classes don't depend on each other.
One-sentence decision rule: If a class has more than one clear responsibility, split it. If a class knows too much about another, use dependency injection and interfaces.

17. Related Concepts

SOLID Principles

Single Responsibility: Cohesion is the measure of SRP.
Dependency Inversion: Low coupling through interfaces.
Open/Closed: Low coupling enables extension.
Liskov Substitution: Low coupling through substitutability.
Interface Segregation: Low coupling through focused interfaces.

Design Patterns

Strategy Pattern: Low coupling through interchangeable algorithms.
Factory Pattern: Reduces coupling by creating objects.
Observer Pattern: Low coupling between event sources and listeners.
Decorator Pattern: Adds behavior without changing classes.
Adapter Pattern: Reduces coupling between incompatible interfaces.

Laravel Internals

Service Container: Reduces coupling by managing dependencies.
Service Providers: Organize services by cohesion.
Contracts: Define interfaces for low coupling.
Facades: Simplified access with controlled coupling.
Middleware: Each middleware has one responsibility (high cohesion).
Events/Listeners: Decouple event sources from handlers.

Enterprise Patterns

Repository Pattern: Separates data access (high cohesion in data layer).
Service Layer Pattern: Organizes business logic.
Unit of Work: Manages transactions.
DTOs: Reduce coupling between layers.
CQRS: Separates commands from queries.

Final Thoughts

Cohesion and coupling are the foundational metrics of object-oriented design. They tell you if your code is healthy or dying.

High cohesion and low coupling are the goals. They make your code:

Maintainable: Changes are localized.
Testable: Each class can be tested independently.
Readable: Classes are small and focused.
Reusable: Classes can be used in different contexts.
Extensible: New features don't break existing code.

The next time you find yourself in a codebase where changes break everything, think about cohesion and coupling. You'll probably find low cohesion and high coupling.

Remember: High cohesion means "do one thing." Low coupling means "don't know about others." Master these two metrics, and you'll master object design.

Github: Cohesion and Coupling Practice Labs

The Art of Abstraction: When to Use Interfaces and Abstract Classes

Anas Hussain — Wed, 29 Jul 2026 04:39:38 +0000

1. Hook & Problem Statement

You're building a Laravel application. You type-hint PaymentGatewayInterface in your controller constructor. It works. You move on.

Later, you're reading through a senior developer's code and see:

abstract class PaymentGateway implements PaymentGatewayInterface { ... }
class StripeGateway extends PaymentGateway { ... }

You pause. "Wait," you think. "What's the difference between an interface and an abstract class? Why use one over the other? When should I use both?"

You've used interfaces before. You've seen abstract classes in Laravel (Model, ServiceProvider, Request). But you've never been able to clearly articulate when and why to use each.

This confusion is common. Most developers use interfaces and abstract classes without understanding the fundamental distinction. They're just "things that make my code more OOP." But they serve entirely different purposes.

The difference is subtle but profound.

An interface is a contract. An abstract class is a partial implementation. One tells you what to do. The other helps you how to do it.

Understanding this distinction is the difference between writing code that works and designing systems that scale. It's the difference between a junior developer who follows patterns and a senior architect who creates them.

2. Why This Pattern/Concept Exists

The Software Engineering Problem It Solves

Abstraction solves the problem of managing complexity by hiding implementation details. It allows you to define what a system does without specifying how it does it.

In large systems, you need to:

Define contracts that multiple implementations must follow.
Provide base functionality that implementations can reuse.
Enforce structure while allowing flexibility.

The Pain That Existed Before

Before interfaces and abstract classes (or in codebases that don't use them), developers faced:

Tight Coupling to Concretions: Code depended on specific classes, making it impossible to swap implementations.
Code Duplication: Similar logic was copy-pasted across multiple classes because there was no way to share base functionality.
No Contract Enforcement: There was no way to guarantee that different implementations had the same methods.
Fragile Inheritance: When inheritance was used for everything, changes cascaded unpredictably. #### Why Large Applications Need It

As applications grow, so does the need for structured abstraction:

Contracts (Interfaces): Allow teams to define a clear contract that multiple implementations must follow. This enables polymorphism and dependency inversion.
Base Functionality (Abstract Classes): Allow teams to share common logic across multiple implementations, reducing duplication and ensuring consistency.
Evolution: Abstractions allow you to evolve a system without breaking existing code. You can add new implementations without changing the code that uses them.

The core insight: Interfaces define what can be done. Abstract classes define how something is done. One is about specification, the other about implementation.

3. Real World Analogy

The Restaurant Menu

Imagine a restaurant chain with multiple locations.

Interfaces (The Menu):
Every restaurant in the chain has a menu (interface). The menu defines what dishes are available (methods): burger, pizza, salad. Customers (client code) know they can order these items at any location.

Menu: The interface (defines what is available).
Burger, Pizza, Salad: The methods (contract).
Customer: The client code that depends on the interface.

Abstract Classes (The Recipe Book):
The chain has a recipe book (abstract class) that provides how to make the dishes. It includes:

Common techniques for all dishes.
Specific ingredients (properties).
Standardized procedures (methods).

The recipes define:

A prepareMeal() method with standard steps (base functionality).
Abstract methods like cookMainComponent() that each location implements differently.

Concrete Classes (The Actual Restaurants):
Each location (Stripe, PayPal, etc.):

Follows the menu (implements the interface).
Uses the recipe (extends the abstract class).
Customizes the details (implements abstract methods).

Analogy Mapping:

Menu: Interface (what you can do).
Recipe Book: Abstract class (how to do it with shared logic).
Actual Restaurant: Concrete class (specific implementation).
Customer: Client code.
Chef's Special Technique: Private/protected methods (implementation details).

Why it works:

The interface guarantees every location has the same offerings.
The abstract class ensures consistency in preparation.
Each location can customize the specifics.

4. The Pain (Bad Design)

Let's look at a common scenario: an e-commerce application with different payment gateways, implemented without proper abstraction.

// No abstraction - everything is concrete
class StripePayment
{
    private string $secretKey;
    private string $currency;
    private array $transactionLog = [];

    public function __construct(string $secretKey, string $currency = 'USD')
    {
        $this->secretKey = $secretKey;
        $this->currency = $currency;
    }

    public function charge(float $amount, array $customer): array
    {
        // 30 lines of Stripe-specific logic
        $stripe = new \Stripe\StripeClient($this->secretKey);

        try {
            $intent = $stripe->paymentIntents->create([
                'amount' => $amount * 100,
                'currency' => $this->currency,
                'customer' => $customer['stripe_id'],
                'payment_method' => $customer['payment_method_id'],
            ]);

            $this->logTransaction('charge', $intent->id, $amount);

            return [
                'success' => true,
                'transaction_id' => $intent->id,
                'status' => $intent->status,
            ];
        } catch (\Exception $e) {
            $this->logTransaction('charge_failed', null, $amount, $e->getMessage());
            throw $e;
        }
    }

    public function refund(string $transactionId, float $amount): array
    {
        // 15 lines of Stripe-specific refund logic
        $stripe = new \Stripe\StripeClient($this->secretKey);
        $refund = $stripe->refunds->create([
            'payment_intent' => $transactionId,
            'amount' => $amount * 100,
        ]);

        $this->logTransaction('refund', $refund->id, $amount);

        return ['success' => true, 'refund_id' => $refund->id];
    }

    private function logTransaction(string $type, ?string $id, float $amount, ?string $error = null): void
    {
        $this->transactionLog[] = [
            'type' => $type,
            'id' => $id,
            'amount' => $amount,
            'error' => $error,
            'timestamp' => date('Y-m-d H:i:s'),
        ];
    }

    public function getTransactionLog(): array
    {
        return $this->transactionLog;
    }
}

class PayPalPayment
{
    private string $clientId;
    private string $clientSecret;
    private array $transactionLog = [];

    public function __construct(string $clientId, string $clientSecret)
    {
        $this->clientId = $clientId;
        $this->clientSecret = $clientSecret;
    }

    public function charge(float $amount, array $customer): array
    {
        // 30 lines of PayPal-specific logic
        $apiContext = new \PayPal\Rest\ApiContext(
            new \PayPal\Auth\OAuthTokenCredential($this->clientId, $this->clientSecret)
        );

        $payment = new \PayPal\Api\Payment();
        $payment->setIntent('sale')
            ->setPayer(['payment_method' => 'paypal'])
            ->setTransactions([[
                'amount' => [
                    'total' => $amount,
                    'currency' => 'USD',
                ],
                'description' => 'Payment',
            ]]);

        try {
            $payment->create($apiContext);

            $this->logTransaction('charge', $payment->getId(), $amount);

            return [
                'success' => true,
                'transaction_id' => $payment->getId(),
                'approval_url' => $this->getApprovalUrl($payment),
            ];
        } catch (\Exception $e) {
            $this->logTransaction('charge_failed', null, $amount, $e->getMessage());
            throw $e;
        }
    }

    public function refund(string $transactionId, float $amount): array
    {
        // 15 lines of PayPal-specific refund logic
        // Different API calls, different parameters
        return ['success' => true];
    }

    private function getApprovalUrl($payment): ?string
    {
        foreach ($payment->getLinks() as $link) {
            if ($link->getRel() === 'approval_url') {
                return $link->getHref();
            }
        }
        return null;
    }

    private function logTransaction(string $type, ?string $id, float $amount, ?string $error = null): void
    {
        $this->transactionLog[] = [
            'type' => $type,
            'id' => $id,
            'amount' => $amount,
            'error' => $error,
            'timestamp' => date('Y-m-d H:i:s'),
        ];
    }

    public function getTransactionLog(): array
    {
        return $this->transactionLog;
    }
}

// Client code
class PaymentController
{
    public function charge(Request $request)
    {
        $paymentMethod = $request->input('payment_method');

        if ($paymentMethod === 'stripe') {
            $payment = new StripePayment(config('services.stripe.secret'));
            $result = $payment->charge($request->amount, $request->customer);
        } elseif ($paymentMethod === 'paypal') {
            $payment = new PayPalPayment(
                config('services.paypal.client_id'),
                config('services.paypal.secret')
            );
            $result = $payment->charge($request->amount, $request->customer);
        } else {
            throw new \Exception('Unsupported payment method');
        }

        return response()->json($result);
    }
}

Why This Is Terrible

No Contract: No guarantee that both classes have the same methods.
Duplicated Code: Logging logic is identical but repeated.
Tight Coupling: The controller must know about every payment class.
No Extensibility: Adding a new method requires finding all implementations.
Violates SOLID:
- OCP: Adding a new payment method requires modifying the controller.
- DIP: Controller depends on concrete classes, not abstractions.
- DRY: Logging logic is duplicated.

Why Developers Write Code Like This

They think "I'll just add one more payment method."
They don't plan for abstraction.
They don't understand the power of interfaces and abstract classes.
They're afraid of "over-engineering."

5. Solution Overview

Abstraction is the process of hiding implementation details and exposing only essential features. In PHP, abstraction is achieved through:

Interfaces: Pure contracts (no implementation).
Abstract Classes: Partial implementations (some concrete, some abstract).

Core Idea

Interfaces define what an object can do. They are contracts.
Abstract classes define how an object does it, providing shared logic.

Main Participants

Interface: The contract that all implementations must follow.
Abstract Class: The base implementation with shared logic.
Concrete Classes: The specific implementations.
Client: The code that depends on the abstraction.

How Objects Collaborate

Interface (Contract)
    ↓
Abstract Class (Base Implementation)
    ↓
Concrete Class (Specific Implementation)
    ↓
Client (Uses the abstraction)

Mental Model

Interfaces are like job descriptions. They define what a person (object) needs to be able to do, not how they do it.

Abstract classes are like employee handbooks. They provide standard procedures, guidelines, and shared resources that all employees (objects) can use, while still allowing each employee to perform their specific duties.

Benefits

Flexibility: Swap implementations easily.
Testability: Mock dependencies using interfaces.
Reusability: Share common logic via abstract classes.
Maintainability: Changes are isolated.

Trade-offs

Complexity: More files and abstractions.
Learning Curve: Developers must understand abstraction hierarchies.
Over-engineering: Unnecessary abstractions can complicate simple code.

6. UML Diagram

Laravel Abstraction Mermaid Diagram

Diagram Explanation

PaymentInterface defines the contract (what methods exist).
AbstractPayment provides shared implementation (currency, logging).
Concrete classes extend the abstract class and implement specific logic.
PaymentController depends only on the interface.
Abstract methods (calculateFee, formatCurrency) force concrete classes to implement payment-specific logic.

7. Vanilla PHP Example

Let's refactor the payment system using proper abstraction.

Before Refactoring (No Abstraction)

(The terrible code shown above)

After Refactoring (Interfaces + Abstract Classes)

Step 1: Define the Interface (The Contract)

interface PaymentInterface
{
    public function charge(float $amount, array $customer): array;
    public function refund(string $transactionId, float $amount): array;
    public function getTransactionLog(): array;
    public function calculateFee(float $amount): float;
    public function formatCurrency(float $amount): string;
}

Step 2: Define the Abstract Class (Shared Logic)

abstract class AbstractPayment implements PaymentInterface
{
    protected string $currency;
    protected array $transactionLog = [];

    public function __construct(string $currency = 'USD')
    {
        $this->currency = $currency;
    }

    // Shared implementation
    protected function logTransaction(string $type, ?string $id, float $amount, ?string $error = null): void
    {
        $this->transactionLog[] = [
            'type' => $type,
            'id' => $id,
            'amount' => $amount,
            'error' => $error,
            'timestamp' => date('Y-m-d H:i:s'),
            'currency' => $this->currency,
        ];
    }

    // Concrete implementation (shared by all)
    public function getTransactionLog(): array
    {
        return $this->transactionLog;
    }

    // Abstract methods (each implementation must define)
    abstract public function charge(float $amount, array $customer): array;
    abstract public function refund(string $transactionId, float $amount): array;
    abstract public function calculateFee(float $amount): float;
    abstract public function formatCurrency(float $amount): string;
}

Step 3: Implement Concrete Classes

class StripePayment extends AbstractPayment
{
    private \Stripe\StripeClient $stripe;

    public function __construct(string $secretKey, string $currency = 'USD')
    {
        parent::__construct($currency);
        $this->stripe = new \Stripe\StripeClient($secretKey);
    }

    public function charge(float $amount, array $customer): array
    {
        try {
            $intent = $this->stripe->paymentIntents->create([
                'amount' => $this->formatCurrency($amount),
                'currency' => $this->currency,
                'customer' => $customer['stripe_id'],
                'payment_method' => $customer['payment_method_id'],
                'confirm' => true,
            ]);

            $this->logTransaction('charge', $intent->id, $amount);

            return [
                'success' => true,
                'transaction_id' => $intent->id,
                'status' => $intent->status,
                'fee' => $this->calculateFee($amount),
                'currency' => $this->currency,
            ];
        } catch (\Exception $e) {
            $this->logTransaction('charge_failed', null, $amount, $e->getMessage());
            throw new \Exception('Stripe charge failed: ' . $e->getMessage());
        }
    }

    public function refund(string $transactionId, float $amount): array
    {
        try {
            $refund = $this->stripe->refunds->create([
                'payment_intent' => $transactionId,
                'amount' => $this->formatCurrency($amount),
            ]);

            $this->logTransaction('refund', $refund->id, $amount);

            return [
                'success' => true,
                'refund_id' => $refund->id,
                'status' => $refund->status,
                'currency' => $this->currency,
            ];
        } catch (\Exception $e) {
            $this->logTransaction('refund_failed', $transactionId, $amount, $e->getMessage());
            throw new \Exception('Stripe refund failed: ' . $e->getMessage());
        }
    }

    public function calculateFee(float $amount): float
    {
        // Stripe fee: 2.9% + $0.30
        return round(($amount * 0.029) + 0.30, 2);
    }

    public function formatCurrency(float $amount): int
    {
        // Stripe uses cents
        return (int)($amount * 100);
    }
}

class PayPalPayment extends AbstractPayment
{
    private \PayPal\Rest\ApiContext $apiContext;

    public function __construct(string $clientId, string $clientSecret, string $currency = 'USD')
    {
        parent::__construct($currency);
        $this->apiContext = new \PayPal\Rest\ApiContext(
            new \PayPal\Auth\OAuthTokenCredential($clientId, $clientSecret)
        );
    }

    public function charge(float $amount, array $customer): array
    {
        try {
            $payment = new \PayPal\Api\Payment();
            $payment->setIntent('sale')
                ->setPayer(['payment_method' => 'paypal'])
                ->setTransactions([[
                    'amount' => [
                        'total' => $this->formatCurrency($amount),
                        'currency' => $this->currency,
                    ],
                    'description' => 'Payment',
                ]])
                ->setRedirectUrls([
                    'return_url' => $customer['return_url'],
                    'cancel_url' => $customer['cancel_url'],
                ]);

            $payment->create($this->apiContext);

            $this->logTransaction('charge', $payment->getId(), $amount);

            return [
                'success' => true,
                'transaction_id' => $payment->getId(),
                'approval_url' => $this->getApprovalUrl($payment),
                'fee' => $this->calculateFee($amount),
                'currency' => $this->currency,
            ];
        } catch (\Exception $e) {
            $this->logTransaction('charge_failed', null, $amount, $e->getMessage());
            throw new \Exception('PayPal charge failed: ' . $e->getMessage());
        }
    }

    public function refund(string $transactionId, float $amount): array
    {
        try {
            $sale = new \PayPal\Api\Sale();
            $sale->setId($transactionId);

            $refund = new \PayPal\Api\Refund();
            $refund->setAmount([
                'total' => $this->formatCurrency($amount),
                'currency' => $this->currency,
            ]);

            $refunded = $sale->refund($refund, $this->apiContext);

            $this->logTransaction('refund', $refunded->getId(), $amount);

            return [
                'success' => true,
                'refund_id' => $refunded->getId(),
                'status' => $refunded->getState(),
                'currency' => $this->currency,
            ];
        } catch (\Exception $e) {
            $this->logTransaction('refund_failed', $transactionId, $amount, $e->getMessage());
            throw new \Exception('PayPal refund failed: ' . $e->getMessage());
        }
    }

    public function calculateFee(float $amount): float
    {
        // PayPal fee: 3.4% + $0.30
        return round(($amount * 0.034) + 0.30, 2);
    }

    public function formatCurrency(float $amount): string
    {
        // PayPal expects string with 2 decimals
        return number_format($amount, 2, '.', '');
    }

    private function getApprovalUrl($payment): ?string
    {
        foreach ($payment->getLinks() as $link) {
            if ($link->getRel() === 'approval_url') {
                return $link->getHref();
            }
        }
        return null;
    }
}

Step 4: Client Code (Using the Abstraction)

class PaymentController
{
    private PaymentInterface $payment;

    public function __construct(PaymentInterface $payment)
    {
        $this->payment = $payment;
    }

    public function charge(Request $request): JsonResponse
    {
        try {
            $result = $this->payment->charge(
                $request->input('amount'),
                $request->input('customer')
            );

            return response()->json($result);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage(),
            ], 400);
        }
    }

    public function refund(Request $request): JsonResponse
    {
        try {
            $result = $this->payment->refund(
                $request->input('transaction_id'),
                $request->input('amount')
            );

            return response()->json($result);
        } catch (\Exception $e) {
            return response()->json([
                'success' => false,
                'error' => $e->getMessage(),
            ], 400);
        }
    }

    public function log(): JsonResponse
    {
        return response()->json($this->payment->getTransactionLog());
    }
}

Step 5: Factory (or Dependency Injection)

class PaymentFactory
{
    public static function create(string $type): PaymentInterface
    {
        return match($type) {
            'stripe' => new StripePayment(
                config('services.stripe.secret'),
                config('services.stripe.currency', 'USD')
            ),
            'paypal' => new PayPalPayment(
                config('services.paypal.client_id'),
                config('services.paypal.secret'),
                config('services.paypal.currency', 'USD')
            ),
            default => throw new \Exception("Unknown payment type: {$type}"),
        };
    }
}

// Usage in controller (or via Laravel's container)
$payment = PaymentFactory::create($request->input('payment_method'));
$controller = new PaymentController($payment);

What We Improved

Clear Contract: Interface defines what all payments must do.
Shared Logic: Abstract class provides logging and currency handling.
Specific Logic: Each concrete class implements its own charge/refund logic.
Flexibility: Swap payments by changing the factory or binding.
Testability: Mock the interface for testing.
SOLID Compliance: OCP (add new payments), DIP (depend on interface).

8. Laravel Internal Example

Laravel is built on layers of abstraction. Let's look at how it uses interfaces and abstract classes.

Eloquent Model (Abstract Class + Interfaces)

// Illuminate\Database\Eloquent\Model
abstract class Model implements Arrayable, ArrayAccess, Jsonable, JsonSerializable, QueueableEntity, UrlRoutable
{
    // Abstract: Provides base functionality
    protected $connection;
    protected $table;
    protected $primaryKey = 'id';

    // Concrete methods (shared by all models)
    public function save(array $options = [])
    {
        // 100+ lines of shared save logic
    }

    public function delete()
    {
        // Shared delete logic
    }

    // Abstract methods (must be implemented by child classes)
    abstract public function getConnectionName();
    abstract public function getTable();
}

Why This Is Elegant:

Abstract Class: Provides all the shared Eloquent functionality.
Interfaces: Ensure the model can be used in different contexts (Arrayable, Jsonable, Queueable).
Your Model: Extends the abstract class and optionally implements additional interfaces.

Service Provider (Abstract Class)

// Illuminate\Support\ServiceProvider
abstract class ServiceProvider
{
    // Abstract: Provides the registration structure
    protected $app;
    protected $defer = false;

    // Concrete method (shared)
    public function register()
    {
        // Default implementation
    }

    // Abstract method (must be implemented)
    abstract public function register();

    // Optional boot method (concrete)
    public function boot()
    {
        // Can be overridden
    }
}

Why This Is Elegant:

The abstract class provides the registration infrastructure.
Your provider only needs to implement register().
boot() is optional, allowing providers to be simple or complex.

Queueable Interface (Pure Interface)

// Illuminate\Contracts\Queue\QueueableEntity
interface QueueableEntity
{
    public function getQueueableId();
    public function getQueueableConnection();
    public function getQueueableRelations();
}

// Implemented by Model
class Model implements QueueableEntity
{
    public function getQueueableId()
    {
        return $this->getKey();
    }
    // ...
}

Why This Is Elegant:

The interface defines what's needed to queue an entity.
Model implements it, but other classes could too.
The queue system only depends on the interface.

Authentication (Multiple Interfaces)

// Illuminate\Contracts\Auth\Guard
interface Guard
{
    public function check(): bool;
    public function user(): ?Authenticatable;
    public function validate(array $credentials = []): bool;
}

// Illuminate\Contracts\Auth\Authenticatable
interface Authenticatable
{
    public function getAuthIdentifierName();
    public function getAuthIdentifier();
    public function getAuthPassword();
    public function getRememberToken();
    public function setRememberToken($value);
    public function getRememberTokenName();
}

// Abstract base guard
abstract class Guard implements Guard
{
    // Shared logic for all guards
    protected $name;
    protected $user;
    protected $lastAttempted;

    // Abstract methods for specific guards
    abstract public function attempt(array $credentials = [], $remember = false);
    abstract public function once(array $credentials = []);
}

Why This Is Elegant:

Interfaces define clear contracts.
Abstract class provides shared logic.
Concrete guards (SessionGuard, TokenGuard) handle specifics.

Filesystem (Interface + Abstract Class)

// Illuminate\Contracts\Filesystem\Filesystem
interface Filesystem
{
    public function exists(string $path): bool;
    public function get(string $path): string;
    public function put(string $path, $contents, $options = []): bool;
    public function delete(string|array $paths): bool;
    // ... more methods
}

// Abstract FilesystemAdapter (Laravel-specific)
abstract class FilesystemAdapter implements Filesystem
{
    // Shared logic for all filesystems
    protected $driver;
    protected $config;

    public function get($path)
    {
        // Shared get logic with error handling
    }

    // Abstract methods
    abstract public function write($path, $contents, $config);
    abstract public function read($path);
}

// Concrete implementations
class LocalFilesystem extends FilesystemAdapter { /* ... */ }
class S3Filesystem extends FilesystemAdapter { /* ... */ }

Why This Is Elegant:

The interface defines the contract.
The abstract class provides error handling and shared logic.
Each driver implements the specific operations.

9. Real Laravel Application Example

Let's build a Report Generation System using proper abstraction.

Scenario

Your application needs to generate reports in different formats (PDF, Excel, CSV, JSON). Each format has:

Different rendering logic.
Different file generation.
Different meta-requirements.

But they all share:

Data fetching.
Header/footer formatting.
Logging.
File storage.

Implementation

Step 1: Define the Interface (Contract)

// app/Contracts/ReportGeneratorInterface.php
namespace App\Contracts;

use App\Models\Report;

interface ReportGeneratorInterface
{
    public function generate(Report $report, array $options = []): ReportResult;
    public function getFormat(): string;
    public function getMimeType(): string;
    public function getFileExtension(): string;
    public function supports(Report $report): bool;
}

Step 2: Create Result DTO

// app/DTO/ReportResult.php
namespace App\DTO;

class ReportResult
{
    public function __construct(
        public readonly string $content,
        public readonly string $filename,
        public readonly string $mimeType,
        public readonly int $size,
        public readonly ?string $tempPath = null,
        public readonly array $metadata = []
    ) {}
}

Step 3: Abstract Base Class (Shared Logic)

// app/Services/Report/AbstractReportGenerator.php
namespace App\Services\Report;

use App\Contracts\ReportGeneratorInterface;
use App\DTO\ReportResult;
use App\Models\Report;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Storage;

abstract class AbstractReportGenerator implements ReportGeneratorInterface
{
    protected array $headers = [];
    protected array $footers = [];
    protected array $metadata = [];

    public function __construct(
        protected readonly string $storageDisk = 'local',
        protected readonly bool $debug = false
    ) {}

    public function generate(Report $report, array $options = []): ReportResult
    {
        $startTime = microtime(true);

        try {
            // Step 1: Fetch data (shared)
            $data = $this->fetchData($report, $options);

            // Step 2: Prepare headers (shared)
            $this->prepareHeaders($report);

            // Step 3: Format the content (specific)
            $content = $this->formatContent($data, $report, $options);

            // Step 4: Apply template (shared)
            $finalContent = $this->applyTemplate($content, $report);

            // Step 5: Generate file (specific)
            $filePath = $this->generateFile($finalContent, $report, $options);

            // Step 6: Log (shared)
            $this->logGeneration($report, $startTime);

            return new ReportResult(
                content: file_get_contents($filePath) ?: '',
                filename: $this->generateFilename($report) . '.' . $this->getFileExtension(),
                mimeType: $this->getMimeType(),
                size: filesize($filePath),
                tempPath: $filePath,
                metadata: array_merge($this->metadata, [
                    'format' => $this->getFormat(),
                    'generated_at' => now()->toIso8601String(),
                    'generation_time' => round(microtime(true) - $startTime, 2),
                ])
            );
        } catch (\Exception $e) {
            Log::error('Report generation failed', [
                'report_id' => $report->id,
                'format' => $this->getFormat(),
                'error' => $e->getMessage(),
            ]);
            throw $e;
        }
    }

    // Shared implementation
    protected function fetchData(Report $report, array $options): array
    {
        // Cache the data
        $cacheKey = "report_data_{$report->id}";

        if ($options['use_cache'] ?? true) {
            return cache()->remember($cacheKey, 3600, function () use ($report) {
                return $this->getReportData($report);
            });
        }

        return $this->getReportData($report);
    }

    protected function prepareHeaders(Report $report): void
    {
        $this->headers = [
            'title' => $report->title,
            'generated_at' => now()->format('Y-m-d H:i:s'),
            'company_name' => config('app.name'),
            'report_type' => $report->type,
        ];
    }

    protected function applyTemplate(string $content, Report $report): string
    {
        // Shared template wrapping
        $template = view('reports.template', [
            'content' => $content,
            'headers' => $this->headers,
            'footers' => $this->footers,
            'report' => $report,
        ]);

        return $template->render();
    }

    protected function logGeneration(Report $report, float $startTime): void
    {
        Log::info('Report generated', [
            'report_id' => $report->id,
            'format' => $this->getFormat(),
            'time' => round(microtime(true) - $startTime, 2),
        ]);
    }

    protected function generateFilename(Report $report): string
    {
        $safeTitle = strtolower(str_replace(' ', '_', $report->title));
        return "{$safeTitle}_{$report->id}_" . date('Ymd_His');
    }

    // Abstract methods (must be implemented by concrete classes)
    abstract protected function getReportData(Report $report): array;
    abstract protected function formatContent(array $data, Report $report, array $options): string;
    abstract protected function generateFile(string $content, Report $report, array $options): string;
    abstract public function getFormat(): string;
    abstract public function getMimeType(): string;
    abstract public function getFileExtension(): string;
    abstract public function supports(Report $report): bool;
}

Step 4: Concrete Implementations

// app/Services/Report/PdfReportGenerator.php
namespace App\Services\Report;

use App\Models\Report;
use Dompdf\Dompdf;
use Dompdf\Options;

class PdfReportGenerator extends AbstractReportGenerator
{
    public function __construct(
        protected readonly Dompdf $dompdf,
        protected readonly array $pdfOptions = [],
        string $storageDisk = 'local',
        bool $debug = false
    ) {
        parent::__construct($storageDisk, $debug);

        $options = new Options();
        $options->set('isHtml5ParserEnabled', true);
        $options->set('isRemoteEnabled', true);
        $this->dompdf->setOptions($options);
    }

    protected function getReportData(Report $report): array
    {
        // Fetch specific data for PDF
        return [
            'data' => $report->getData(),
            'totals' => $report->calculateTotals(),
            'charts' => $report->getChartData(),
        ];
    }

    protected function formatContent(array $data, Report $report, array $options): string
    {
        // Render the HTML content
        $view = view($report->getPdfView(), [
            'data' => $data,
            'report' => $report,
            'options' => $options,
        ]);

        return $view->render();
    }

    protected function generateFile(string $content, Report $report, array $options): string
    {
        $this->dompdf->loadHtml($content);
        $this->dompdf->setPaper('A4', 'portrait');
        $this->dompdf->render();

        $output = $this->dompdf->output();

        $tempPath = tempnam(sys_get_temp_dir(), 'report_pdf_');
        file_put_contents($tempPath, $output);

        return $tempPath;
    }

    public function getFormat(): string
    {
        return 'pdf';
    }

    public function getMimeType(): string
    {
        return 'application/pdf';
    }

    public function getFileExtension(): string
    {
        return 'pdf';
    }

    public function supports(Report $report): bool
    {
        return in_array('pdf', $report->supported_formats ?? ['pdf']);
    }
}

// app/Services/Report/ExcelReportGenerator.php
namespace App\Services\Report;

use App\Models\Report;
use PhpOffice\PhpSpreadsheet\Spreadsheet;
use PhpOffice\PhpSpreadsheet\Writer\Xlsx;

class ExcelReportGenerator extends AbstractReportGenerator
{
    protected function getReportData(Report $report): array
    {
        // Fetch Excel-specific data
        return $report->getData();
    }

    protected function formatContent(array $data, Report $report, array $options): string
    {
        $spreadsheet = new Spreadsheet();
        $sheet = $spreadsheet->getActiveSheet();

        // Headers
        $headers = $this->getHeaders($report);
        $col = 'A';
        foreach ($headers as $header) {
            $sheet->setCellValue($col . '1', $header);
            $col++;
        }

        // Data
        $row = 2;
        foreach ($data as $item) {
            $col = 'A';
            foreach ($headers as $key => $header) {
                $value = $item[$key] ?? '';
                $sheet->setCellValue($col . $row, $value);
                $col++;
            }
            $row++;
        }

        // Auto-size columns
        foreach (range('A', $col) as $col) {
            $sheet->getColumnDimension($col)->setAutoSize(true);
        }

        $tempPath = tempnam(sys_get_temp_dir(), 'report_excel_');
        $writer = new Xlsx($spreadsheet);
        $writer->save($tempPath);

        return file_get_contents($tempPath);
    }

    protected function generateFile(string $content, Report $report, array $options): string
    {
        $tempPath = tempnam(sys_get_temp_dir(), 'report_excel_');
        file_put_contents($tempPath, $content);
        return $tempPath;
    }

    protected function getHeaders(Report $report): array
    {
        return $report->getHeaders() ?? ['Column 1', 'Column 2', 'Column 3'];
    }

    public function getFormat(): string
    {
        return 'excel';
    }

    public function getMimeType(): string
    {
        return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
    }

    public function getFileExtension(): string
    {
        return 'xlsx';
    }

    public function supports(Report $report): bool
    {
        return in_array('excel', $report->supported_formats ?? ['pdf', 'excel']);
    }
}

Step 5: Service Provider

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

use App\Contracts\ReportGeneratorInterface;
use App\Services\Report\PdfReportGenerator;
use App\Services\Report\ExcelReportGenerator;
use App\Services\Report\ReportResolver;
use App\Services\ReportService;
use Illuminate\Support\ServiceProvider;

class ReportServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register each generator
        $this->app->tag([
            PdfReportGenerator::class,
            ExcelReportGenerator::class,
        ], 'report_generators');

        $this->app->singleton(ReportResolver::class, function ($app) {
            $resolver = new ReportResolver();

            foreach ($app->tagged('report_generators') as $generator) {
                $resolver->register($generator);
            }

            return $resolver;
        });

        $this->app->singleton(ReportService::class);
    }
}

Step 6: Controller

// app/Http/Controllers/ReportController.php
namespace App\Http\Controllers;

use App\Models\Report;
use App\Services\ReportService;
use Illuminate\Http\Request;

class ReportController extends Controller
{
    public function __construct(
        private readonly ReportService $reportService
    ) {}

    public function generate(Request $request, Report $report)
    {
        $format = $request->input('format', 'pdf');

        if (!$this->reportService->isSupported($format)) {
            return response()->json([
                'error' => "Format '{$format}' is not supported",
            ], 400);
        }

        try {
            $result = $this->reportService->generate($report, $format, [
                'use_cache' => $request->boolean('use_cache', true),
                'include_charts' => $request->boolean('include_charts', true),
            ]);

            return response($result->content)
                ->header('Content-Type', $result->mimeType)
                ->header('Content-Disposition', 'attachment; filename="' . $result->filename . '"')
                ->header('Content-Length', $result->size);

        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }
}

Why This Abstraction Is Powerful

Interface: Defines the contract for all report generators.
Abstract Class: Provides shared logic (data fetching, logging, caching, templating).
Concrete Classes: Each handles a specific format.
Flexibility: Add a new format by creating a new class.
Maintainability: Shared logic is in one place.
Testability: Test each generator and the abstract class separately.

10. SOLID Principles Mapping

D - Dependency Inversion Principle (DIP)

This is the most direct mapping. The ReportController depends on ReportGeneratorInterface (abstraction), not concrete implementations.

class ReportController
{
    public function __construct(
        private readonly ReportGeneratorInterface $generator
    ) {}
}

O - Open/Closed Principle (OCP)

Adding a new format requires creating a new class, not modifying existing code.

// Adding a new JSON format
class JsonReportGenerator extends AbstractReportGenerator { /* ... */ }

// No changes to ReportService or ReportController needed!

L - Liskov Substitution Principle (LSP)

All generators are substitutable for ReportGeneratorInterface. The ReportService works correctly with any of them.

function generate(ReportGeneratorInterface $generator, Report $report)
{
    // Works with any generator
    return $generator->generate($report);
}

I - Interface Segregation Principle (ISP)

The interface is focused on report generation only.

interface ReportGeneratorInterface
{
    public function generate(Report $report, array $options = []): ReportResult;
    // Only generation methods. No extra methods.
}

S - Single Responsibility Principle (SRP)

Each class has a single responsibility:

AbstractReportGenerator: Shared logic.
PdfReportGenerator: PDF-specific logic.
ExcelReportGenerator: Excel-specific logic.

11. Trade-offs

Benefits

Flexibility: Swap implementations without changing client code.
Testability: Mock the interface for unit testing.
Reusability: Shared logic in abstract classes.
Maintainability: Changes are isolated.
Extensibility: Add new implementations without modifying existing ones.
Documentation: Interfaces document the contract.

Costs

Complexity: More files and abstractions.
Indirection: Harder to trace code flow.
Learning Curve: Developers must understand abstraction hierarchies.
Over-Engineering: Unnecessary abstractions can complicate simple code.

When Is Complexity Justified?

Use abstraction when:

You have multiple implementations of the same concept.
The number of implementations is likely to grow.
You need to test implementations in isolation.
You want to adhere to SOLID principles.
You're building a framework or library.

Avoid abstraction when:

You only have one implementation (YAGNI).
The logic is trivial and stable.
The overhead of abstraction doesn't justify the benefit.

12. When NOT To Use It

3 Green Flags (USE ABSTRACTION)

Multiple Implementations: You have 2+ implementations of the same concept.
Likely to Grow: The number of implementations will increase over time.
Need for Testing: You need to mock the dependency for testing.

3 Red Flags (AVOID ABSTRACTION)

Single Implementation: You only have one implementation and it's unlikely to change.

// BAD: Unnecessary abstraction
interface CalculatorInterface { public function add(int $a, int $b): int; }
class Calculator implements CalculatorInterface { public function add(int $a, int $b): int { return $a + $b; } }

Stable Logic: The logic is simple and will never change.
Tightly Coupled Implementations: All implementations share so much logic that the abstraction adds no value.

13. Common Mistakes

1. Creating an Interface for Every Class

// BAD: Interface for everything
interface UserRepositoryInterface { ... }
class UserRepository implements UserRepositoryInterface { ... }

interface UserServiceInterface { ... }
class UserService implements UserServiceInterface { ... }

Problem: You have many interfaces with only one implementation. This is over-engineering.

Fix: Wait until you have a second implementation before creating the interface.

2. Using Abstract Class When Interface Would Suffice

// BAD: Abstract class with no shared logic
abstract class PaymentProcessor
{
    abstract public function process(Order $order): array;
}

// GOOD: Interface (no need for abstract)
interface PaymentProcessor
{
    public function process(Order $order): array;
}

Problem: The abstract class provides no value. It just adds complexity.

Fix: Use an interface when there's no shared logic.

3. Using Interface When Abstract Class Is Needed

// BAD: Interface with no way to share code
interface PaymentInterface
{
    public function charge(): array;
    public function logTransaction(): void; // Every implementation duplicates this!
}

// GOOD: Abstract class with shared logic
abstract class AbstractPayment implements PaymentInterface
{
    public function logTransaction(): void
    {
        // Shared logic once
    }
}

Problem: Every implementation duplicates the logTransaction logic.

Fix: Use an abstract class for shared implementation.

4. Making Abstract Class Too Specific

// BAD: Abstract class with hardcoded assumptions
abstract class AbstractPayment
{
    public function charge(float $amount, array $customer): array
    {
        // Assumes stripe-like behavior
        $intent = $this->createPaymentIntent($amount, $customer);
        return $this->processIntent($intent);
    }

    abstract protected function createPaymentIntent(float $amount, array $customer);
    abstract protected function processIntent($intent);
}

Problem: The abstract class assumes a Stripe-like model. PayPal doesn't work this way.

Fix: Keep abstract classes generic. Let concrete classes handle their own flow.

5. Changing the Interface

// BAD: Changing the interface
interface PaymentInterface
{
    public function charge(): array;  // Removed parameters!
}

// Everything breaks

Problem: Changing the interface breaks all implementations.

Fix: Design interfaces carefully. If you need to change them, consider a new interface or use the Adapter pattern.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is the difference between an interface and an abstract class in PHP?
A: An interface defines a contract with no implementation. An abstract class can provide partial implementation and shared logic.
Q: Can a class implement multiple interfaces? Can it extend multiple abstract classes?
A: Yes, a class can implement multiple interfaces. No, PHP doesn't support multiple inheritance (extending multiple abstract classes).
Q: When would you use an interface instead of an abstract class?
A: When you only need to define a contract, and there's no shared logic to provide.
Q: When would you use an abstract class instead of an interface?
A: When you have shared logic that multiple implementations can reuse, and you want to enforce certain methods.
Q: Does Laravel use interfaces or abstract classes more?
A: Laravel uses both extensively. It uses interfaces for contracts (e.g., Queueable, Authenticatable) and abstract classes for base implementations (e.g., Model, ServiceProvider).

Senior/Architect

Q: Explain the design decision: when to use an interface, an abstract class, or a concrete class.
A: Use an interface when you need a contract that multiple unrelated classes can implement. Use an abstract class when you have a common base with shared logic. Use concrete classes when the logic is specific and not shared.
Q: How do you handle evolving interfaces without breaking existing code?
A: Use default methods (PHP 8+), create a new interface that extends the old one, or use the Adapter pattern to bridge old and new interfaces.
Q: What's the role of abstractions in the Dependency Inversion Principle?
A: DIP states that high-level modules shouldn't depend on low-level modules; both should depend on abstractions. Interfaces are the primary tool for creating these abstractions.
Q: How does Laravel's Service Container interact with interfaces and abstract classes?
A: The Service Container can resolve interfaces to concrete classes using bindings. It can also instantiate abstract classes if they have no abstract methods (or use factories).
Q: What's the difference between an interface and a trait? When would you use each?
A: An interface defines a contract. A trait provides code reuse. Use interfaces for polymorphism (different implementations). Use traits for shared code across unrelated classes (horizontal reuse).

15. Interactive Practice Challenge

The Requirement

You're building a Document Export System for a CMS. The current code is a mess of concrete classes with no abstraction.

The Code (POOR DESIGN)

// No abstraction - everything is concrete
class PdfExporter
{
    private array $config;
    private array $log = [];

    public function __construct(array $config = [])
    {
        $this->config = array_merge([
            'paper_size' => 'A4',
            'orientation' => 'portrait',
            'margin_top' => 10,
            'margin_bottom' => 10,
            'margin_left' => 10,
            'margin_right' => 10,
        ], $config);
    }

    public function export(Document $document): string
    {
        $this->log['start'] = microtime(true);
        $content = $this->generateContent($document);
        $html = $this->wrapWithTemplate($content, $document);
        $pdf = $this->renderPdf($html);
        $this->log['end'] = microtime(true);
        $this->log['size'] = strlen($pdf);

        return $pdf;
    }

    private function generateContent(Document $document): string
    {
        // Generate content specific to PDF
        return view('exports.pdf_content', ['document' => $document])->render();
    }

    private function wrapWithTemplate(string $content, Document $document): string
    {
        // Add headers, footers, styles
        return view('exports.pdf_template', [
            'content' => $content,
            'document' => $document,
            'config' => $this->config,
        ])->render();
    }

    private function renderPdf(string $html): string
    {
        $dompdf = new Dompdf();
        $dompdf->loadHtml($html);
        $dompdf->setPaper($this->config['paper_size'], $this->config['orientation']);
        $dompdf->render();
        return $dompdf->output();
    }

    public function getLog(): array
    {
        return $this->log;
    }
}

class ExcelExporter
{
    private array $config;
    private array $log = [];

    public function __construct(array $config = [])
    {
        $this->config = array_merge([
            'include_headers' => true,
            'auto_size_columns' => true,
            'date_format' => 'Y-m-d',
        ], $config);
    }

    public function export(Document $document): string
    {
        $this->log['start'] = microtime(true);
        $data = $document->getData();
        $spreadsheet = $this->createSpreadsheet($data, $document);
        $file = $this->saveSpreadsheet($spreadsheet);
        $this->log['end'] = microtime(true);
        $this->log['size'] = filesize($file);

        $content = file_get_contents($file);
        unlink($file);

        return $content;
    }

    private function createSpreadsheet(array $data, Document $document): Spreadsheet
    {
        $spreadsheet = new Spreadsheet();
        $sheet = $spreadsheet->getActiveSheet();

        if ($this->config['include_headers']) {
            $headers = $document->getHeaders();
            $col = 'A';
            foreach ($headers as $header) {
                $sheet->setCellValue($col . '1', $header);
                $col++;
            }
        }

        $row = $this->config['include_headers'] ? 2 : 1;
        foreach ($data as $item) {
            $col = 'A';
            foreach ($item as $value) {
                $sheet->setCellValue($col . $row, $value);
                $col++;
            }
            $row++;
        }

        if ($this->config['auto_size_columns']) {
            // Auto-size columns
        }

        return $spreadsheet;
    }

    private function saveSpreadsheet(Spreadsheet $spreadsheet): string
    {
        $tempPath = tempnam(sys_get_temp_dir(), 'export_');
        $writer = new Xlsx($spreadsheet);
        $writer->save($tempPath);
        return $tempPath;
    }

    public function getLog(): array
    {
        return $this->log;
    }
}

class CsvExporter
{
    private array $config;
    private array $log = [];

    public function __construct(array $config = [])
    {
        $this->config = array_merge([
            'delimiter' => ',',
            'enclosure' => '"',
            'escape_char' => '\\',
            'include_headers' => true,
        ], $config);
    }

    public function export(Document $document): string
    {
        $this->log['start'] = microtime(true);
        $data = $document->getData();
        $headers = $document->getHeaders();

        $output = fopen('php://temp', 'r+');

        if ($this->config['include_headers']) {
            fputcsv($output, $headers, $this->config['delimiter'], $this->config['enclosure']);
        }

        foreach ($data as $row) {
            fputcsv($output, $row, $this->config['delimiter'], $this->config['enclosure']);
        }

        rewind($output);
        $content = stream_get_contents($output);
        fclose($output);

        $this->log['end'] = microtime(true);
        $this->log['size'] = strlen($content);

        return $content;
    }

    public function getLog(): array
    {
        return $this->log;
    }
}

// Client code
class DocumentController
{
    public function export(Request $request, Document $document)
    {
        $format = $request->input('format', 'pdf');

        if ($format === 'pdf') {
            $exporter = new PdfExporter($request->input('config', []));
            $content = $exporter->export($document);
            $log = $exporter->getLog();
        } elseif ($format === 'excel') {
            $exporter = new ExcelExporter($request->input('config', []));
            $content = $exporter->export($document);
            $log = $exporter->getLog();
        } elseif ($format === 'csv') {
            $exporter = new CsvExporter($request->input('config', []));
            $content = $exporter->export($document);
            $log = $exporter->getLog();
        } else {
            throw new \Exception("Unsupported format: {$format}");
        }

        // Log the export
        Log::info('Export completed', $log);

        return response($content)
            ->header('Content-Type', $this->getMimeType($format))
            ->header('Content-Disposition', 'attachment; filename="export.' . $this->getExtension($format) . '"');
    }

    private function getMimeType(string $format): string
    {
        return match($format) {
            'pdf' => 'application/pdf',
            'excel' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
            'csv' => 'text/csv',
            default => 'application/octet-stream',
        };
    }

    private function getExtension(string $format): string
    {
        return match($format) {
            'pdf' => 'pdf',
            'excel' => 'xlsx',
            'csv' => 'csv',
            default => 'bin',
        };
    }
}

The Challenges

New requirements are piling up:

"We need to add JSON export for APIs."
"We need to add XML export for legacy systems."
"We need to add HTML export for previews."
"We need to add Markdown export for documentation."
"We need to compress large exports into ZIP files."
"We need to track export metrics (time, size, user) across all formats."
"We need to queue large exports for background processing."

The current code is unmaintainable. Adding a new format requires understanding and duplicating code.

Your Task

Refactor this system using proper abstraction. Specifically:

Define an ExporterInterface with methods like export(), getFormat(), getMimeType(), getExtension(), getLog().
Create an AbstractExporter that provides:
- Shared logging logic.
- Shared metrics tracking.
- Shared configuration handling.
- Shared file handling (temp files, cleanup).
Implement concrete exporters for PDF, Excel, CSV.
Add support for JSON, XML, HTML, and Markdown by implementing new exporters.
Build a ExporterResolver that resolves the right exporter for a given format.
Create a ExportService that:
- Uses the resolver.
- Handles queueing for large exports.
- Tracks metrics.
Update the controller to use the new abstraction.

Questions to Consider

What should the ExporterInterface look like?
What shared logic belongs in the abstract class?
How should you handle different configurations per format?
How do you track metrics without duplicating code?
How do you handle queuing without coupling to the export logic?
How do you test each exporter independently?

(We won't provide the solution—refactor this code and master abstraction!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Abstraction is the process of hiding implementation details and exposing only essential features through contracts (interfaces) and shared logic (abstract classes).
One-sentence intuition: Interfaces say what an object can do. Abstract classes help with how it does it. One is a contract, the other is a starter kit.
One-sentence decision rule: Use an interface to define a contract for multiple implementations. Use an abstract class when you have shared logic that multiple implementations can reuse.

17. Related Concepts

SOLID Principles

Dependency Inversion: Abstractions (interfaces) enable DIP.
Open/Closed: Abstractions enable extension without modification.
Liskov Substitution: Interfaces and abstract classes enforce substitutability.

Design Patterns

Strategy Pattern: Uses interfaces for interchangeable algorithms.
Template Method Pattern: Uses abstract classes for shared flow.
Factory Pattern: Creates abstracted objects.
Adapter Pattern: Bridges different interfaces.
Bridge Pattern: Separates abstraction from implementation.

Laravel Internals

Service Container: Resolves abstractions to concretions.
Service Providers: Register bindings between interfaces and concrete classes.
Contracts: Laravel's interfaces for framework services.
Facades: Static access to abstracted services.
Eloquent: Abstract class (Model) with interfaces.

Enterprise Patterns

Repository Pattern: Abstractions for data access.
Service Layer Pattern: Abstractions for business logic.
Data Mapper Pattern: Abstracts database interactions.
DAO Pattern: Abstracts data access.

Final Thoughts

Interfaces and abstract classes are the foundation of abstraction in object-oriented programming. They serve different but complementary purposes:

Interfaces define contracts. They ensure consistency across implementations.
Abstract classes provide shared logic. They reduce duplication and enforce structure.

Understanding when to use each is a hallmark of senior-level design. Use interfaces when you need a contract. Use abstract classes when you have shared logic. Use both when you need both.

Remember: Abstraction isn't about complexity. It's about clarity. It's about making your code easier to understand, extend, and maintain.

Github: Abstraction Practice Labs

Kill Your Conditionals: Mastering Polymorphism in PHP & Laravel

Anas Hussain — Sun, 26 Jul 2026 11:39:01 +0000

1. Hook & Problem Statement

You've seen it. You've written it. We all have.

public function processPayment(Order $order)
{
    if ($order->payment_method === 'stripe') {
        // 50 lines of Stripe-specific code
    } elseif ($order->payment_method === 'paypal') {
        // 50 lines of PayPal-specific code
    } elseif ($order->payment_method === 'bank_transfer') {
        // 50 lines of bank transfer code
    } elseif ($order->payment_method === 'crypto') {
        // 50 lines of cryptocurrency code
    } else {
        throw new Exception('Unknown payment method');
    }
}

It starts small. Two payment methods. Then three. Then five. Before you know it, your method is 500 lines long. Adding a new payment method means touching this file, understanding all the existing logic, and hoping you don't break anything.

The pain compounds:

Readability is dead: Nobody can understand this method.
Testing is a nightmare: You need to test every branch.
Changing one method affects all: A bug in Stripe logic requires redeploying the entire controller.
Open/Closed Principle violation: To add a new payment method, you must modify existing code.

This is the Conditional Apocalypse. And it's all because developers don't understand one of the fundamental pillars of object-oriented programming: Polymorphism.

2. Why This Pattern/Concept Exists

The Software Engineering Problem It Solves

Polymorphism solves the problem of variability in behavior. When you have multiple implementations of the same concept (e.g., payment processing, notification sending, file storage), you need a way to treat them uniformly while allowing each to behave differently.

The Pain That Existed Before

Before polymorphism (or in codebases that don't use it), developers used:

Massive Conditionals: if-elseif-else blocks that grew endlessly.
Switch Statements: The same problem, different syntax.
Case-Based Logic: "Type checking" with instanceof or string comparisons.

These approaches had severe problems:

Duplication: Similar logic was copy-pasted across conditional branches.
Fragility: Adding a new type meant modifying many files.
Single Responsibility Violation: A single class handled many variations.
Testing Complexity: Every conditional branch needed testing.

Why Large Applications Need It

As applications grow, the number of variations increases. A simple sendNotification() method might need to handle email, SMS, push notifications, Slack, webhooks, and more.

With polymorphism:

New variations are additive, not disruptive.
Each variation is isolated, reducing bugs.
Testing is focused, not combinatorial.
Changes are localized, not global.

The core insight: Instead of asking "what type is this?" and then deciding what to do, you simply tell the object to do it. The object knows its own type and behaves accordingly.

3. Real World Analogy

The Universal Remote Control

Imagine a universal remote that controls different devices: TV, sound system, streaming box, DVD player.

The Non-Polymorphic Remote:

It has a giant button panel with different buttons for each device.
To turn on the TV, you press "Power" but you have to remember which mode you're in.
To change volume, you press different buttons depending on the device.
Adding a new device requires redesigning the entire remote.

The Polymorphic Remote:

It has simple, universal buttons: Power, Volume Up, Volume Down, Play, Pause, Stop.
You point it at a device and press "Power." The device turns on.
You press "Volume Up." The device adjusts its volume.
Adding a new device (a projector) doesn't require changing the remote—just making a "Projector" that understands the same button presses.

Analogy Mapping:

Remote Control: The calling code (e.g., PaymentProcessor).
Universal Buttons: The interface methods (pay(), refund()).
Devices: The concrete implementations (StripePayment, PayPalPayment).
Pointing at the Device: Dependency injection (giving the remote the device).
Adding a new device: Creating a new class that implements the interface.

Why it works: The remote doesn't need to know about different device types. It just sends the same signal, and the device responds appropriately. This is polymorphism in action.

4. The Pain (Bad Design)

Let's look at a classic example of conditional hell in a Laravel application.

namespace App\Services;

use App\Models\Order;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;

class PaymentService
{
    public function processPayment(Order $order): array
    {
        $result = ['status' => 'failed', 'message' => ''];

        // Check payment method
        if ($order->payment_method === 'stripe') {
            // Stripe-specific setup
            $stripe = new \Stripe\StripeClient(config('services.stripe.secret'));

            try {
                $intent = $stripe->paymentIntents->create([
                    'amount' => $order->total * 100,
                    'currency' => $order->currency,
                    'payment_method' => $order->payment_method_id,
                    'confirmation_method' => 'manual',
                    'confirm' => true,
                ]);

                if ($intent->status === 'requires_action') {
                    $result['status'] = 'requires_action';
                    $result['client_secret'] = $intent->client_secret;
                } elseif ($intent->status === 'succeeded') {
                    $result['status'] = 'succeeded';
                    $order->status = 'paid';
                    $order->payment_intent_id = $intent->id;
                    $order->save();

                    // Send confirmation email
                    Mail::to($order->user->email)->send(new OrderConfirmation($order));

                    Log::info('Payment succeeded', ['order' => $order->id]);
                } else {
                    $result['message'] = 'Payment failed: ' . $intent->status;
                }
            } catch (\Exception $e) {
                $result['message'] = 'Stripe error: ' . $e->getMessage();
                Log::error('Stripe payment failed', ['error' => $e->getMessage()]);
            }

        } elseif ($order->payment_method === 'paypal') {
            // PayPal-specific setup
            $clientId = config('services.paypal.client_id');
            $clientSecret = config('services.paypal.secret');
            $apiContext = new \PayPal\Rest\ApiContext(
                new \PayPal\Auth\OAuthTokenCredential($clientId, $clientSecret)
            );

            try {
                $payment = new \PayPal\Api\Payment();
                $payment->setIntent('sale')
                    ->setPayer(['payment_method' => 'paypal'])
                    ->setTransactions([[
                        'amount' => [
                            'total' => $order->total,
                            'currency' => $order->currency,
                        ],
                        'description' => "Order #{$order->id}",
                    ]])
                    ->setRedirectUrls([
                        'return_url' => route('paypal.success', ['order' => $order->id]),
                        'cancel_url' => route('paypal.cancel', ['order' => $order->id]),
                    ]);

                $payment->create($apiContext);

                // Get approval URL
                foreach ($payment->getLinks() as $link) {
                    if ($link->getRel() === 'approval_url') {
                        $result['status'] = 'redirect';
                        $result['url'] = $link->getHref();
                        break;
                    }
                }

                $order->payment_intent_id = $payment->getId();
                $order->save();

            } catch (\Exception $e) {
                $result['message'] = 'PayPal error: ' . $e->getMessage();
                Log::error('PayPal payment failed', ['error' => $e->getMessage()]);
            }

        } elseif ($order->payment_method === 'bank_transfer') {
            // Bank transfer specific logic
            $reference = 'ORD-' . $order->id . '-' . time();

            $result['status'] = 'pending';
            $result['reference'] = $reference;
            $result['instructions'] = [
                'bank_name' => 'Example Bank',
                'account_name' => 'Company Name',
                'account_number' => '12345678',
                'reference' => $reference,
                'amount' => $order->total,
            ];

            $order->payment_reference = $reference;
            $order->status = 'pending_payment';
            $order->save();

            // Send instructions email
            Mail::to($order->user->email)->send(new BankTransferInstructions($order));

        } elseif ($order->payment_method === 'crypto') {
            // Crypto-specific logic
            $cryptoService = new CryptoPaymentService();
            $address = $cryptoService->generateAddress($order->id);

            $result['status'] = 'pending';
            $result['address'] = $address;
            $result['amount'] = $order->total / $cryptoService->getCurrentRate();

            $order->crypto_address = $address;
            $order->status = 'pending_payment';
            $order->save();

        } else {
            throw new \Exception('Unsupported payment method: ' . $order->payment_method);
        }

        return $result;
    }
}

Why This Is Terrible

500+ Lines: The method is unreadable and untestable.
Violates SRP: The class handles Stripe, PayPal, bank transfers, AND crypto.
Violates OCP: Adding a new method requires modifying PaymentService.
Violates DIP: The class depends on concrete implementations (StripeClient, PayPal API).
Difficult Testing: Testing Stripe requires mocking PayPal, bank transfer, and crypto logic.
Duplication: Similar concerns (logging, email sending) are repeated.
Cognitive Overhead: Understanding the entire method is nearly impossible.

Why Developers Write Code Like This

We write code like this because:

It's the path of least resistance.
We're not thinking about extensibility.
We think "just one more method" won't hurt.
We haven't internalized the power of polymorphism.
We don't design for the future.

5. Solution Overview

Polymorphism (from Greek: "many forms") is the ability of objects of different types to respond to the same interface (method) in different ways.

Core Idea

Instead of conditionally checking what type of object you have and then performing different logic, you define a common interface, implement it in multiple classes, and let the object itself decide how to behave.

Main Participants

The Interface (Contract): Defines the methods that all variations must implement.
The Concrete Implementations: Each class implements the interface in its own way.
The Client: The code that uses the interface, not the concrete implementations.
The Factory/Resolver: Determines which implementation to use (often via the Service Container).

How Objects Collaborate

Instead of:

if ($type === 'stripe') {
    // Stripe logic
} elseif ($type === 'paypal') {
    // PayPal logic
}

You write:

$paymentProcessor = app(PaymentProcessorInterface::class);
$result = $paymentProcessor->process($order);

The PaymentProcessor is resolved based on the order's payment method. The client code doesn't know which implementation it's using.

Mental Model

Think of polymorphism as a shape-shifter.

Without Polymorphism: You have to ask "what are you?" before deciding how to interact.
With Polymorphism: You don't ask. You just interact. The object responds appropriately based on its true nature.

You don't ask a dog "are you a cat?" before telling it to bark. You just tell it to bark. If it's a dog, it barks. If it's a cat, it meows. The speak() method is polymorphic.

Benefits

Extensibility: Add new variations without changing existing code.
Isolation: Each variation is in its own class.
Testability: Test each implementation in isolation.
Readability: The client code is clean and focused.
Single Responsibility: Each class handles one variation.

Trade-offs

More Classes: You'll create many small classes instead of one large one.
Indirection: It's harder to see "all the code" in one place.
Learning Curve: Developers need to understand interface-based design.

6. UML Diagram

Laravel Polymorphism Mermaid Diagram

Diagram Explanation

PaymentProcessorInterface defines the contract.
Concrete implementations each handle a specific payment method.
PaymentService depends on the interface, not the concrete classes.
PaymentProcessorFactory determines which implementation to use.
The client code calls PaymentService, which delegates to the appropriate processor.

7. Vanilla PHP Example

Let's refactor the payment system using polymorphism.

Before Refactoring (Massive Conditionals)

// The terrible 500-line PaymentService (shown above)

After Refactoring (Polymorphism)

Step 1: Define the Interface

interface PaymentProcessorInterface
{
    public function process(Order $order): array;
    public function refund(Order $order, float $amount): array;
    public function cancel(Order $order): bool;
    public function supports(Order $order): bool;
}

Step 2: Implement Each Variation

// StripePaymentProcessor.php
class StripePaymentProcessor implements PaymentProcessorInterface
{
    private \Stripe\StripeClient $stripe;

    public function __construct()
    {
        $this->stripe = new \Stripe\StripeClient(config('services.stripe.secret'));
    }

    public function process(Order $order): array
    {
        try {
            $intent = $this->stripe->paymentIntents->create([
                'amount' => $order->total * 100,
                'currency' => $order->currency,
                'payment_method' => $order->payment_method_id,
                'confirmation_method' => 'manual',
                'confirm' => true,
            ]);

            $result = ['status' => 'failed'];

            if ($intent->status === 'requires_action') {
                $result = [
                    'status' => 'requires_action',
                    'client_secret' => $intent->client_secret,
                ];
            } elseif ($intent->status === 'succeeded') {
                $result = [
                    'status' => 'succeeded',
                    'payment_intent_id' => $intent->id,
                ];
            }

            return $result;

        } catch (\Exception $e) {
            throw new \Exception('Stripe error: ' . $e->getMessage());
        }
    }

    public function refund(Order $order, float $amount): array
    {
        $refund = $this->stripe->refunds->create([
            'payment_intent' => $order->payment_intent_id,
            'amount' => (int)($amount * 100),
        ]);

        return ['status' => $refund->status, 'refund_id' => $refund->id];
    }

    public function cancel(Order $order): bool
    {
        if (!$order->payment_intent_id) {
            return false;
        }

        $intent = $this->stripe->paymentIntents->cancel($order->payment_intent_id);
        return $intent->status === 'canceled';
    }

    public function supports(Order $order): bool
    {
        return $order->payment_method === 'stripe';
    }
}

// PayPalPaymentProcessor.php
class PayPalPaymentProcessor implements PaymentProcessorInterface
{
    private \PayPal\Rest\ApiContext $apiContext;

    public function __construct()
    {
        $clientId = config('services.paypal.client_id');
        $clientSecret = config('services.paypal.secret');

        $this->apiContext = new \PayPal\Rest\ApiContext(
            new \PayPal\Auth\OAuthTokenCredential($clientId, $clientSecret)
        );
    }

    public function process(Order $order): array
    {
        try {
            $payment = new \PayPal\Api\Payment();
            $payment->setIntent('sale')
                ->setPayer(['payment_method' => 'paypal'])
                ->setTransactions([[
                    'amount' => [
                        'total' => $order->total,
                        'currency' => $order->currency,
                    ],
                    'description' => "Order #{$order->id}",
                ]])
                ->setRedirectUrls([
                    'return_url' => route('paypal.success', ['order' => $order->id]),
                    'cancel_url' => route('paypal.cancel', ['order' => $order->id]),
                ]);

            $payment->create($this->apiContext);

            $result = ['status' => 'failed'];

            foreach ($payment->getLinks() as $link) {
                if ($link->getRel() === 'approval_url') {
                    $result = [
                        'status' => 'redirect',
                        'url' => $link->getHref(),
                        'payment_intent_id' => $payment->getId(),
                    ];
                    break;
                }
            }

            return $result;

        } catch (\Exception $e) {
            throw new \Exception('PayPal error: ' . $e->getMessage());
        }
    }

    public function refund(Order $order, float $amount): array
    {
        // PayPal refund logic
        $refund = new \PayPal\Api\Refund();
        $refund->setAmount([
            'total' => $amount,
            'currency' => $order->currency,
        ]);

        // Execute refund
        $sale = new \PayPal\Api\Sale();
        $sale->setId($order->payment_intent_id);
        $refunded = $sale->refund($refund, $this->apiContext);

        return ['status' => $refunded->getState(), 'refund_id' => $refunded->getId()];
    }

    public function cancel(Order $order): bool
    {
        // PayPal cancellation via voiding authorization
        return true; // Simplified
    }

    public function supports(Order $order): bool
    {
        return $order->payment_method === 'paypal';
    }
}

// BankTransferProcessor.php
class BankTransferProcessor implements PaymentProcessorInterface
{
    public function process(Order $order): array
    {
        $reference = 'ORD-' . $order->id . '-' . time();

        return [
            'status' => 'pending',
            'reference' => $reference,
            'instructions' => [
                'bank_name' => 'Example Bank',
                'account_name' => 'Company Name',
                'account_number' => '12345678',
                'reference' => $reference,
                'amount' => $order->total,
            ],
        ];
    }

    public function refund(Order $order, float $amount): array
    {
        // Bank transfers are usually manual refunds
        return ['status' => 'manual_refund_required'];
    }

    public function cancel(Order $order): bool
    {
        return true; // Bank transfers can always be cancelled
    }

    public function supports(Order $order): bool
    {
        return $order->payment_method === 'bank_transfer';
    }
}

// CryptoPaymentProcessor.php
class CryptoPaymentProcessor implements PaymentProcessorInterface
{
    private CryptoService $cryptoService;

    public function __construct(CryptoService $cryptoService)
    {
        $this->cryptoService = $cryptoService;
    }

    public function process(Order $order): array
    {
        $address = $this->cryptoService->generateAddress($order->id);
        $rate = $this->cryptoService->getCurrentRate();

        return [
            'status' => 'pending',
            'address' => $address,
            'amount' => $order->total / $rate,
            'currency' => 'BTC',
        ];
    }

    public function refund(Order $order, float $amount): array
    {
        // Crypto refund via address lookup
        return ['status' => 'manual_refund_required'];
    }

    public function cancel(Order $order): bool
    {
        return true;
    }

    public function supports(Order $order): bool
    {
        return $order->payment_method === 'crypto';
    }
}

Step 3: The Factory (Resolver)

class PaymentProcessorFactory
{
    private array $processors;

    public function __construct(array $processors)
    {
        $this->processors = $processors;
    }

    public function make(Order $order): PaymentProcessorInterface
    {
        foreach ($this->processors as $processor) {
            if ($processor->supports($order)) {
                return $processor;
            }
        }

        throw new \Exception('No payment processor found for order');
    }
}

// Or with dependency injection in Laravel:
class PaymentProcessorResolver
{
    private array $processors;

    public function registerProcessor(PaymentProcessorInterface $processor): void
    {
        $this->processors[] = $processor;
    }

    public function resolve(Order $order): PaymentProcessorInterface
    {
        foreach ($this->processors as $processor) {
            if ($processor->supports($order)) {
                return $processor;
            }
        }

        throw new \Exception("Unsupported payment method: {$order->payment_method}");
    }
}

Step 4: The Client Code

class PaymentService
{
    private PaymentProcessorResolver $resolver;
    private MailService $mailService;
    private LoggerInterface $logger;

    public function __construct(
        PaymentProcessorResolver $resolver,
        MailService $mailService,
        LoggerInterface $logger
    ) {
        $this->resolver = $resolver;
        $this->mailService = $mailService;
        $this->logger = $logger;
    }

    public function processPayment(Order $order): array
    {
        $processor = $this->resolver->resolve($order);

        try {
            $result = $processor->process($order);

            // Handle successful payment logic
            if ($result['status'] === 'succeeded') {
                $order->status = 'paid';
                $order->payment_intent_id = $result['payment_intent_id'] ?? null;
                $order->save();

                $this->mailService->sendConfirmation($order);
                $this->logger->info('Payment succeeded', ['order' => $order->id]);
            } elseif ($result['status'] === 'requires_action') {
                $order->status = 'pending_action';
                $order->save();
            } elseif ($result['status'] === 'pending') {
                $order->status = 'pending_payment';
                $order->save();
                $this->mailService->sendInstructions($order, $result);
            } elseif ($result['status'] === 'redirect') {
                $order->payment_intent_id = $result['payment_intent_id'] ?? null;
                $order->save();
            }

            return $result;

        } catch (\Exception $e) {
            $this->logger->error('Payment processing failed', [
                'order' => $order->id,
                'error' => $e->getMessage(),
            ]);

            return ['status' => 'failed', 'message' => $e->getMessage()];
        }
    }
}

Step 5: Service Provider (Laravel-Specific)

namespace App\Providers;

use App\Services\Payment\PaymentProcessorResolver;
use App\Services\Payment\PaymentProcessorInterface;
use App\Services\Payment\StripePaymentProcessor;
use App\Services\Payment\PayPalPaymentProcessor;
use App\Services\Payment\BankTransferProcessor;
use App\Services\Payment\CryptoPaymentProcessor;
use Illuminate\Support\ServiceProvider;

class PaymentServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register all processors
        $this->app->bind(StripePaymentProcessor::class);
        $this->app->bind(PayPalPaymentProcessor::class);
        $this->app->bind(BankTransferProcessor::class);
        $this->app->bind(CryptoPaymentProcessor::class);

        // Register the resolver
        $this->app->singleton(PaymentProcessorResolver::class, function ($app) {
            $resolver = new PaymentProcessorResolver();

            // Register processors (order matters for priority)
            $resolver->registerProcessor($app->make(StripePaymentProcessor::class));
            $resolver->registerProcessor($app->make(PayPalPaymentProcessor::class));
            $resolver->registerProcessor($app->make(BankTransferProcessor::class));
            $resolver->registerProcessor($app->make(CryptoPaymentProcessor::class));

            return $resolver;
        });
    }
}

What We Improved

Zero Conditionals: The client code has no if-elseif blocks.
Open/Closed: Add a new processor by creating a class, no modifications needed.
Single Responsibility: Each processor handles one payment method.
Testability: Test StripeProcessor without PayPal logic.
Readability: The client code is clean and focused.
Extensibility: New methods (e.g., getStatus()) can be added to the interface.

8. Laravel Internal Example

Laravel uses polymorphism everywhere. Let's look at some key examples.

Authentication Guards (Multiple Auth Methods)

Laravel's authentication system uses polymorphism to support different guard types (session, token, JWT, etc.).

// Illuminate\Contracts\Auth\Guard
interface Guard
{
    public function check(): bool;
    public function guest(): bool;
    public function user(): ?Authenticatable;
    public function id(): ?int;
    public function validate(array $credentials = []): bool;
    public function setUser(Authenticatable $user): static;
}

// SessionGuard (one implementation)
class SessionGuard implements Guard
{
    // Session-based authentication
}

// TokenGuard (another implementation)
class TokenGuard implements Guard
{
    // Token-based authentication (API)
}

// The AuthManager creates the right guard
class AuthManager
{
    public function guard(?string $name = null)
    {
        $name = $name ?: $this->getDefaultDriver();

        if (isset($this->guards[$name])) {
            return $this->guards[$name];
        }

        return $this->guards[$name] = $this->resolve($name);
    }
}

Why This Is Elegant:

Your code uses Auth::guard()->user() regardless of the guard type.
Adding a new guard (e.g., JWT) doesn't affect existing code.
Each guard is isolated and testable.

Filesystem Drivers (Multiple Storage Services)

Laravel's Filesystem uses polymorphism to support local, S3, FTP, and other storage providers.

// Illuminate\Contracts\Filesystem\Filesystem
interface Filesystem
{
    public function exists(string $path): bool;
    public function get(string $path): string;
    public function put(string $path, $contents, $options = []): bool;
    public function delete(string|array $paths): bool;
    // ... more methods
}

// LocalFilesystem (one implementation)
class LocalFilesystem implements Filesystem { /* ... */ }

// S3Filesystem (another implementation)
class S3Filesystem implements Filesystem { /* ... */ }

// Usage: Same interface, different implementations
Storage::disk('local')->put('file.txt', 'content');
Storage::disk('s3')->put('file.txt', 'content');

Why This Is Elegant:

Your code uses Storage::disk('s3')->put() regardless of the driver.
Adding a new driver (e.g., Google Cloud Storage) is just a new class.
The interface ensures consistency.

Queue Drivers (Multiple Queue Systems)

Laravel's Queue system uses polymorphism to support database, Redis, SQS, and beanstalkd.

// Illuminate\Contracts\Queue\Queue
interface Queue
{
    public function push($job, $data = '', $queue = null);
    public function later($delay, $job, $data = '', $queue = null);
    public function pop($queue = null);
}

// DatabaseQueue
class DatabaseQueue implements Queue { /* ... */ }

// RedisQueue
class RedisQueue implements Queue { /* ... */ }

// SqsQueue
class SqsQueue implements Queue { /* ... */ }

Why This Is Elegant:

Queue::push() works the same regardless of the driver.
Switching from Redis to SQS is a configuration change.
Each driver handles its own specific logic.

Middleware Pipeline (Chain of Responsibility with Polymorphism)

The middleware pipeline is a perfect example of polymorphic behavior.

// Each middleware implements the same interface
interface Middleware
{
    public function handle($request, Closure $next);
}

// Different middleware implementations
class Authenticate implements Middleware { /* ... */ }
class TrimStrings implements Middleware { /* ... */ }
class EncryptCookies implements Middleware { /* ... */ }

// The pipeline treats them uniformly
$response = (new Pipeline($container))
    ->send($request)
    ->through([Authenticate::class, TrimStrings::class])
    ->then(function ($request) {
        return $controller->handle($request);
    });

Why This Is Elegant:

The pipeline doesn't care what each middleware does.
Adding a new middleware is just adding a new class.
Each middleware is independent.

Notifications System (Multiple Channels)

Laravel's notifications use polymorphism to support different channels.

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        return ['mail', 'database', 'broadcast', 'slack'];
    }

    public function toMail($notifiable): MailMessage
    {
        // Returns a mail message
    }

    public function toDatabase($notifiable): array
    {
        // Returns database data
    }

    public function toSlack($notifiable): SlackMessage
    {
        // Returns a Slack message
    }
}

Why This Is Elegant:

You define channel-specific logic in separate methods.
The notification system decides which methods to call.
Adding a new channel doesn't affect existing notifications.

9. Real Laravel Application Example

Let's build a Document Export System that handles different export formats (PDF, Excel, CSV, XML) using polymorphism.

Scenario

Your application needs to export reports, invoices, and user data in multiple formats. Each format has different rendering requirements, file structures, and constraints.

Implementation

Step 1: Define the Interface

// app/Contracts/Export/ExportInterface.php
namespace App\Contracts\Export;

use App\Models\Exportable;

interface ExportInterface
{
    public function export(Exportable $data, array $options = []): ExportResult;
    public function getMimeType(): string;
    public function getFileExtension(): string;
    public function supports(string $format): bool;
    public function getChunkSize(): int;
}

Step 2: Create a Result DTO

// app/DTO/ExportResult.php
namespace App\DTO;

class ExportResult
{
    public function __construct(
        public readonly string $content,
        public readonly string $filename,
        public readonly string $mimeType,
        public readonly int $size,
        public readonly ?string $tempPath = null,
        public readonly array $metadata = []
    ) {}
}

Step 3: Implement Each Format

// app/Services/Export/PdfExporter.php
namespace App\Services\Export;

use App\Contracts\Export\ExportInterface;
use App\DTO\ExportResult;
use App\Models\Exportable;
use Dompdf\Dompdf;

class PdfExporter implements ExportInterface
{
    private Dompdf $dompdf;

    public function __construct(Dompdf $dompdf)
    {
        $this->dompdf = $dompdf;
    }

    public function export(Exportable $data, array $options = []): ExportResult
    {
        // Generate HTML from the data
        $html = $this->generateHtml($data, $options);

        $this->dompdf->loadHtml($html);
        $this->dompdf->setPaper('A4', 'portrait');
        $this->dompdf->render();

        $content = $this->dompdf->output();

        return new ExportResult(
            content: $content,
            filename: $this->generateFilename($data) . '.pdf',
            mimeType: $this->getMimeType(),
            size: strlen($content),
            metadata: ['pages' => $this->dompdf->getPaper()],
        );
    }

    public function getMimeType(): string
    {
        return 'application/pdf';
    }

    public function getFileExtension(): string
    {
        return 'pdf';
    }

    public function supports(string $format): bool
    {
        return in_array($format, ['pdf', 'PDF', 'application/pdf']);
    }

    public function getChunkSize(): int
    {
        return 50; // Process 50 items at a time
    }

    private function generateHtml(Exportable $data, array $options): string
    {
        // Generate HTML for PDF rendering
        $view = view($data->getExportView(), ['data' => $data, 'options' => $options]);
        return $view->render();
    }

    private function generateFilename(Exportable $data): string
    {
        return 'export_' . $data->getExportId() . '_' . date('Ymd_His');
    }
}

// app/Services/Export/ExcelExporter.php
namespace App\Services\Export;

use App\Contracts\Export\ExportInterface;
use App\DTO\ExportResult;
use App\Models\Exportable;
use PhpOffice\PhpSpreadsheet\Spreadsheet;
use PhpOffice\PhpSpreadsheet\Writer\Xlsx;

class ExcelExporter implements ExportInterface
{
    public function export(Exportable $data, array $options = []): ExportResult
    {
        $spreadsheet = new Spreadsheet();
        $sheet = $spreadsheet->getActiveSheet();

        // Headers
        $headers = $data->getExportHeaders();
        $column = 'A';
        foreach ($headers as $header) {
            $sheet->setCellValue($column . '1', $header);
            $column++;
        }

        // Data rows
        $row = 2;
        foreach ($data->getExportData() as $item) {
            $column = 'A';
            foreach ($headers as $key => $header) {
                $value = $item[$key] ?? '';
                $sheet->setCellValue($column . $row, $value);
                $column++;
            }
            $row++;
        }

        // Auto-size columns
        foreach (range('A', $column) as $col) {
            $sheet->getColumnDimension($col)->setAutoSize(true);
        }

        // Save to temp file
        $tempPath = tempnam(sys_get_temp_dir(), 'export_');
        $writer = new Xlsx($spreadsheet);
        $writer->save($tempPath);

        $content = file_get_contents($tempPath);

        return new ExportResult(
            content: $content,
            filename: $this->generateFilename($data) . '.xlsx',
            mimeType: $this->getMimeType(),
            size: filesize($tempPath),
            tempPath: $tempPath,
        );
    }

    public function getMimeType(): string
    {
        return 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
    }

    public function getFileExtension(): string
    {
        return 'xlsx';
    }

    public function supports(string $format): bool
    {
        return in_array($format, ['excel', 'xlsx', 'xls']);
    }

    public function getChunkSize(): int
    {
        return 1000;
    }

    private function generateFilename(Exportable $data): string
    {
        return 'export_' . $data->getExportId() . '_' . date('Ymd_His');
    }
}

// app/Services/Export/CsvExporter.php
namespace App\Services\Export;

use App\Contracts\Export\ExportInterface;
use App\DTO\ExportResult;
use App\Models\Exportable;

class CsvExporter implements ExportInterface
{
    public function export(Exportable $data, array $options = []): ExportResult
    {
        $output = fopen('php://temp', 'r+');

        // Write headers
        $headers = $data->getExportHeaders();
        fputcsv($output, $headers);

        // Write data
        foreach ($data->getExportData() as $item) {
            $row = [];
            foreach ($headers as $key => $header) {
                $row[] = $item[$key] ?? '';
            }
            fputcsv($output, $row);
        }

        rewind($output);
        $content = stream_get_contents($output);
        fclose($output);

        return new ExportResult(
            content: $content,
            filename: $this->generateFilename($data) . '.csv',
            mimeType: $this->getMimeType(),
            size: strlen($content),
            metadata: ['rows' => count($data->getExportData())],
        );
    }

    public function getMimeType(): string
    {
        return 'text/csv';
    }

    public function getFileExtension(): string
    {
        return 'csv';
    }

    public function supports(string $format): bool
    {
        return in_array($format, ['csv', 'CSV']);
    }

    public function getChunkSize(): int
    {
        return 10000;
    }

    private function generateFilename(Exportable $data): string
    {
        return 'export_' . $data->getExportId() . '_' . date('Ymd_His');
    }
}

Step 4: The Export Service (Client Code)

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

use App\Contracts\Export\ExportInterface;
use App\DTO\ExportResult;
use App\Models\Exportable;
use App\Services\Export\ExportResolver;
use Illuminate\Support\Facades\Log;

class ExportService
{
    private ExportResolver $resolver;

    public function __construct(ExportResolver $resolver)
    {
        $this->resolver = $resolver;
    }

    public function export(Exportable $data, string $format, array $options = []): ExportResult
    {
        $exporter = $this->resolver->resolve($format);

        try {
            $result = $exporter->export($data, $options);

            Log::info('Export completed', [
                'format' => $format,
                'filename' => $result->filename,
                'size' => $result->size,
            ]);

            return $result;

        } catch (\Exception $e) {
            Log::error('Export failed', [
                'format' => $format,
                'error' => $e->getMessage(),
            ]);

            throw $e;
        }
    }

    public function isSupported(string $format): bool
    {
        try {
            $this->resolver->resolve($format);
            return true;
        } catch (\Exception $e) {
            return false;
        }
    }
}

// app/Services/Export/ExportResolver.php
namespace App\Services\Export;

use App\Contracts\Export\ExportInterface;

class ExportResolver
{
    private array $exporters;

    public function __construct(array $exporters)
    {
        $this->exporters = $exporters;
    }

    public function resolve(string $format): ExportInterface
    {
        foreach ($this->exporters as $exporter) {
            if ($exporter->supports($format)) {
                return $exporter;
            }
        }

        throw new \Exception("No exporter found for format: {$format}");
    }
}

Step 5: Controller

// app/Http/Controllers/ExportController.php
namespace App\Http\Controllers;

use App\Models\Report;
use App\Services\ExportService;
use Illuminate\Http\Request;

class ExportController extends Controller
{
    public function __construct(
        private ExportService $exportService
    ) {}

    public function export(Request $request, Report $report)
    {
        $format = $request->input('format', 'pdf');

        if (!$this->exportService->isSupported($format)) {
            return response()->json([
                'error' => "Format '{$format}' is not supported",
                'supported' => ['pdf', 'excel', 'csv'],
            ], 400);
        }

        try {
            $result = $this->exportService->export(
                $report,
                $format,
                $request->input('options', [])
            );

            // Clean up temp file if needed
            if ($result->tempPath && file_exists($result->tempPath)) {
                register_shutdown_function(fn() => unlink($result->tempPath));
            }

            return response($result->content)
                ->header('Content-Type', $result->mimeType)
                ->header('Content-Disposition', 'attachment; filename="' . $result->filename . '"')
                ->header('Content-Length', $result->size);

        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 500);
        }
    }

    public function supportedFormats()
    {
        return response()->json([
            'formats' => ['pdf', 'excel', 'csv'],
        ]);
    }
}

Step 6: Service Provider

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

use App\Contracts\Export\ExportInterface;
use App\Services\Export\CsvExporter;
use App\Services\Export\ExcelExporter;
use App\Services\Export\ExportResolver;
use App\Services\Export\PdfExporter;
use App\Services\ExportService;
use Illuminate\Support\ServiceProvider;

class ExportServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register exporters
        $this->app->tag([
            PdfExporter::class,
            ExcelExporter::class,
            CsvExporter::class,
        ], 'exporters');

        $this->app->singleton(ExportResolver::class, function ($app) {
            $exporters = $app->tagged('exporters');

            return new ExportResolver($exporters);
        });

        $this->app->singleton(ExportService::class);
    }
}

Why Polymorphism Wins Here

Extensibility: Adding a new format (XML, JSON, HTML) requires only a new class.
Isolation: Each exporter is independent. A bug in PDF doesn't affect Excel.
Testability: Test each exporter separately with known data.
Configuration: The resolver can prioritize exporters based on context.
Open/Closed: The ExportService never changes when adding a new format.

10. SOLID Principles Mapping

L - Liskov Substitution Principle (LSP)

The Most Direct Mapping

LSP states that objects of a superclass should be replaceable with objects of its subclasses without affecting the program's correctness.

In our payment example:

StripePaymentProcessor, PayPalPaymentProcessor, etc. are all substitutable for PaymentProcessorInterface.
The PaymentService works correctly regardless of which processor is used.
Each processor fulfills the contract of the interface.

// LSP in action
function processPayment(PaymentProcessorInterface $processor, Order $order) {
    return $processor->process($order); // Works with any processor
}

O - Open/Closed Principle (OCP)

OCP states that classes should be open for extension but closed for modification.

Open for extension: Add a new CryptoPaymentProcessor class.
Closed for modification: The PaymentService never changes.

This is the primary benefit of polymorphism. You can add new behavior without touching existing code.

S - Single Responsibility Principle (SRP)

Each payment processor has one responsibility: handling a specific payment method.

StripePaymentProcessor: Only Stripe logic.
PayPalPaymentProcessor: Only PayPal logic.
PaymentService: Only orchestrates the flow.

D - Dependency Inversion Principle (DIP)

High-level modules depend on abstractions, not concretions.

High-level: PaymentService depends on PaymentProcessorInterface.
Low-level: StripePaymentProcessor depends on the same interface (via implementation).

I - Interface Segregation Principle (ISP)

The interface is focused and minimal. It only contains methods that all processors need.

interface PaymentProcessorInterface {
    public function process(Order $order): array;
    public function refund(Order $order, float $amount): array;
    public function cancel(Order $order): bool;
    public function supports(Order $order): bool;
}

If a processor doesn't support refunds, it can still implement the interface (perhaps returning an error). The interface is not bloated with methods irrelevant to some implementations.

11. Trade-offs

Benefits

Extensibility: Add new behaviors without modifying existing code.
Isolation: Changes to one implementation don't affect others.
Testability: Test each implementation independently.
Readability: Client code is clean and focused.
Maintainability: Each variation is in its own file.
Scalability: Teams can work on different implementations simultaneously.

Costs

More Classes: Each variation needs its own class.
Indirection: It's harder to see "all the code" in one place.
Abstraction Overhead: You need to design interfaces carefully.
Learning Curve: Developers must understand interface-based design.
Over-Engineering Risk: Not every conditional needs polymorphism.

When Is Complexity Justified?

Use polymorphism when:

The number of variations is likely to grow.
Variations are independent and unrelated.
You want to adhere to the Open/Closed Principle.
You need to test variations in isolation.
Different teams will work on different variations.

Avoid polymorphism when:

The variations are trivial (e.g., a single-line difference).
The number of variations is small and stable.
The logic is tightly coupled across variations.
Performance is critical (method dispatch overhead).

12. When NOT To Use It

3 Green Flags (USE POLYMORPHISM)

Multiple Implementations: You have 3+ variations of the same concept.
Likely to Grow: The number of variations will increase over time.
Independent Logic: Each variation has significantly different logic.

3 Red Flags (AVOID POLYMORPHISM)

Trivial Variations: The difference is a single configuration value.

// BAD: Over-engineered polymorphism
interface GreetingInterface { public function greet(): string; }
class EnglishGreeting implements GreetingInterface { public function greet(): string { return 'Hello'; } }
class SpanishGreeting implements GreetingInterface { public function greet(): string { return 'Hola'; } }

// GOOD: Simple config
$greeting = match($locale) {
    'en' => 'Hello',
    'es' => 'Hola',
    default => 'Hello',
};

Tightly Coupled Variations: Variations share most logic with small differences. A strategy with config might be better.
Stable Requirements: The number of variations is known and fixed. The extra complexity isn't justified.

13. Common Mistakes

1. Creating Unnecessary Interfaces

// BAD: Interface with only one implementation
interface UserRepositoryInterface { public function find(int $id): User; }
class EloquentUserRepository implements UserRepositoryInterface { /* ... */ }

// If there's only one implementation, why have the interface?
// Wait until you have a second implementation.

Fix: Use the concrete class directly until you need the abstraction.

2. Interface Bloat (Violating ISP)

// BAD: Bloated interface
interface PaymentProcessorInterface
{
    public function process(): array;
    public function refund(): array;
    public function cancel(): bool;
    public function getTransactionHistory(): array;
    public function getBalance(): float;
    public function getStatus(): string;
    public function retry(): bool;
    public function void(): bool;
    public function capture(): bool;
}

// Some processors can't implement all these methods
class BankTransferProcessor implements PaymentProcessorInterface
{
    // Must implement getBalance() even though it doesn't apply
}

Fix: Split into smaller interfaces.

interface PaymentProcessorInterface { /* core */ }
interface RefundableInterface { public function refund(): array; }
interface BalanceCheckInterface { public function getBalance(): float; }

3. Type Checking Instead of Letting Polymorphism Work

// BAD: Type checking
function process($processor, Order $order)
{
    if ($processor instanceof StripeProcessor) {
        // Stripe-specific logic
    } elseif ($processor instanceof PayPalProcessor) {
        // PayPal-specific logic
    }
}

// GOOD: Let polymorphism do its job
function process(PaymentProcessorInterface $processor, Order $order)
{
    return $processor->process($order);
}

Fix: Trust the interface. Don't check types.

4. Hardcoding Dependencies

// BAD: Hardcoding
class PaymentController
{
    public function process(Request $request, Order $order)
    {
        if ($order->payment_method === 'stripe') {
            $processor = new StripePaymentProcessor();
        } else {
            $processor = new PayPalPaymentProcessor();
        }

        // ... use processor
    }
}

Fix: Use dependency injection and the resolver pattern.

5. Over-Engineering Simple Logic

// BAD: Polymorphism for a simple switch
// (See "Trivial Variations" above)

Fix: Use a simple conditional or configuration.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is polymorphism in object-oriented programming?
A: The ability of objects of different types to respond to the same interface in different ways.
Q: What are the two types of polymorphism?
A: Compile-time polymorphism (method overloading, not supported in PHP) and runtime polymorphism (method overriding via interfaces and inheritance).
Q: How does polymorphism differ from inheritance?
A: Inheritance is the "is-a" relationship. Polymorphism is the ability to treat objects of different types uniformly through a common interface.
Q: What is an interface in PHP?
A: A contract that defines which methods a class must implement. Interfaces enable polymorphism by allowing different classes to implement the same methods.
Q: How does Laravel use polymorphism?
A: In authentication guards, filesystem drivers, queue drivers, middleware, and notification channels—all use polymorphism to support multiple implementations.

Senior/Architect

Q: Explain the difference between ad-hoc polymorphism and parametric polymorphism. Which does PHP support?
A: Ad-hoc polymorphism (overloading) allows different behavior based on type. PHP supports this via interfaces and inheritance (runtime polymorphism). Parametric polymorphism (generics) allows types to vary. PHP 8+ supports generics through docblocks but not natively.
Q: How do you decide between polymorphism and a simple conditional?
A: Use polymorphism when the number of variations is likely to grow, the logic is significantly different, and you want to adhere to OCP. Use conditionals for simple, stable variations.
Q: How does the Strategy pattern relate to polymorphism?
A: The Strategy pattern is an implementation of polymorphism. It defines a family of algorithms (strategies), encapsulates each one, and makes them interchangeable.
Q: How would you handle adding a new payment method in the described system?
A: Create a new class implementing PaymentProcessorInterface. Register it in the service provider. No other changes are needed. This demonstrates OCP in action.
Q: What's the difference between polymorphism and the Factory pattern?
A: Polymorphism is the principle of different objects responding to the same interface. The Factory pattern is a creational pattern that creates objects. They often work together: a factory creates polymorphic objects.

15. Interactive Practice Challenge

The Requirement

You're building a Notification Delivery System for your SaaS application. Notifications need to be sent through multiple channels: email, SMS, push notifications, Slack, and webhook.

The current code is a mess of conditionals and duplicated logic. It's becoming unmaintainable.

The Code (POOR DESIGN)

namespace App\Services;

use App\Models\Notification;
use App\Models\User;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;

class NotificationService
{
    public function send(Notification $notification, User $user): array
    {
        $result = ['success' => false, 'channel' => 'none'];

        // Determine which channels to use
        $channels = $user->notification_preferences ?? ['email'];

        foreach ($channels as $channel) {
            if ($channel === 'email') {
                try {
                    Mail::to($user->email)->send(new \App\Mail\NotificationMessage($notification));
                    $result['email'] = ['success' => true];
                    Log::info('Email sent', ['user' => $user->id, 'notification' => $notification->id]);
                } catch (\Exception $e) {
                    $result['email'] = ['success' => false, 'error' => $e->getMessage()];
                    Log::error('Email failed', ['error' => $e->getMessage()]);
                }
            } elseif ($channel === 'sms') {
                try {
                    $twilio = new \Twilio\Rest\Client(
                        config('services.twilio.sid'),
                        config('services.twilio.token')
                    );
                    $twilio->messages->create(
                        $user->phone,
                        [
                            'from' => config('services.twilio.from'),
                            'body' => $notification->content,
                        ]
                    );
                    $result['sms'] = ['success' => true];
                    Log::info('SMS sent', ['user' => $user->id, 'notification' => $notification->id]);
                } catch (\Exception $e) {
                    $result['sms'] = ['success' => false, 'error' => $e->getMessage()];
                    Log::error('SMS failed', ['error' => $e->getMessage()]);
                }
            } elseif ($channel === 'slack') {
                try {
                    Http::post(config('services.slack.webhook_url'), [
                        'text' => $notification->content,
                        'channel' => $user->slack_channel,
                    ]);
                    $result['slack'] = ['success' => true];
                    Log::info('Slack sent', ['user' => $user->id, 'notification' => $notification->id]);
                } catch (\Exception $e) {
                    $result['slack'] = ['success' => false, 'error' => $e->getMessage()];
                    Log::error('Slack failed', ['error' => $e->getMessage()]);
                }
            } elseif ($channel === 'push') {
                try {
                    // Push notification logic
                    $pushService = new \App\Services\PushService();
                    $pushService->send($user->device_token, $notification->title, $notification->content);
                    $result['push'] = ['success' => true];
                } catch (\Exception $e) {
                    $result['push'] = ['success' => false, 'error' => $e->getMessage()];
                }
            } elseif ($channel === 'webhook') {
                try {
                    Http::post($user->webhook_url, [
                        'event' => 'notification',
                        'data' => [
                            'id' => $notification->id,
                            'title' => $notification->title,
                            'content' => $notification->content,
                            'user_id' => $user->id,
                        ],
                    ]);
                    $result['webhook'] = ['success' => true];
                } catch (\Exception $e) {
                    $result['webhook'] = ['success' => false, 'error' => $e->getMessage()];
                }
            } else {
                Log::warning('Unknown channel: ' . $channel);
            }
        }

        // Check if any channel succeeded
        foreach ($result as $key => $value) {
            if ($key !== 'success' && $key !== 'channel' && ($value['success'] ?? false)) {
                $result['success'] = true;
                $result['channel'] = $key;
                break;
            }
        }

        return $result;
    }
}

The Challenges

New requirements are coming fast:

"We need to add Telegram channel."
"We need to add Microsoft Teams channel."
"We need to add WebSocket push notifications."
"We need to retry failed notifications with exponential backoff."
"We need to log all notification attempts to a database table."
"We need to add rate limiting per channel."

The current code is already a nightmare. Adding more channels will make it impossible to maintain.

Your Task

Refactor this system using polymorphism. Specifically:

Define a NotificationChannelInterface with methods like send(), supports(), getRetryDelay(), etc.
Create channel implementations for each notification type (Email, SMS, Slack, Push, Webhook, Telegram, Teams).
Build a ChannelResolver that resolves the right channel based on the user's preference.
Implement a NotificationService that uses the resolver and handles the flow.
Add retry logic with exponential backoff.
Implement logging and tracking without duplicating logic.

Questions to Consider

What should the NotificationChannelInterface look like?
How should you handle channel preferences?
How do you add retry logic without duplicating it in every channel?
How do you track notification status and history?
How do you add rate limiting per channel?
How do you test each channel independently?

(We won't provide the solution—refactor this code and experience the power of polymorphism!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Polymorphism is the ability of objects of different types to respond to the same interface in their own unique way.
One-sentence intuition: You don't need to ask "what are you?" before interacting. Just interact, and the object will respond appropriately based on its true nature.
One-sentence decision rule: If you find yourself writing if-elseif-else based on type, that's polymorphism screaming to be used. Extract each branch into its own class.

17. Related Concepts

SOLID Principles

Liskov Substitution: Polymorphism is the practical implementation of LSP.
Open/Closed: Polymorphism enables extension without modification.
Dependency Inversion: High-level modules depend on abstractions (interfaces), which polymorphism provides.

Design Patterns

Strategy Pattern: Encapsulates interchangeable algorithms via polymorphism.
Factory Pattern: Creates polymorphic objects.
Command Pattern: Encapsulates requests as objects via polymorphism.
Decorator Pattern: Wraps objects with polymorphic behavior.
Chain of Responsibility: Uses polymorphism to handle requests through a chain.

Laravel Internals

Authentication Guards: Different guard implementations via polymorphism.
Filesystem Drivers: Different storage providers via polymorphism.
Queue Drivers: Different queue systems via polymorphism.
Notification Channels: Different delivery methods via polymorphism.
Middleware: Different processing steps via polymorphism.

Enterprise Patterns

Strategy: Business logic variations via polymorphism.
Factory Method: Creation of polymorphic objects.
Abstract Factory: Families of polymorphic objects.
Chain of Responsibility: Processing chains via polymorphism.
Composite: Tree structures with polymorphic behavior.

Final Thoughts

Polymorphism is the most powerful tool in your OOP toolbox for managing variation. It's the antidote to the Conditional Apocalypse.

Every time you write if ($type === 'something'), you're making a decision that could be handled by polymorphism. Every time you add a new branch to an existing conditional, you're violating the Open/Closed Principle.

The next time you find yourself writing a long if-elseif block, stop. Ask yourself: "Could each branch be its own class?"

Remember: Polymorphism isn't just about replacing conditionals. It's about designing systems that are open for extension and closed for modification. It's about making your code future-proof.

Github: Polymorphism Practice Labs

From Data Dump to Domain Model: Encapsulation in PHP 8

Anas Hussain — Thu, 23 Jul 2026 07:55:55 +0000

Why Public Properties Are Slowly Destroying Your Object Design

1. Hook & Problem Statement

You're working on a Laravel project. You have a User class with a $isActive property. It's public. Easy to access, easy to set.

$user->isActive = false;

Then, you build a system that sends emails. You have a $email property. It's public. Easy.

Then, you build a payment system. You need to check if the user is active before charging them. So you write:

if ($user->isActive) {
    $this->charge($user);
}

Everything works. You move on to the next feature.

But then the requirements change. Now, users need to be verified before they're considered active. You need to send a verification email when they become active. You need to log when they're deactivated. You need to check if their subscription is paid before setting them to active.

Suddenly, your simple $user->isActive = false needs to trigger multiple actions. But you have 47 places in your code where you directly set isActive. Now you have to find all of them and add the new logic.

You start updating them one by one. You miss one. The system breaks. You spend 3 hours debugging. The business is unhappy. You're unhappy.

This is the problem with public properties.

They're convenient. They're fast. And they're slowly destroying your codebase. Every public property is a contract you cannot change. Every direct assignment is a bug waiting to happen.

The solution is as old as object-oriented programming itself: Encapsulation.

2. Why This Pattern/Concept Exists

The Software Engineering Problem It Solves

Encapsulation solves a fundamental problem in software design: managing complexity through information hiding.

When you expose internal state (public properties), you create a coupling between the class's internal representation and every piece of code that uses it. This coupling makes change expensive and risky.

The Pain That Existed Before

In the early days of programming (and still today in many codebases), developers treated data structures as just that—structures. They exposed everything, and everyone could modify everything.

This led to:

Spaghetti Data Flow: Data could be modified from anywhere. Debugging became a nightmare because you couldn't trace where a value changed.
Violated Invariants: A class had assumptions about its state (e.g., "email must be valid," "isActive and emailVerified must align"). But because state was exposed, these assumptions could be broken.
Fragile Code: Adding logic to a property access required finding every place that used the property.
Copy-Paste Validation: Every time you used a property, you had to validate it again. Validation was scattered across the codebase.
Testing Nightmare: You couldn't control what happened when a property was set because the logic (if any) was scattered.

Why Large Applications Need It

As applications grow, the number of places that interact with an object grows exponentially. A simple property like isActive might be accessed in 50 different places. Changing its behavior means finding all 50 places.

Encapsulation centralizes the logic. The property becomes a "behavioral access point." You can add logging, validation, event dispatching, or any other logic in ONE place.

The core insight: Objects aren't just data containers. They're responsible entities that protect their own integrity. Encapsulation is how they do it.

3. Real World Analogy

The Bank Teller

Imagine a bank. You can't just walk into the vault and withdraw money (public property). Instead, you go to a teller (method) and make a request.

The Encapsulated Bank:

You ask the teller to withdraw $100.
The teller checks your balance.
The teller verifies your identity.
The teller records the transaction.
The teller hands you the money.

The Non-Encapsulated Bank:

You walk into the vault.
You take $100.
The system doesn't know.
There's no record.
Anyone can do it.

Analogy Mapping:

Vault: The object's internal state.
Teller: The object's public methods.
Withdrawal Request: A method call.
Identity Verification: Validation logic.
Transaction Record: Logging and event dispatching.
Walking into the vault: Direct property access.

Why it works: The teller protects the bank's integrity. They ensure every withdrawal is legitimate. They keep records. The vault isn't exposed; only controlled access points exist.

The same applies to your objects. Public methods are the tellers. Public properties are leaving the vault door open.

4. The Pain (Bad Design)

Let's look at a typical Laravel application that has violated encapsulation.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Order extends Model
{
    // Public properties (bad practice!)
    public string $status;
    public float $total;
    public string $currency;
    public int $userId;
    public array $items = [];
    public ?string $shippingAddress;
    public ?string $billingAddress;
    public string $paymentMethod;
    public ?string $paymentIntentId;
    public array $timestamps = [];

    // Few methods, most logic is outside
}

Now, imagine 30 different controllers and services that use this model:

// Controller 1
public function store(Request $request)
{
    $order = new Order();
    $order->status = 'pending';
    $order->total = $request->total;
    $order->currency = $request->currency;
    $order->userId = $request->user()->id;
    $order->items = $request->items;
    $order->shippingAddress = $request->shipping_address;
    $order->billingAddress = $request->billing_address;
    $order->paymentMethod = $request->payment_method;
    $order->save();

    // Process payment
    if ($order->paymentMethod === 'stripe') {
        $stripe = new StripeClient(env('STRIPE_SECRET'));
        $intent = $stripe->paymentIntents->create([
            'amount' => $order->total * 100,
            'currency' => $order->currency,
        ]);
        $order->paymentIntentId = $intent->id;
        $order->save();
    }

    return response()->json($order);
}

// Controller 2
public function cancel(Order $order)
{
    if ($order->status !== 'pending') {
        throw new Exception('Order cannot be cancelled');
    }

    // Refund if paid
    if ($order->status === 'paid') {
        $stripe = new StripeClient(env('STRIPE_SECRET'));
        $stripe->refunds->create(['payment_intent' => $order->paymentIntentId]);
    }

    $order->status = 'cancelled';
    $order->save();
}

// Service 1
public function processPayment(Order $order)
{
    if ($order->total > 0 && $order->status === 'pending') {
        // Charge the user
        $payment = new PaymentService();
        $payment->charge($order->userId, $order->total, $order->currency);
        $order->status = 'paid';
        $order->save();

        // Send confirmation
        Mail::to(User::find($order->userId)->email)->send(new OrderConfirmation($order));
    }
}

// Service 2
public function calculateShipping(Order $order)
{
    if (!$order->shippingAddress) {
        return 0;
    }

    return match($order->status) {
        'pending' => 10,
        'paid' => 5,
        default => 0,
    };
}

Why This Is Terrible

Logic Scattered: Validation, payment processing, and email sending are spread across controllers and services.
No Invariant Enforcement: Nothing prevents an order from being paid without a paymentIntentId. Nothing ensures status transitions are valid.
Duplicated Validation: Every controller that creates an order validates the input differently (or not at all).
Duplicated Payment Logic: Payment processing logic is in controllers, services, and scattered everywhere.
Impossible to Change: Want to add a cancelled status that refunds automatically? Find every place that changes status.
Violates SOLID:
- SRP: No one is responsible for the order's integrity.
- OCP: Adding a new status requires modifying many files.
- DIP: The model depends on nothing (it's just data), while all logic depends on the model's state.

Why Developers Write Code Like This

We write code like this because:

Eloquent models make properties look like public fields.
It's fast to prototype.
We think "it's just data."
We don't realize the cost until it's too late.
We haven't internalized "tell, don't ask."

5. Solution Overview

Encapsulation is the bundling of data with the methods that operate on that data, combined with restricting direct access to the data.

Core Idea

Objects should hide their internal state (properties) and expose only behavior (methods). The outside world interacts with the object through this behavior, not by directly manipulating state.

Main Participants

Private Properties: The object's internal state, accessible only within the object.
Public Methods: The object's behavior, accessible to the outside world.
Getters/Setters (Accessors/Mutators): Controlled access to properties, often with validation or logic.
Command Methods: Methods that change state in meaningful ways (e.g., pay(), cancel(), markAsPaid()).

How Objects Collaborate

Instead of:

$order->status = 'paid';

You write:

$order->markAsPaid();

The outside world tells the object what to do, not how to do it or what to change. This is the "tell, don't ask" principle.

Mental Model

Think of an object as a living organism, not a grocery bag.

Grocery bag: You open it, put things in, take things out. Anyone can reach in and grab what they want.
Living organism: It has a boundary (skin). To interact, you talk to it (call methods). It responds (returns values or performs actions). You can't reach in and change its heart rate directly; you tell it to "run" and it changes its heart rate internally.

Encapsulation is the skin. It protects the organism's internal organs (state) and ensures they work together correctly.

Benefits

Centralized Logic: Validation, logging, and event dispatching in one place.
Invariant Protection: The object ensures it's always in a valid state.
Change Isolation: Changing internal representation doesn't affect outside code.
Readability: The object's public methods tell you what it can do.
Testability: Test the object's behavior, not its internal state.

Trade-offs

Boilerplate: More methods (getters, setters, commands).
Indirection: You can't just read or write properties directly.
Learning Curve: Developers need to understand the "tell, don't ask" principle.

6. UML Diagram

Laravel Encapsulation Mermaid Diagram

Diagram Explanation

Order encapsulates all its state (private properties) and exposes behavior (public methods).
PaymentProcessor collaborates with the order by calling its methods, not by modifying properties directly.
OrderRepository persists the order as a whole.
OrderController orchestrates the flow using the order's behavior.

The order is the single source of truth for its own integrity.

7. Vanilla PHP Example

Let's refactor the Order example using encapsulation.

Before Refactoring (No Encapsulation)

class BadOrder
{
    public string $status;
    public float $total;
    public string $currency;
    public int $userId;
    public array $items = [];
    public ?string $shippingAddress;
    public ?string $billingAddress;
    public string $paymentMethod;
    public ?string $paymentIntentId;
    public array $timestamps = [];
}

// Usage: scattered logic everywhere
$order = new BadOrder();
$order->status = 'pending';
$order->total = 100.00;
$order->currency = 'USD';
// ... etc.

After Refactoring (Full Encapsulation)

class Order
{
    // Private properties: hidden from outside
    private string $status;
    private float $total;
    private string $currency;
    private int $userId;
    private array $items = [];
    private ?string $shippingAddress;
    private ?string $billingAddress;
    private string $paymentMethod;
    private ?string $paymentIntentId;
    private array $timestamps = [];

    // Constants for valid states
    private const STATUS_PENDING = 'pending';
    private const STATUS_PAID = 'paid';
    private const STATUS_SHIPPED = 'shipped';
    private const STATUS_CANCELLED = 'cancelled';

    // Valid status transitions
    private const ALLOWED_TRANSITIONS = [
        self::STATUS_PENDING => [self::STATUS_PAID, self::STATUS_CANCELLED],
        self::STATUS_PAID => [self::STATUS_SHIPPED, self::STATUS_CANCELLED],
        self::STATUS_SHIPPED => [],
        self::STATUS_CANCELLED => [],
    ];

    // Constructor: validated creation
    public function __construct(array $data)
    {
        $this->validateOrderData($data);

        $this->status = self::STATUS_PENDING;
        $this->total = $data['total'];
        $this->currency = $data['currency'] ?? 'USD';
        $this->userId = $data['user_id'];
        $this->items = $data['items'] ?? [];
        $this->shippingAddress = $data['shipping_address'] ?? null;
        $this->billingAddress = $data['billing_address'] ?? null;
        $this->paymentMethod = $data['payment_method'] ?? 'stripe';
        $this->paymentIntentId = null;
        $this->timestamps['created_at'] = now();
    }

    // Command methods: behavior, not just setters
    public function markAsPaid(string $paymentIntentId): void
    {
        if ($this->status !== self::STATUS_PENDING) {
            throw new \Exception('Only pending orders can be marked as paid');
        }

        if (empty($paymentIntentId)) {
            throw new \Exception('Payment Intent ID is required');
        }

        $this->status = self::STATUS_PAID;
        $this->paymentIntentId = $paymentIntentId;
        $this->timestamps['paid_at'] = now();
    }

    public function cancel(): void
    {
        if (!$this->canBeCancelled()) {
            throw new \Exception('Order cannot be cancelled');
        }

        $this->status = self::STATUS_CANCELLED;
        $this->timestamps['cancelled_at'] = now();
    }

    public function ship(): void
    {
        if ($this->status !== self::STATUS_PAID) {
            throw new \Exception('Only paid orders can be shipped');
        }

        if (!$this->shippingAddress) {
            throw new \Exception('Shipping address is required');
        }

        $this->status = self::STATUS_SHIPPED;
        $this->timestamps['shipped_at'] = now();
    }

    public function addItem(array $item): void
    {
        if ($this->status !== self::STATUS_PENDING) {
            throw new \Exception('Cannot add items to a non-pending order');
        }

        $this->items[] = $item;
        $this->recalculateTotal();
    }

    public function updateShippingAddress(string $address): void
    {
        if ($this->status === self::STATUS_SHIPPED) {
            throw new \Exception('Cannot change shipping address after shipping');
        }

        $this->shippingAddress = $address;
    }

    // Query methods: controlled access to state
    public function getTotal(): float
    {
        return $this->total;
    }

    public function getStatus(): string
    {
        return $this->status;
    }

    public function getCurrency(): string
    {
        return $this->currency;
    }

    public function getUserId(): int
    {
        return $this->userId;
    }

    public function getItems(): array
    {
        return $this->items;
    }

    public function getShippingAddress(): ?string
    {
        return $this->shippingAddress;
    }

    public function getPaymentIntentId(): ?string
    {
        return $this->paymentIntentId;
    }

    public function isPending(): bool
    {
        return $this->status === self::STATUS_PENDING;
    }

    public function isPaid(): bool
    {
        return $this->status === self::STATUS_PAID;
    }

    public function isShipped(): bool
    {
        return $this->status === self::STATUS_SHIPPED;
    }

    public function isCancelled(): bool
    {
        return $this->status === self::STATUS_CANCELLED;
    }

    public function canBeCancelled(): bool
    {
        return in_array($this->status, [self::STATUS_PENDING, self::STATUS_PAID]);
    }

    public function canBeShipped(): bool
    {
        return $this->status === self::STATUS_PAID && $this->shippingAddress !== null;
    }

    // Private helper methods
    private function validateOrderData(array $data): void
    {
        if (!isset($data['user_id'])) {
            throw new \Exception('User ID is required');
        }

        if (!isset($data['total']) || $data['total'] <= 0) {
            throw new \Exception('Total must be greater than 0');
        }
    }

    private function recalculateTotal(): void
    {
        $total = 0;
        foreach ($this->items as $item) {
            $total += ($item['price'] ?? 0) * ($item['quantity'] ?? 1);
        }
        $this->total = $total;
    }
}

What We Improved

State Protection: Properties are private. No one can modify them directly.
Behavioral Methods: markAsPaid(), cancel(), ship() express intent, not just set values.
Invariant Enforcement: The order ensures it's always in a valid state.
Validation Centralization: All validation is in one place (the order itself).
Query Methods: Getters provide controlled access to state.
Status Transitions: Valid transitions are defined and enforced.
Single Responsibility: The order is responsible for its own integrity.
Testability: We can test the order's behavior, not its state.

Usage Now:

// Create an order
$order = new Order([
    'user_id' => 1,
    'total' => 100.00,
    'currency' => 'USD',
    'items' => [['name' => 'Laptop', 'price' => 100.00, 'quantity' => 1]],
]);

// Process payment
$order->markAsPaid('pi_123456');

// Cannot directly change status
// $order->status = 'paid'; // Error: private property

// Ship the order
if ($order->canBeShipped()) {
    $order->ship();
}

// Cancel only if allowed
if ($order->canBeCancelled()) {
    $order->cancel();
}

8. Laravel Internal Example

Laravel is built on encapsulation. Let's look at examples where the framework protects internal state.

Eloquent Models (Encapsulation Through Mutators)

Eloquent models use mutators (setters) and accessors (getters) to encapsulate property access.

// Laravel's Model class
class Model
{
    // Properties are protected
    protected $attributes = [];
    protected $original = [];
    protected $hidden = [];
    protected $fillable = [];

    // Encapsulated access
    public function setAttribute($key, $value)
    {
        // Validation, casting, mutator logic
        if ($this->hasSetMutator($key)) {
            return $this->setMutatedAttributeValue($key, $value);
        }
        // ... more logic
    }

    public function getAttribute($key)
    {
        // Casting, accessor logic
        if ($this->hasGetMutator($key)) {
            return $this->mutateAttribute($key, $value);
        }
        // ... more logic
    }
}

// In your model
class User extends Model
{
    // You can add custom mutators
    public function setPasswordAttribute($value)
    {
        // Encapsulated: any password set goes through bcrypt
        $this->attributes['password'] = bcrypt($value);
    }

    public function getFullNameAttribute()
    {
        // Encapsulated: computed property
        return $this->first_name . ' ' . $this->last_name;
    }
}

Why This Is Elegant:

You can't directly assign invalid values.
Mutators centralize logic (e.g., password hashing).
Accessors provide computed properties.
The model protects its integrity.

The Service Container (Encapsulated Resolution)

class Container
{
    // Private/internal state
    private $bindings = [];
    private $instances = [];
    private $aliases = [];

    // Encapsulated access
    public function bind($abstract, $concrete = null, $shared = false)
    {
        // Validation and setup
        $this->bindings[$abstract] = compact('concrete', 'shared');
    }

    public function make($abstract, array $parameters = [])
    {
        // Complex resolution logic encapsulated
        return $this->resolve($abstract, $parameters);
    }

    // Private methods for internal logic
    private function resolve($abstract, $parameters)
    {
        // Complex resolution hidden from outside
    }
}

Why This Is Elegant:

The container's internal state (bindings, instances) is private.
You interact through public methods (bind, make).
The container can change its internal implementation without affecting users.

Middleware Pipeline (Encapsulated Flow)

// Pipeline class
class Pipeline
{
    private $passable;
    private $pipes = [];
    private $method = 'handle';

    public function send($passable)
    {
        $this->passable = $passable;
        return $this;
    }

    public function through($pipes)
    {
        $this->pipes = is_array($pipes) ? $pipes : func_get_args();
        return $this;
    }

    public function then(Closure $destination)
    {
        // The pipeline controls the flow internally
        $pipeline = array_reduce(
            array_reverse($this->pipes),
            $this->carry(),
            $this->prepareDestination($destination)
        );

        return $pipeline($this->passable);
    }

    // Private helper methods
    private function carry()
    {
        return function ($stack, $pipe) {
            return function ($passable) use ($stack, $pipe) {
                // Encapsulated middleware execution
                return (new $pipe)->handle($passable, $stack);
            };
        };
    }
}

Why This Is Elegant:

The pipeline's internal flow is hidden.
You tell the pipeline what to send, through which pipes, and what to do at the end.
The pipeline encapsulates the complexity of middleware execution.

Queues (Encapsulated Job Processing)

class Worker
{
    public function processJob(Job $job)
    {
        // Encapsulated job processing
        $this->markJobAsStarted($job);

        try {
            $this->fireJob($job);
            $this->markJobAsFinished($job);
        } catch (Exception $e) {
            $this->markJobAsFailed($job, $e);
            $this->raiseFailureEvent($job, $e);
        }
    }

    // Private methods encapsulate logic
    private function markJobAsStarted(Job $job) { /* ... */ }
    private function fireJob(Job $job) { /* ... */ }
    private function markJobAsFinished(Job $job) { /* ... */ }
    private function markJobAsFailed(Job $job, Exception $e) { /* ... */ }
}

Why This Is Elegant:

The worker handles all the complexity of job lifecycle.
You don't need to know how to handle failures; the worker does it.
Changing how failures are handled only requires changing the worker.

9. Real Laravel Application Example

Let's build a Subscription Management System with full encapsulation.

Scenario

Your SaaS application needs to manage user subscriptions. Subscriptions can be:

Trial (7 days)
Monthly
Annual

They can be canceled, resumed, upgraded, downgraded, and have automatic renewals.

Implementation

Step 1: The Subscription Class (Fully Encapsulated)

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Subscription extends Model
{
    // Private state
    private string $status; // trial, active, paused, cancelled, expired
    private string $plan; // trial, monthly, annual
    private int $userId;
    private ?string $stripeSubscriptionId;
    private ?string $stripeCustomerId;
    private ?string $stripePaymentMethodId;
    private ?array $paymentHistory = [];
    private array $features = [];
    private array $billingCycle;

    // Constants
    private const STATUS_TRIAL = 'trial';
    private const STATUS_ACTIVE = 'active';
    private const STATUS_PAUSED = 'paused';
    private const STATUS_CANCELLED = 'cancelled';
    private const STATUS_EXPIRED = 'expired';

    private const PLAN_TRIAL = 'trial';
    private const PLAN_MONTHLY = 'monthly';
    private const PLAN_ANNUAL = 'annual';

    private const PLAN_FEATURES = [
        'trial' => ['basic_features' => true],
        'monthly' => ['basic_features' => true, 'advanced_features' => true],
        'annual' => ['basic_features' => true, 'advanced_features' => true, 'premium_support' => true],
    ];

    private const PLAN_PRICES = [
        'monthly' => 9.99,
        'annual' => 99.99,
    ];

    // Constructor
    public function __construct(int $userId, string $plan = self::PLAN_TRIAL)
    {
        $this->userId = $userId;
        $this->plan = $plan;
        $this->status = self::STATUS_TRIAL;
        $this->features = self::PLAN_FEATURES[$plan] ?? [];
        $this->billingCycle = [
            'started_at' => now(),
            'next_billing_at' => now()->addDays(7),
        ];
    }

    // Command methods
    public function activateTrial(): void
    {
        if ($this->status !== self::STATUS_TRIAL) {
            throw new \Exception('Trial can only be activated from trial status');
        }

        // Set trial features
        $this->features = self::PLAN_FEATURES['trial'];
        $this->billingCycle['trial_end'] = now()->addDays(7);
        $this->status = self::STATUS_TRIAL;
    }

    public function subscribe(string $stripeCustomerId, string $stripePaymentMethodId): void
    {
        if (!in_array($this->status, [self::STATUS_TRIAL, self::STATUS_CANCELLED])) {
            throw new \Exception('Cannot subscribe from current status');
        }

        if ($this->plan === self::PLAN_TRIAL) {
            throw new \Exception('Cannot subscribe with trial plan');
        }

        $this->stripeCustomerId = $stripeCustomerId;
        $this->stripePaymentMethodId = $stripePaymentMethodId;
        $this->status = self::STATUS_ACTIVE;
        $this->features = self::PLAN_FEATURES[$this->plan];
        $this->billingCycle = [
            'started_at' => now(),
            'next_billing_at' => $this->calculateNextBillingDate(),
        ];
        $this->paymentHistory[] = [
            'date' => now(),
            'amount' => $this->getPrice(),
            'type' => 'subscription_start',
        ];
    }

    public function cancel(): void
    {
        if (!in_array($this->status, [self::STATUS_ACTIVE, self::STATUS_PAUSED])) {
            throw new \Exception('Subscription cannot be cancelled');
        }

        $this->status = self::STATUS_CANCELLED;
        $this->billingCycle['cancelled_at'] = now();

        // Note: When to end depends on billing cycle
        $this->billingCycle['ends_at'] = $this->billingCycle['next_billing_at'] ?? now();
    }

    public function pause(): void
    {
        if ($this->status !== self::STATUS_ACTIVE) {
            throw new \Exception('Only active subscriptions can be paused');
        }

        $this->status = self::STATUS_PAUSED;
        $this->billingCycle['paused_at'] = now();
    }

    public function resume(): void
    {
        if ($this->status !== self::STATUS_PAUSED) {
            throw new \Exception('Only paused subscriptions can be resumed');
        }

        $this->status = self::STATUS_ACTIVE;
        // Reset billing cycle
        $this->billingCycle['next_billing_at'] = now()->addMonths(1);
        unset($this->billingCycle['paused_at']);
    }

    public function changePlan(string $newPlan): void
    {
        if (!in_array($this->status, [self::STATUS_ACTIVE, self::STATUS_PAUSED])) {
            throw new \Exception('Subscription must be active or paused to change plan');
        }

        if (!isset(self::PLAN_FEATURES[$newPlan])) {
            throw new \Exception('Invalid plan');
        }

        if ($newPlan === $this->plan) {
            throw new \Exception('New plan must be different');
        }

        // Store old plan for proration
        $oldPlan = $this->plan;
        $this->plan = $newPlan;
        $this->features = self::PLAN_FEATURES[$newPlan];

        // If upgrading, charge the difference
        if ($this->getPrice($newPlan) > $this->getPrice($oldPlan)) {
            $this->paymentHistory[] = [
                'date' => now(),
                'amount' => $this->getPrice($newPlan) - $this->getPrice($oldPlan),
                'type' => 'upgrade_proration',
            ];
        }

        $this->billingCycle['next_billing_at'] = $this->calculateNextBillingDate();
    }

    public function processRenewal(): void
    {
        if ($this->status !== self::STATUS_ACTIVE) {
            throw new \Exception('Only active subscriptions can be renewed');
        }

        // Charge the user
        // This would call Stripe, but we'll just update our records

        $this->paymentHistory[] = [
            'date' => now(),
            'amount' => $this->getPrice(),
            'type' => 'renewal',
        ];

        $this->billingCycle['last_renewal_at'] = now();
        $this->billingCycle['next_billing_at'] = $this->calculateNextBillingDate();
    }

    // Query methods
    public function isActive(): bool
    {
        return in_array($this->status, [self::STATUS_TRIAL, self::STATUS_ACTIVE]);
    }

    public function isOnTrial(): bool
    {
        return $this->status === self::STATUS_TRIAL;
    }

    public function canBeCancelled(): bool
    {
        return in_array($this->status, [self::STATUS_ACTIVE, self::STATUS_PAUSED]);
    }

    public function canBePaused(): bool
    {
        return $this->status === self::STATUS_ACTIVE;
    }

    public function canBeResumed(): bool
    {
        return $this->status === self::STATUS_PAUSED;
    }

    public function getPlan(): string
    {
        return $this->plan;
    }

    public function getStatus(): string
    {
        return $this->status;
    }

    public function getPrice(?string $plan = null): float
    {
        $plan = $plan ?? $this->plan;
        return self::PLAN_PRICES[$plan] ?? 0;
    }

    public function getFeatures(): array
    {
        return $this->features;
    }

    public function hasFeature(string $feature): bool
    {
        return $this->features[$feature] ?? false;
    }

    public function getNextBillingDate(): ?string
    {
        return $this->billingCycle['next_billing_at'] ?? null;
    }

    public function getPaymentHistory(): array
    {
        return $this->paymentHistory;
    }

    // Private helpers
    private function calculateNextBillingDate(): string
    {
        return match($this->plan) {
            self::PLAN_MONTHLY => now()->addMonths(1)->toDateString(),
            self::PLAN_ANNUAL => now()->addYear()->toDateString(),
            default => now()->addDays(30)->toDateString(),
        };
    }
}

Step 2: Service Provider (for dependency injection)

namespace App\Providers;

use App\Models\Subscription;
use Illuminate\Support\ServiceProvider;

class SubscriptionServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->bind(Subscription::class, function ($app) {
            // You could add initialization logic here
            return new Subscription(
                $app->request->user()->id,
                $app->config->get('subscription.default_plan', 'monthly')
            );
        });
    }
}

Step 3: Controller (Using Encapsulation)

namespace App\Http\Controllers;

use App\Models\Subscription;
use Illuminate\Http\Request;

class SubscriptionController extends Controller
{
    public function subscribe(Request $request)
    {
        $subscription = new Subscription(
            $request->user()->id,
            $request->input('plan', 'monthly')
        );

        // Validate payment method
        $request->validate([
            'payment_method_id' => 'required|string',
            'stripe_customer_id' => 'required|string',
        ]);

        try {
            $subscription->subscribe(
                $request->input('stripe_customer_id'),
                $request->input('payment_method_id')
            );

            // Persist the subscription (using a repository)
            $subscription->save();

            return response()->json([
                'subscription' => [
                    'plan' => $subscription->getPlan(),
                    'status' => $subscription->getStatus(),
                    'features' => $subscription->getFeatures(),
                    'next_billing' => $subscription->getNextBillingDate(),
                ]
            ]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }

    public function cancel(Subscription $subscription)
    {
        if (!$subscription->canBeCancelled()) {
            return response()->json(['error' => 'Subscription cannot be cancelled'], 400);
        }

        $subscription->cancel();
        $subscription->save();

        return response()->json([
            'message' => 'Subscription cancelled',
            'status' => $subscription->getStatus(),
        ]);
    }

    public function changePlan(Request $request, Subscription $subscription)
    {
        try {
            $subscription->changePlan($request->input('plan'));
            $subscription->save();

            return response()->json([
                'plan' => $subscription->getPlan(),
                'features' => $subscription->getFeatures(),
            ]);
        } catch (\Exception $e) {
            return response()->json(['error' => $e->getMessage()], 400);
        }
    }
}

Why Encapsulation Wins Here

State Protection: You can't accidentally put the subscription in an invalid state.
Intent-Revealing Methods: activateTrial(), subscribe(), pause(), resume() express clear intent.
Centralized Validation: All validation is in the subscription class.
Event-Ready: Adding events (e.g., SubscriptionCreated, PlanChanged) is trivial.
Testability: Test each method in isolation with known inputs.
Domain Language: The class speaks the language of the business (trial, pause, resume, upgrade).

10. SOLID Principles Mapping

S - Single Responsibility Principle (SRP)

Encapsulation naturally enforces SRP. The Subscription class is responsible for subscription integrity. It doesn't handle HTTP requests, database persistence, or email sending. Those are separate concerns.

O - Open/Closed Principle (OCP)

The Subscription class is open for extension (adding new plans, statuses) but closed for modification (you don't change existing methods to add new behavior).

L - Liskov Substitution Principle (LSP)

When you encapsulate, you work with abstractions. Subclasses (if any) can substitute the parent class because the parent's behavior is defined by its public methods, not its exposed state.

I - Interface Segregation Principle (ISP)

Encapsulation encourages focused interfaces. Each public method is a clear, focused behavior. You don't have to implement methods you don't need.

D - Dependency Inversion Principle (DIP)

High-level modules depend on abstractions, not concrete state. With encapsulation, you depend on the object's behavior (methods), not its internal representation.

11. Trade-offs

Benefits

Integrity Protection: Objects ensure they're always in a valid state.
Change Isolation: Internal changes don't affect external code.
Centralized Logic: Validation, logging, and events in one place.
Readability: Methods like cancel() are self-documenting.
Testability: Test behavior, not state.
Debugability: You know where state changes happen (in the object's methods).

Costs

Boilerplate: More methods to write (getters, setters, commands).
Indirection: You can't directly read or write properties.
Learning Curve: Developers must learn to "tell, don't ask."
Performance: Method calls have a tiny overhead vs property access (negligible in practice).

When Is Complexity Justified?

Encapsulation is justified for any class that has behavior. For pure data containers (DTOs), you might use public properties with readonly in PHP 8.1.

Rule of thumb: If the class has methods besides getters/setters, encapsulate. If it's just a data bag, consider using a DTO.

12. When NOT To Use It

3 Green Flags (USE ENCAPSULATION)

Business Logic: Classes that enforce rules and invariants.
State Management: Classes where state changes have consequences (logging, events, validation).
Complex Objects: Objects with multiple related properties that must stay in sync.

3 Red Flags (AVOID OVER-ENCAPSULATION)

Data Transfer Objects (DTOs): Simple containers for moving data between layers. Use readonly public properties.
Value Objects: Immutable objects like Money, Email, PhoneNumber. They can be public if they're immutable.
Config Objects: Objects that hold configuration values and have no behavior.

13. Common Mistakes

1. Getters and Setters for Everything

// BAD: Wrapping every property with getter/setter
class User
{
    private string $name;

    public function getName(): string { return $this->name; }
    public function setName(string $name): void { $this->name = $name; }
}

Problem: This is just verbose property access. It adds no value.

Fix: Use readonly public properties or add behavior to the methods.

// GOOD: Behavior, not just setters
class User
{
    private string $name;

    public function changeName(string $newName): void
    {
        // Validation, events, and more
        if (strlen($newName) < 2) {
            throw new \Exception('Name is too short');
        }

        $this->name = $newName;
        $this->recordEvent(new NameChangedEvent($this->id, $newName));
    }
}

2. Exposing Internal State Anyway

// BAD: Exposing internal state through getters
class Order
{
    private array $items = [];

    public function getItems(): array
    {
        return $this->items; // Exposed!
    }
}

// Outside code can modify the array
$items = $order->getItems();
$items[] = ['name' => 'New Item']; // Breaking encapsulation!

Problem: You've exposed a mutable array. Outside code can modify it.

Fix: Return immutable representations.

class Order
{
    private array $items = [];

    public function getItems(): array
    {
        return array_map(fn($item) => clone $item, $this->items); // Return copies
    }

    // Or return a DTO
    public function getItems(): ItemCollection
    {
        return new ItemCollection($this->items);
    }
}

3. Getting and Then Setting Instead of Telling

// BAD: Ask, then set
if ($order->getStatus() === 'pending') {
    $order->setStatus('paid');
    $order->setPaymentIntentId($intentId);
}

// GOOD: Tell the object
$order->markAsPaid($intentId);

Problem: The object has no control over the transition. It's just reacting.

Fix: Command methods express intent and enforce invariants.

4. Violating Law of Demeter (Talking Too Much)

// BAD: Breaking encapsulation by traversing objects
$user->getAddress()->getCity()->getName();

// GOOD: Tell the user what you want
$user->getCityName();

Problem: You're reaching deep into object graphs. You're coupling to internal structures.

Fix: Each object should provide methods that handle its own responsibilities.

5. Validation in the Wrong Place

// BAD: Validation outside the object
if (strlen($data['email']) > 0 && filter_var($data['email'], FILTER_VALIDATE_EMAIL)) {
    $user->setEmail($data['email']);
}

// GOOD: Validation inside the object
$user->setEmail($data['email']); // Object validates

Problem: Validation is scattered. It's easy to miss.

Fix: Validate in the object. The object is the guardian of its own data.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is encapsulation in object-oriented programming?
A: The bundling of data with methods that operate on that data, with restricted direct access to the data.
Q: Why should I make properties private instead of public?
A: To protect the object's integrity, centralize validation, and make the code easier to maintain and change.
Q: What's the difference between a getter and a public property?
A: A getter can compute a value, validate access, or return a transformed value. A public property is just a direct reference to internal state.
Q: What does "tell, don't ask" mean?
A: You should tell objects what to do rather than asking them for data and then making decisions based on that data.
Q: How does Laravel's Eloquent support encapsulation?
A: Through mutators (setters) and accessors (getters) that allow you to add logic when properties are set or read.

Senior/Architect

Q: Explain the relationship between encapsulation and the Law of Demeter.
A: The Law of Demeter (Don't Talk to Strangers) states that objects should only talk to their immediate friends. Encapsulation enforces this by hiding internal structure, preventing chained method calls like $user->getAddress()->getCity()->getName().
Q: How do you design for encapsulation while maintaining performance?
A: Focus on designing clear, focused interfaces. Use CQRS (Command Query Responsibility Segregation) to separate commands (state-changing methods) from queries (read-only methods). Use DTOs for efficient data transfer.
Q: What's the difference between encapsulation and information hiding?
A: Encapsulation is the broader concept of bundling data and behavior. Information hiding is the specific practice of hiding internal state and implementation details.
Q: How does encapsulation work with dependency injection?
A: Encapsulation ensures that dependencies are injected through the constructor (or setters) rather than created internally. This allows the object to control its own state while accepting external dependencies.
Q: How do you refactor a codebase with public properties to use encapsulation?
A: Gradually make properties private, add getters/setters, and update external code to use the methods. Then, identify behavioral patterns and create command methods (like markAsPaid()) to replace the "get, then set" pattern.

15. Interactive Practice Challenge

The Requirement

You're building an Inventory Management System. The current code uses public properties everywhere, making it fragile and difficult to maintain.

The Code (POOR DESIGN)

// InventoryItem.php
class InventoryItem
{
    public string $sku;
    public string $name;
    public int $quantity;
    public int $minStockLevel;
    public int $maxStockLevel;
    public float $price;
    public ?string $supplier;
    public ?string $location;
    public string $status;
    public array $movementHistory = [];
}

// InventoryService.php
class InventoryService
{
    public function addStock(InventoryItem $item, int $quantity, string $reason): void
    {
        if ($quantity <= 0) {
            throw new \Exception('Quantity must be positive');
        }

        $oldQuantity = $item->quantity;
        $item->quantity += $quantity;
        $item->movementHistory[] = [
            'type' => 'add',
            'quantity' => $quantity,
            'reason' => $reason,
            'old_quantity' => $oldQuantity,
            'new_quantity' => $item->quantity,
            'timestamp' => now(),
        ];

        if ($item->quantity > $item->maxStockLevel) {
            Log::warning('Stock exceeded max level', ['sku' => $item->sku]);
        }
    }

    public function removeStock(InventoryItem $item, int $quantity, string $reason): void
    {
        if ($quantity <= 0) {
            throw new \Exception('Quantity must be positive');
        }

        if ($item->quantity - $quantity < 0) {
            throw new \Exception('Insufficient stock');
        }

        $oldQuantity = $item->quantity;
        $item->quantity -= $quantity;
        $item->movementHistory[] = [
            'type' => 'remove',
            'quantity' => $quantity,
            'reason' => $reason,
            'old_quantity' => $oldQuantity,
            'new_quantity' => $item->quantity,
            'timestamp' => now(),
        ];

        if ($item->quantity < $item->minStockLevel) {
            Log::warning('Stock below min level', ['sku' => $item->sku]);
            // Send reorder notification
            $this->reorderItem($item);
        }
    }

    public function reorderItem(InventoryItem $item): void
    {
        if (!$item->supplier) {
            Log::error('No supplier for item', ['sku' => $item->sku]);
            return;
        }

        $reorderQuantity = $item->maxStockLevel - $item->quantity;
        if ($reorderQuantity > 0) {
            // Send reorder request to supplier
            Log::info('Reordering item', [
                'sku' => $item->sku,
                'supplier' => $item->supplier,
                'quantity' => $reorderQuantity,
            ]);

            $item->movementHistory[] = [
                'type' => 'reorder',
                'quantity' => $reorderQuantity,
                'timestamp' => now(),
            ];
        }
    }
}

// OrderProcessor.php
class OrderProcessor
{
    public function processOrder(array $items): void
    {
        foreach ($items as $itemData) {
            $item = InventoryItem::find($itemData['sku']);

            if (!$item) {
                continue;
            }

            // Check if available
            if ($item->quantity < $itemData['quantity']) {
                throw new \Exception("Insufficient stock for {$item->sku}");
            }

            // Check if we're near max
            if ($item->quantity > $item->maxStockLevel - 10) {
                Log::warning("Stock is high for {$item->sku}");
            }

            // Decrement
            $item->quantity -= $itemData['quantity'];

            // Update history
            $item->movementHistory[] = [
                'type' => 'order_fulfillment',
                'quantity' => $itemData['quantity'],
                'timestamp' => now(),
            ];

            // Save
            $item->save();
        }
    }
}

The Challenges

The code has become a nightmare to maintain. New requirements keep coming:

"We need to track who made each inventory change."
"We need to notify the warehouse when an item is low."
"We need to put items on hold (reserve stock) for pending orders."
"We need to calculate the total value of inventory."
"We need to auto-approve reorders for high-value items."

Your Task

Refactor this system using encapsulation. Specifically:

Make properties private and add behavior through methods.
Create command methods like addStock(), removeStock(), reserveStock() that enforce invariants.
Move all validation into the InventoryItem class.
Centralize logging and event dispatching within the object.
Add query methods to safely expose data.
Refactor external code to "tell" the object what to do rather than "asking" it for data.

Questions to Consider

What should happen when stock exceeds max?
How do you handle stock reservations for pending orders?
How do you track who made each change?
How do you notify the warehouse when stock is low?
How do you calculate total inventory value?
What methods should InventoryItem expose?

(We won't provide the solution—refactor this code and see how much cleaner it becomes!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Encapsulation is the principle of hiding internal state and exposing behavior, ensuring that objects maintain their own integrity.
One-sentence intuition: Objects are like bank vaults—you can't access them directly, but you can ask the teller (the public methods) to perform operations.
One-sentence decision rule: If a class has behavior (not just data), make its properties private and expose methods that represent what the object can do, not what it contains.

17. Related Concepts

SOLID Principles

Single Responsibility: Encapsulation ensures each object is responsible for its own state.
Open/Closed: Objects are open for extension but closed for modification through encapsulation.
Liskov Substitution: Subclasses can substitute because behavior, not state, defines the contract.
Interface Segregation: Focused interfaces emerge from encapsulated behavior.
Dependency Inversion: High-level modules depend on behavior abstractions, not state.

Design Patterns

Command Pattern: Encapsulates a request as an object (like markAsPaid()).
Strategy Pattern: Encapsulates algorithms behind an interface.
Observer Pattern: Encapsulates event notification and handling.
State Pattern: Encapsulates state-specific behavior.
Factory Pattern: Encapsulates object creation logic.

Laravel Internals

Eloquent Models: Use mutators/accessors to encapsulate property access.
Service Container: Encapsulates dependency resolution logic.
Event System: Encapsulates event dispatching and listener resolution.
Middleware: Encapsulates request/response processing steps.

Enterprise Patterns

Domain Model: Encapsulates business rules and logic.
Value Object: Immutable objects that encapsulate validation.
Aggregate Root: Encapsulates consistency boundaries.
Repository: Encapsulates data access logic.

Final Thoughts

Public properties are the silent killer of object-oriented design. They seem convenient, but they slowly erode your codebase's integrity, making changes expensive and risky.

Encapsulation is your shield. It protects your objects from being corrupted, centralizes logic, and makes your code maintainable and testable.

The next time you start typing public $property, ask yourself: "Do I really want everyone to be able to change this? Or should this object be responsible for its own state?"

Remember: A good object tells the world what it can do, not what it contains. Objects are actors, not data containers.

Github: Encapsulation Practice Labs

The Inheritance Trap: How Laravel Developers Can Build More Flexible Systems

Anas Hussain — Mon, 20 Jul 2026 05:57:41 +0000

1. Hook & Problem Statement

You're building a Laravel application. You have a User model that extends Authenticatable. Everything works great. Then you need a Admin user with additional permissions, so you extend User. Then you need a PremiumUser with special features, so you extend Admin. Then you need a GuestUser that inherits some behavior, so you extend User.

Before you know it, your inheritance tree looks like this:

Authenticatable
    └── User
        ├── Admin
        │   └── SuperAdmin
        └── PremiumUser
            ├── VipUser
            └── EnterpriseUser

Now, you need to add a Moderator that has some admin features but not all. You start thinking: "Should Moderator extend Admin? But then it gets SuperAdmin methods it shouldn't have. Should I duplicate code? Should I copy-paste the methods?"

You're stuck in the inheritance trap. Your class hierarchy has become a rigid, fragile web of dependencies. A change in User breaks SuperAdmin. Adding a new feature requires refactoring the entire tree. Your code is screaming, but you don't know how to fix it.

This is the problem with inheritance-first thinking.

Inheritance is the most overused and misunderstood tool in object-oriented programming. It's often the first solution developers reach for when they see shared behavior. But real-world applications are rarely best modeled with deep class hierarchies.

There's a better way. It's called Composition over Inheritance, and it's the secret to building flexible, maintainable, and scalable systems.

2. Why This Pattern/Concept Exists

The Problem It Solves

Inheritance creates a "is-a" relationship. A Car is a Vehicle. A PremiumUser is a User. This seems natural—until you realize that many real-world relationships aren't strictly hierarchical. They're behavioral.

Consider: a User might have the behavior of being Notifiable, Authenticatable, Billable, and Loggable. These aren't types of users; they're capabilities a user can have. Forcing these capabilities into an inheritance hierarchy creates the "diamond problem," tight coupling, and fragile base classes.

The Pain That Existed Before

Before the Gang of Four book popularized composition, developers relied heavily on inheritance:

The Fragile Base Class Problem: A change in a parent class could subtly break all child classes. This made maintenance terrifying.
The Diamond Problem: Multiple inheritance (in languages that allow it) created ambiguity when two parent classes had the same method.
Deep Hierarchies: Classes became deeply nested, making code hard to understand and navigate.
Code Duplication: When behavior didn't fit the hierarchy, developers duplicated code across branches.
Tight Coupling: Child classes were tightly coupled to their parents. Swapping behavior required re-architecting the hierarchy.

Why Large Applications Need It

As applications grow, requirements change. Today's PremiumUser is tomorrow's EnterpriseUser with a different billing model. Inheritance makes change expensive. Composition makes it cheap.

Composition enables:

Plug-and-play behavior: Add or remove capabilities without changing the class.
Horizontal reuse: Share behavior across unrelated classes.
Testing in isolation: Test behaviors independently.
Evolution: Change behavior by swapping components, not rewriting hierarchies.

3. Real World Analogy

The Swiss Army Knife vs. A Modular Toolkit

Imagine you're a craftsman. You need various tools: a knife, scissors, a can opener, a screwdriver, a file.

The Inheritance Approach (The Swiss Army Knife):
You buy a single Swiss Army Knife with all tools built in. It's a "Multi-Tool" that inherits from "Knife" and "Scissors" and "Screwdriver."

Problem: When the scissors break, the entire knife is compromised.
Problem: You can't replace the scissors with a better version.
Problem: You can't add a new tool (like a flashlight) without redesigning the knife.
Problem: If you need two screwdrivers, you need two Swiss Army Knives.

The Composition Approach (The Modular Toolkit):
You buy a tool case (the container) and separate, interchangeable tools (the components):

A knife blade that fits in a handle
Scissors that snap into a handle
A screwdriver bit set that clicks into a driver
A flashlight attachment that connects to the handle
Benefit: Broken scissors? Replace just the scissors.
Benefit: Need a new tool? Add it to the case. Existing tools unchanged.
Benefit: Need two screwdrivers? Buy two bits. Same handle.
Benefit: Each tool has a single, focused responsibility.

Analogy Mapping:

Tool Case: Your application class (e.g., User)
Interchangeable Tools: Behaviors and capabilities (e.g., Notifiable, Authenticatable)
Handle: The common interface that makes tools compatible
Attaching a tool: Dependency injection (the class receives the capability)
Buying a new tool: Adding a new behavior without modifying existing classes

The modular toolkit is more flexible, maintainable, and extensible than the all-in-one Swiss Army Knife.

4. The Pain (Bad Design)

Let's look at a classic inheritance disaster in a Laravel context.

// Base class
class Vehicle
{
    protected string $model;
    protected int $year;

    public function getInfo(): string
    {
        return "{$this->model} ({$this->year})";
    }

    public function startEngine(): string
    {
        return "Engine started";
    }

    public function honk(): string
    {
        return "Honk!";
    }
}

// Level 1
class Car extends Vehicle
{
    protected int $numberOfDoors = 4;
    protected bool $hasSunroof = false;

    public function lockDoors(): string
    {
        return "Doors locked";
    }
}

// Level 2
class ElectricCar extends Car
{
    protected int $batteryCapacity;

    public function startEngine(): string
    {
        // Override to use electric motor
        return "Electric motor started silently";
    }

    public function charge(): string
    {
        return "Charging battery...";
    }
}

// Level 3
class TeslaModel3 extends ElectricCar
{
    public function __construct()
    {
        $this->model = "Tesla Model 3";
        $this->year = 2024;
        $this->batteryCapacity = 75;
        $this->hasSunroof = true;
        $this->numberOfDoors = 4;
    }

    public function autopilot(): string
    {
        return "Autopilot engaged";
    }
}

Now, your boss says: "We need a FlyingCar that can both drive and fly. And a BoatCar for amphibious operations."

// Where does FlyingCar fit? It's a Car? But it flies like a Plane.
// It can't extend both Car and Plane.
class FlyingCar // extends Car? extends Plane? extends both?
{
    // We're stuck. Multiple inheritance isn't allowed in PHP.
}

// Solution: Duplicate code?
class FlyingCar extends Car
{
    // We have to copy the fly methods from Plane
    public function takeOff(): string
    {
        return "Taking off...";
    }

    public function land(): string
    {
        return "Landing...";
    }
}

Why This Is Terrible

Tight Coupling: Every class is bound to its parent. Changing Vehicle affects every child.
Rigidity: Adding new behavior requires modifying the hierarchy. FlyingCar can't reuse Plane code.
Code Duplication: FlyingCar duplicates the takeOff and land methods from Plane.
Deep Hierarchies: TeslaModel3 is 4 levels deep. Understanding it requires tracing through all parents.
Violates SOLID:
- SRP: Vehicle is responsible for engine, honking, and all vehicle logic.
- OCP: Adding FlyingCar required creating new subclasses and duplicating code.
- LSP: ElectricCar overrides startEngine but still works as a Car (okay in this case, but often LSP violations happen).

Why Developers Write Code Like This

We write inheritance-heavy code because:

It's taught as the first OOP concept in many tutorials.
It feels natural ("A Car is a Vehicle").
It seems like code reuse without extra complexity.
We don't realize the costs until the hierarchy grows.
We haven't been introduced to composition.

5. Solution Overview

Composition over Inheritance is a design principle that favors assembling objects with capabilities (composition) over creating deep class hierarchies (inheritance).

Core Idea

Instead of saying "A User is a Notifiable entity," you say "A User has a Notification capability."

Instead of building a rigid tree, you build a flexible "Lego set." Each class is a Lego brick that can be combined with others in various ways.

Main Participants

The Host/Container: The main class that aggregates capabilities.
The Components: Small, focused classes that provide specific behaviors.
The Interfaces: Contracts that define what a component can do.
The Composition: The act of injecting components into the host.

How Objects Collaborate

User (Host)
    ├── NotificationTrait (Component)
    ├── AuthenticationTrait (Component)
    └── BillingTrait (Component)

Each component handles one aspect of behavior. The host delegates to its components.

Mental Model

Think of a class as a ship.

Inheritance (The Mega-Yacht): You build a single, monolithic vessel that does everything. To change anything, you must rebuild the ship.
Composition (A Fleet of Ships): You have a command ship, a supply ship, a medical ship, and a repair ship. They work together but are independent. Swap out the medical ship for a better one without changing the others.

Benefits

Flexibility: Add, remove, or swap behaviors independently.
Reusability: Reuse the same component across completely different classes.
Maintainability: Components are small, focused, and easy to understand.
Testability: Test each component in isolation.

Trade-offs

Boilerplate: You may need more classes and more delegation code.
Complexity: Deciding how to compose objects requires careful design.
Learning Curve: Developers must learn to think in terms of capabilities, not hierarchies.

6. UML Diagram

Laravel Composition Over Inheritance Mermaid Diagram

Diagram Explanation

User is the host class. It doesn't extend anything. It has capabilities.
User receives its components through constructor injection.
User delegates behavior to its components.
Components are interfaces (contracts) that define capabilities.
Concrete implementations can be swapped (e.g., EmailNotifier or SmsNotifier for NotificationService).

The host class is small, focused, and flexible. The components are reusable across different hosts.

7. Vanilla PHP Example

Let's refactor the Vehicle disaster using composition.

Before Refactoring (The Inheritance Mess)

// Complex inheritance hierarchy as shown above
class Vehicle { /* ... */ }
class Car extends Vehicle { /* ... */ }
class ElectricCar extends Car { /* ... */ }
class TeslaModel3 extends ElectricCar { /* ... */ }
// FlyingCar? BoatCar? We're stuck.

After Refactoring (Composition)

// Step 1: Define interfaces for capabilities
interface Startable
{
    public function start(): string;
}

interface Honkable
{
    public function honk(): string;
}

interface Flyable
{
    public function takeOff(): string;
    public function land(): string;
}

interface Floatable
{
    public function sail(): string;
}

interface Autopilotable
{
    public function autopilot(): string;
}

// Step 2: Implement components (behaviors)
class CombustionEngine implements Startable
{
    public function start(): string
    {
        return "Engine started with a roar!";
    }
}

class ElectricMotor implements Startable
{
    public function start(): string
    {
        return "Electric motor started silently...";
    }
}

class AirHorn implements Honkable
{
    public function honk(): string
    {
        return "HONK HONK!";
    }
}

class Chime implements Honkable
{
    public function honk(): string
    {
        return "Beep beep!";
    }
}

class FixedWing implements Flyable
{
    public function takeOff(): string
    {
        return "Lifting off the runway...";
    }

    public function land(): string
    {
        return "Approaching runway for landing...";
    }
}

class Hull implements Floatable
{
    public function sail(): string
    {
        return "Gliding across the water...";
    }
}

class TeslaAutopilot implements Autopilotable
{
    public function autopilot(): string
    {
        return "Navigating autonomously (Tesla AI)...";
    }
}

// Step 3: The host class (composition)
class Vehicle
{
    private Startable $engine;
    private Honkable $horn;
    private array $capabilities = [];

    public function __construct(
        Startable $engine,
        Honkable $horn,
        array $capabilities = []
    ) {
        $this->engine = $engine;
        $this->horn = $horn;
        $this->capabilities = $capabilities;
    }

    public function start(): string
    {
        return $this->engine->start();
    }

    public function honk(): string
    {
        return $this->horn->honk();
    }

    public function hasCapability(string $capability): bool
    {
        return isset($this->capabilities[$capability]);
    }

    public function do(string $action): string
    {
        if (isset($this->capabilities[$action])) {
            return $this->capabilities[$action]->$action();
        }
        throw new \Exception("Capability {$action} not available");
    }
}

// Step 4: Usage (composition in action)
// Create a regular car
$car = new Vehicle(
    new CombustionEngine(),
    new AirHorn()
);
echo $car->start(); // "Engine started with a roar!"
echo $car->honk(); // "HONK HONK!"

// Create a Tesla (electric car with autopilot)
$tesla = new Vehicle(
    new ElectricMotor(),
    new Chime(),
    ['autopilot' => new TeslaAutopilot()]
);
echo $tesla->start(); // "Electric motor started silently..."
echo $tesla->honk(); // "Beep beep!"
echo $tesla->do('autopilot'); // "Navigating autonomously (Tesla AI)..."

// Create a flying car!
$flyingCar = new Vehicle(
    new CombustionEngine(),
    new AirHorn(),
    [
        'takeOff' => new FixedWing(),
        'land' => new FixedWing(),
        'sail' => new Hull()
    ]
);
echo $flyingCar->do('takeOff'); // "Lifting off the runway..."
echo $flyingCar->do('sail'); // "Gliding across the water..."

What We Improved

No Inheritance: Vehicle extends nothing. It's a container for capabilities.
Plug-and-Play: Want to add flying? Add Flyable component. Want to remove it? Don't include it.
Reusable Components: ElectricMotor can be used in cars, boats, or anything that needs an electric start.
Testable: Test ElectricMotor without needing a Vehicle. Test Vehicle with mock components.
Open/Closed: To add a new capability, create a new component and use it. No need to modify existing classes.
Liskov Substitution: Any Startable component can be substituted for another. Vehicle doesn't care which one.

8. Laravel Internal Example

Laravel is built on composition. Let's look at how the framework uses this principle.

Eloquent Models (A Masterclass in Composition)

Eloquent models don't inherit much behavior. Instead, they use traits and components.

namespace Illuminate\Database\Eloquent;

class Model
{
    use HasAttributes,
        HasEvents,
        HasRelationships,
        HasTimestamps,
        HasGlobalScopes,
        HasVisibility;

    // The class doesn't do much itself.
    // It delegates to traits (composition by another name).
}

Why This Is Elegant:

Each trait is focused on one concern.
You can pick and choose which traits to use in your own models.
Adding a new feature (e.g., SoftDeletes) is as simple as adding a trait.

Middleware Pipeline (Composition in Action)

Middleware is a perfect example of composition using the Pipeline pattern.

// Middleware are small, focused components
class Authenticate
{
    public function handle($request, $next)
    {
        if (!auth()->check()) {
            return redirect('/login');
        }
        return $next($request);
    }
}

class EnsureEmailIsVerified
{
    public function handle($request, $next)
    {
        if (!auth()->user()->hasVerifiedEmail()) {
            return redirect('/verify-email');
        }
        return $next($request);
    }
}

// The Kernel composes these components
protected $middlewareGroups = [
    'web' => [
        \Illuminate\Session\Middleware\StartSession::class,
        \Illuminate\View\Middleware\ShareErrorsFromSession::class,
        \App\Http\Middleware\Authenticate::class,
        \App\Http\Middleware\EnsureEmailIsVerified::class,
    ],
];

Why This Is Elegant:

Each middleware has one job (SRP).
They can be composed in any order.
Adding a new middleware doesn't affect others (OCP).
They can be reused across routes.

The Notifications System

Laravel's notifications are built on composition, not inheritance.

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        // Choose channels based on the notifiable object
        return ['mail', 'database', 'broadcast'];
    }

    public function toMail($notifiable): MailMessage
    {
        return (new MailMessage)
            ->greeting('Hello!')
            ->line('Your order has been shipped.');
    }

    public function toDatabase($notifiable): array
    {
        return ['order_id' => $this->order->id];
    }
}

Why This Is Elegant:

You compose the notification from different channels.
Each toXxx method is a component that handles one channel.
Channels are swappable (switch from mail to SMS without changing the notification logic).

Service Providers (Configuration Composition)

Service providers compose your application's services.

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Compose services
        $this->app->bind(NotificationChannel::class, EmailChannel::class);
        $this->app->bind(PaymentGateway::class, StripeGateway::class);
    }
}

The application is composed from these providers. Adding a new service means adding a new provider, not changing existing ones.

9. Real Laravel Application Example

Let's build a Content Moderation System using composition.

Scenario

Your application needs to moderate user content (comments, posts, images). Moderation includes:

Profanity filtering
Spam detection
Image NSFW detection
Sentiment analysis

Different types of content need different combinations of these checks.

Implementation

Step 1: Define the Core Interface

// app/Contracts/ModeratorInterface.php
namespace App\Contracts;

interface ModeratorInterface
{
    public function moderate(string $content, array $metadata = []): array;
}

Step 2: Create Moderator Components

// app/Moderators/ProfanityFilter.php
namespace App\Moderators;

use App\Contracts\ModeratorInterface;

class ProfanityFilter implements ModeratorInterface
{
    private array $badWords = ['damn', 'hell', 'shoot']; // Simplified

    public function moderate(string $content, array $metadata = []): array
    {
        $result = ['blocked' => false, 'reasons' => []];

        foreach ($this->badWords as $word) {
            if (stripos($content, $word) !== false) {
                $result['blocked'] = true;
                $result['reasons'][] = "Contains profanity: {$word}";
            }
        }

        return $result;
    }
}

// app/Moderators/SpamDetector.php
namespace App\Moderators;

use App\Contracts\ModeratorInterface;

class SpamDetector implements ModeratorInterface
{
    public function moderate(string $content, array $metadata = []): array
    {
        $result = ['blocked' => false, 'reasons' => []];

        // Check for spam patterns
        if (preg_match('/buy now|click here|free money/i', $content)) {
            $result['blocked'] = true;
            $result['reasons'][] = 'Contains spam keywords';
        }

        if (strpos($content, 'http') !== false && count(explode(' ', $content)) < 10) {
            $result['blocked'] = true;
            $result['reasons'][] = 'Short content with suspicious links';
        }

        return $result;
    }
}

// app/Moderators/SentimentAnalyzer.php
namespace App\Moderators;

use App\Contracts\ModeratorInterface;

class SentimentAnalyzer implements ModeratorInterface
{
    public function moderate(string $content, array $metadata = []): array
    {
        // In a real app, this would call an external API
        $sentimentScore = $this->analyzeSentiment($content);

        return [
            'blocked' => $sentimentScore < -0.8,
            'score' => $sentimentScore,
            'reasons' => $sentimentScore < -0.8 ? ['Extremely negative sentiment'] : []
        ];
    }

    private function analyzeSentiment(string $content): float
    {
        // Simplified implementation
        $positiveWords = ['great', 'awesome', 'beautiful', 'nice'];
        $negativeWords = ['terrible', 'awful', 'hate', 'worst'];

        $positiveCount = 0;
        $negativeCount = 0;

        foreach ($positiveWords as $word) {
            if (strpos($content, $word) !== false) $positiveCount++;
        }
        foreach ($negativeWords as $word) {
            if (strpos($content, $word) !== false) $negativeCount++;
        }

        return ($positiveCount - $negativeCount) / max(1, $positiveCount + $negativeCount);
    }
}

Step 3: The Composer (Orchestrator)

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

use App\Contracts\ModeratorInterface;
use Illuminate\Support\Collection;

class ModerationService implements ModeratorInterface
{
    private Collection $moderators;

    public function __construct(array $moderators = [])
    {
        $this->moderators = collect($moderators);
    }

    public function addModerator(ModeratorInterface $moderator): self
    {
        $this->moderators->push($moderator);
        return $this;
    }

    public function moderate(string $content, array $metadata = []): array
    {
        $results = [];
        $blocked = false;
        $reasons = [];

        foreach ($this->moderators as $moderator) {
            $result = $moderator->moderate($content, $metadata);
            $results[] = $result;

            if ($result['blocked'] ?? false) {
                $blocked = true;
                $reasons = array_merge($reasons, $result['reasons'] ?? []);
            }
        }

        return [
            'blocked' => $blocked,
            'reasons' => $reasons,
            'details' => $results
        ];
    }
}

Step 4: Service Provider

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

use App\Contracts\ModeratorInterface;
use App\Moderators\ProfanityFilter;
use App\Moderators\SpamDetector;
use App\Moderators\SentimentAnalyzer;
use App\Services\ModerationService;
use Illuminate\Support\ServiceProvider;

class ModerationServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(ModerationService::class, function ($app) {
            $service = new ModerationService();

            // Compose the service with all moderators
            $service->addModerator(new ProfanityFilter());
            $service->addModerator(new SpamDetector());

            // Only add sentiment analyzer for text content
            if (config('moderation.sentiment_enabled')) {
                $service->addModerator(new SentimentAnalyzer());
            }

            return $service;
        });

        // Or bind the interface to the composed service
        $this->app->bind(ModeratorInterface::class, ModerationService::class);
    }
}

Step 5: Controller

// app/Http/Controllers/CommentController.php
namespace App\Http\Controllers;

use App\Contracts\ModeratorInterface;
use App\Models\Comment;
use Illuminate\Http\Request;

class CommentController extends Controller
{
    public function __construct(
        private readonly ModeratorInterface $moderator
    ) {}

    public function store(Request $request)
    {
        $moderationResult = $this->moderator->moderate(
            $request->input('content'),
            ['user_id' => $request->user()->id]
        );

        if ($moderationResult['blocked']) {
            return response()->json([
                'error' => 'Comment rejected',
                'reasons' => $moderationResult['reasons']
            ], 422);
        }

        $comment = Comment::create([
            'content' => $request->input('content'),
            'user_id' => $request->user()->id,
            'moderation_score' => $moderationResult['details'] ?? null
        ]);

        return response()->json($comment, 201);
    }
}

Why Composition Wins Here

Flexibility: Add or remove moderators without changing the core logic.
Reusability: Use ProfanityFilter for comments, posts, and images.
Testability: Test each moderator independently.
Configuration: Enable/disable moderators via configuration.
Extensibility: Add a new ImageNsfwDetector without affecting existing code.

10. SOLID Principles Mapping

S - Single Responsibility Principle (SRP)

With composition, each component has a single responsibility:

ProfanityFilter: Detects bad words only.
SpamDetector: Detects spam patterns only.
SentimentAnalyzer: Analyzes sentiment only.

The ModerationService coordinates, but it doesn't do the actual moderation.

O - Open/Closed Principle (OCP)

The system is open for extension (add new moderators) but closed for modification (the core service never changes). Adding a new ImageNsfwDetector requires zero changes to ModerationService.

L - Liskov Substitution Principle (LSP)

All moderators implement the ModeratorInterface. The ModerationService can use any moderator interchangeably. If you pass a ImageNsfwDetector where a ProfanityFilter is expected, it works.

I - Interface Segregation Principle (ISP)

The ModeratorInterface is focused and minimal. It has exactly one method: moderate(). No class is forced to implement methods it doesn't need.

D - Dependency Inversion Principle (DIP)

High-level ModerationService depends on the ModeratorInterface abstraction, not concrete implementations. Low-level moderators depend on the same abstraction.

11. Trade-offs

Benefits

Flexibility: Swap components at runtime. Add new components without changing existing code.
Testability: Test components in isolation. Mock components during host testing.
Reusability: Use the same component across different contexts.
Maintainability: Changes are localized to specific components.
Understanding: Small, focused classes are easier to understand than deep hierarchies.

Costs

Boilerplate: More classes. More interfaces. More documentation.
Indirection: To understand what a method does, you may need to trace through several components.
Overhead: The act of composing objects requires careful design decisions.
Cognitive Load: Developers must learn to think in terms of capabilities, not "is-a" relationships.

When Is Complexity Justified?

Use composition when:

The behavior is likely to change or extend.
The behavior is reusable across unrelated classes.
The class has multiple, independent concerns.
You need to test behavior in isolation.

Avoid composition when:

The relationship is truly hierarchical and stable.
The class has a single, simple behavior.
The performance overhead of delegation is significant (rarely a factor in web applications).

12. When NOT To Use It

3 Green Flags (USE COMPOSITION)

Multiple Behaviors: A class needs to implement several unrelated behaviors (e.g., Notifiable, Authenticatable, Billable).
Changing Requirements: The behavior is likely to change or expand over time.
Cross-Cutting Concerns: The same behavior is needed across different classes (e.g., logging, caching, validation).

3 Red Flags (USE INHERITANCE)

Truly Hierarchical: The relationship is "is-a" and unlikely to change (e.g., Dog extends Animal).
Simple Extension: You're adding a small behavior to a framework class (e.g., App\User extends Authenticatable). Extending the framework class is the intended use.
Shared State: The behavior relies heavily on the internal state of the parent class. Composition would require exposing that state.

13. Common Mistakes

1. Choosing Composition When Inheritance Was Simpler

// BAD: Over-engineered composition for a simple problem
class Logger
{
    private $formatter;
    public function __construct(FormatterInterface $formatter) { ... }
    public function log($message) { ... }
}

// The formatter never changes. Inheritance would have been fine.

Problem: You've added complexity where none was needed.
Fix: Use inheritance when the relationship is stable and simple.

2. Forgetting to Delegate

// BAD: Composing but not delegating
class Car
{
    private Engine $engine;

    public function start()
    {
        // Forgot to use the engine!
        return "Car started";
    }
}

Problem: The component isn't used. It's just dead weight.
Fix: Always delegate the behavior to the composed component.

3. Exposing Internal Components

// BAD: Exposing internal components
class User
{
    public NotificationService $notifier; // Public property!

    public function sendNotification($message)
    {
        $this->notifier->send($this->email, $message);
    }
}

// Outside code can change the notifier
$user->notifier = new BadNotifier(); // Danger!

Problem: You've broken encapsulation. External code can manipulate internal state.
Fix: Make components private. Only expose methods that use them.

4. Interface Over-Design

// BAD: Every component must implement a huge interface
interface Loggable
{
    public function logInfo(string $message);
    public function logWarning(string $message);
    public function logError(string $message);
    public function logCritical(string $message);
    public function logDebug(string $message); // 5 methods!
}

Problem: You're violating ISP. Classes must implement methods they don't need.
Fix: Use smaller, focused interfaces. For example, LogInfo, LogError, etc.

5. "Trait Abuse"

// BAD: Using traits for everything
class User
{
    use Loggable, Notifiable, Authenticatable, Billable, \
        Cacheable, Validatable, Searchable, Exportable;
}

Problem: The class is now a dumping ground for behavior. You've just moved the problem from inheritance to traits.
Fix: Use traits only when they provide a single, well-defined behavior. Prefer composition over traits when you need to swap implementations.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is composition over inheritance?
A: A design principle that favors assembling objects with capabilities (composition) rather than creating deep class hierarchies (inheritance).
Q: When would you choose composition over inheritance?
A: When behavior is likely to change, is needed across unrelated classes, or when a class has multiple independent concerns.
Q: What's the difference between "is-a" and "has-a" relationships?
A: "Is-a" is inheritance (a Car is a Vehicle). "Has-a" is composition (a Car has an Engine).
Q: Can you use composition with inheritance in the same class?
A: Yes! They're not mutually exclusive. Use inheritance for the core "is-a" relationship and composition for additional behaviors.
Q: How does Laravel's Eloquent use composition?
A: Eloquent uses traits for specific behaviors like HasAttributes, HasTimestamps, and SoftDeletes. These are forms of composition.

Senior/Architect

Q: Explain the fragility problem with deep inheritance hierarchies.
A: The fragile base class problem occurs when a change in a parent class breaks child classes. Because the child classes depend on implementation details of the parent, even minor changes can cascade and break multiple classes.
Q: How does composition help with Liskov Substitution Principle violations?
A: With inheritance, you must ensure the child class can substitute the parent. Composition avoids this entirely because there is no substitution relationship. You're delegating to interfaces.
Q: Compare and contrast traits, interfaces, and composition in PHP.
A: Interfaces define contracts. Traits provide horizontal code reuse. Composition is the act of injecting behavior via dependencies. Interfaces + composition is the most flexible approach. Traits are convenient but can lead to the same problems as multiple inheritance.
Q: How would you refactor a large inheritance hierarchy to composition?
A: Identify the behaviors in the hierarchy. Extract each behavior into a separate class. Inject those classes as dependencies. Use interfaces to decouple the host from the components. Delegate behavior in the host.
Q: How does the Strategy pattern relate to composition?
A: The Strategy pattern is an implementation of composition. You inject a strategy (component) into a context (host), and the context delegates to the strategy. This allows the strategy to be swapped at runtime.

15. Interactive Practice Challenge

The Requirement

You're building a Document Processing System for a law firm. The system handles different types of documents:

Contracts: Need versioning, digital signatures, and approval workflows.
Invoices: Need billing, payment tracking, and tax calculations.
Reports: Need data aggregation, formatting, and export capabilities.

The current implementation uses inheritance and is becoming a nightmare to maintain.

The Code (POOR DESIGN)

// Base class
class Document
{
    protected string $title;
    protected string $content;
    protected array $metadata;
    protected array $history = [];

    public function save(): void
    {
        // Save to database
        \DB::table('documents')->insert([
            'title' => $this->title,
            'content' => $this->content,
            'metadata' => json_encode($this->metadata),
            'history' => json_encode($this->history),
        ]);
    }

    public function addHistory(string $entry): void
    {
        $this->history[] = ['timestamp' => now(), 'entry' => $entry];
    }
}

// Level 1
class Contract extends Document
{
    protected string $signatureStatus = 'draft';
    protected array $signatures = [];
    protected string $version = '1.0';

    public function sign(string $name, string $signature): void
    {
        $this->signatures[] = ['name' => $name, 'signature' => $signature, 'signed_at' => now()];
        $this->signatureStatus = 'signed';
        $this->addHistory("Signed by {$name}");
    }

    public function addVersion(string $version): void
    {
        $this->version = $version;
        $this->addHistory("New version: {$version}");
    }
}

// Level 2
class EmploymentContract extends Contract
{
    protected string $position;
    protected float $salary;
    protected string $startDate;

    public function calculateBenefits(): array
    {
        // Calculate based on position and salary
        return [
            'health_insurance' => $this->salary * 0.05,
            'retirement' => $this->salary * 0.08,
            'vacation_days' => $this->position === 'executive' ? 25 : 15,
        ];
    }
}

class ServiceContract extends Contract
{
    protected string $serviceType;
    protected array $deliverables;
    protected string $paymentTerms;

    public function calculateMilestones(): array
    {
        // Calculate payment milestones based on deliverables
        $milestoneAmount = 100000 / count($this->deliverables);
        $milestones = [];
        foreach ($this->deliverables as $index => $deliverable) {
            $milestones[] = [
                'deliverable' => $deliverable,
                'amount' => $milestoneAmount,
                'due_date' => now()->addDays($index * 30),
            ];
        }
        return $milestones;
    }
}

// Level 3 (More complexity!)
class IndependentContractorContract extends EmploymentContract
{
    protected string $agency;
    protected float $agencyFee;
    protected float $hourlyRate;

    public function calculateBenefits(): array
    {
        // Override: Contractors don't get benefits
        return [
            'health_insurance' => 0,
            'retirement' => 0,
            'vacation_days' => 0,
        ];
    }

    public function calculateInvoice(): array
    {
        // Calculate invoice with agency fee
        return [
            'hours' => 160,
            'rate' => $this->hourlyRate,
            'total' => $this->hourlyRate * 160,
            'agency_fee' => $this->agencyFee,
            'payout' => ($this->hourlyRate * 160) - $this->agencyFee,
        ];
    }
}

The Challenge

Now the law firm says:

"We need to add NDA documents that need a specific approval workflow."
"We need to add ComplianceReport that has both report formatting AND contract approval."
"We want to add document encryption capabilities to ALL documents."

The inheritance hierarchy is breaking down. NDA doesn't fit neatly anywhere. ComplianceReport needs behaviors from two different hierarchies.

Your Task: Refactor this system using composition over inheritance.

Questions to Consider

What behaviors are independent of the document type?
What interfaces would you define?
How would you compose a document from these behaviors?
How would you handle documents that need capabilities from multiple domains?
How would you test this system?

(We won't provide the solution—refactor this code and experience the flexibility of composition!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Composition over inheritance is a design principle that builds objects by assembling independent components (has-a) rather than creating deep class hierarchies (is-a).
One-sentence intuition: Build with Lego bricks, not with a mold. You can rearrange bricks infinitely; you're stuck with the mold forever.
One-sentence decision rule: If the behavior could be reused across unrelated classes or might change in the future, compose it; if the relationship is truly hierarchical and stable, inherit it.

17. Related Concepts

SOLID Principles

Open/Closed Principle: Composition enables extension without modification.
Liskov Substitution: Composition avoids LSP violations entirely.
Single Responsibility: Components are focused on one behavior.
Dependency Inversion: High-level hosts depend on abstraction components.

Design Patterns

Strategy Pattern: Encapsulates interchangeable algorithms via composition.
Decorator Pattern: Adds behavior by wrapping components.
Adapter Pattern: Composes to adapt interfaces.
Composite Pattern: Treats individual objects and compositions uniformly.
Bridge Pattern: Separates abstraction from implementation via composition.

Laravel Internals

Traits: Laravel's primary composition mechanism for models.
Service Providers: Compose application services.
Middleware: Compose request handling.
Pipeline: Compose processing steps.
Notifications: Compose notification channels.

Enterprise Patterns

Encapsulation: Composition is the ultimate encapsulation tool.
Dependency Injection: The mechanism to inject composed components.
Inversion of Control: The framework manages component composition.

Final Thoughts

Inheritance isn't evil. It's a tool—and like any tool, it has its place. But it's overused and often misapplied. The "is-a" relationship is much rarer than developers think.

Most of the time, you're dealing with capabilities, behaviors, and concerns. These are best modeled with composition. You can mix and match capabilities without the fragility of deep hierarchies.

The next time you start typing class Something extends AnotherThing, ask yourself: "Is this truly a hierarchy, or am I just sharing behavior? Could I compose this instead?"

Your future self—and your team—will thank you for the flexibility and maintainability.

Stop creating family trees. Start building toolkits.

Github: Composition Over Inheritance Practice Labs

From Procedural to Pro: Mastering Inversion of Control in Laravel

Anas Hussain — Fri, 17 Jul 2026 05:15:40 +0000

1. Hook & Problem Statement

You're building a Laravel application, and you need to send a notification. You type:

use Illuminate\Support\Facades\Mail;

Mail::to($user)->send(new WelcomeEmail($user));

It works beautifully. The email sends. You move on.

Later, you need to send an SMS notification. You add:

use Twilio\Rest\Client;

$twilio = new Client($sid, $token);
$twilio->messages->create($user->phone, ['from' => $number, 'body' => 'Welcome!']);

Again, it works. Your application grows. You add Slack notifications, push notifications, database notifications—each with their own initialization, configuration, and logic scattered across your controllers.

Everything works until the business says: "We need to add a delay before sending the welcome notification."

Or: "We need to log every notification sent."
Or worst of all: "We need to switch from Twilio to Vonage."

Suddenly, you're hunting through a dozen controller methods, updating the same logic in multiple places. Your code is rigid, repetitive, and resistant to change.

Why does this keep happening?

Because you're controlling the flow. You decide when and how to create objects. You're holding the reins, and as the application grows, those reins become tangled in a knot of dependencies.

What if you could flip that control? What if the framework told your code what to do, instead of your code telling the framework?

This is Inversion of Control (IoC) —the fundamental principle that powers Laravel's Service Container, event system, middleware pipeline, and queue system. You use it every day. You just didn't know it.

2. Why This Pattern/Concept Exists

The Problem It Solves

IoC solves a fundamental problem in software design: the Hollywood Principle—"Don't call us, we'll call you."

In traditional procedural or poorly designed object-oriented code, the application controls the flow. main() creates everything, calls everything, and decides everything. This works for small scripts, but as systems grow, the "main" function becomes a dumping ground for object creation, configuration, and orchestration.

The Pain That Existed Before

Before IoC became mainstream with frameworks like Spring (Java) and Laravel (PHP), developers faced:

The Main Class Monster: A single entry point that initialized every service, database connection, and configuration setting. Changing anything required touching this monolithic class.
Impossible Substitution: If you wanted to use a mock database during testing, you had to modify the main class or use complex reflection hacks.
Global State Addiction: Developers used global variables and singletons to share dependencies, leading to code that was impossible to reason about and even harder to test.
The Bootstrap Trap: Configuration was scattered across files, command-line arguments, and environment variables—all parsed and consumed in the main class.

Why Large Applications Need It

As your application scales, complexity shifts from "what to do" to "how to orchestrate."

Consider a modern Laravel application:

Request enters public/index.php
The Kernel (\App\Http\Kernel) takes over
Middleware is executed (session, authentication, CSRF)
Router finds the matching controller
Controller method is called with resolved dependencies
Response is rendered and sent

At no point does your code decide the order of these operations. The framework controls the flow. It calls you.

This decoupling allows you to:

Swap implementations (use a different mail driver)
Insert cross-cutting concerns (add logging without touching business logic)
Test in isolation (replace real services with mocks)
Extend gracefully (add new middleware without modifying the kernel)

3. Real World Analogy

The Hotel Concierge

Imagine you're staying at a luxury hotel. You need:

A taxi to the airport
Restaurant reservations
Theater tickets
Dry cleaning service

The Bad Way (No IoC):
You personally:

Call the taxi company directly
Call the restaurant yourself
Walk to the theater to buy tickets
Find the dry cleaning shop

You're controlling everything, but you're exhausted, and you have to know every phone number and location. If the taxi company changes its number, you're stuck.

The IoC Way:
You call the concierge (the framework) and say: "I need a taxi, restaurant reservations, theater tickets, and my suit pressed."

The concierge handles:

Which taxi company to use (based on availability)
Which restaurant to book (based on your preferences)
Where to get the tickets (based on inventory)
When to pick up your suit (based on the schedule)

You don't control the details. The concierge does. You just provide the requirements.

Analogy Mapping:

Concierge: The Laravel Service Container / Application instance
Guest (You): Your application code
Service Providers: The concierge's network of contacts
Dependencies: Taxi, restaurant, theater, dry cleaner
Configuration: Your preferences (e.g., "I prefer Italian food")
The "Flow": The concierge orchestrates everything, calling providers as needed

The key insight: You don't call the service; the concierge calls the service on your behalf.

4. The Pain (Bad Design)

Let's look at a typical Laravel controller written without understanding IoC.

namespace App\Http\Controllers;

use App\Models\Order;
use App\Models\User;
use Illuminate\Http\Request;
use Twilio\Rest\Client;

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // Hard dependency on Twilio
        $twilio = new Client(
            env('TWILIO_SID'),
            env('TWILIO_TOKEN')
        );

        // Hard dependency on database
        $order = new Order();
        $order->user_id = $request->user_id;
        $order->total = $request->total;
        $order->status = 'pending';
        $order->save();

        // Send SMS
        $user = User::find($request->user_id);
        $twilio->messages->create(
            $user->phone,
            ['from' => env('TWILIO_NUMBER'), 'body' => "Order #{$order->id} created!"]
        );

        // Log the creation (hard dependency on Log)
        \Log::info('Order created', ['order_id' => $order->id]);

        return response()->json($order, 201);
    }
}

Why This Is Painful

Tight Coupling: The controller is tightly coupled to Twilio's client, the Order model, and the Log facade. If Twilio changes its API, this controller breaks.
Difficult Testing: To unit test this, you need to:
- Configure real Twilio credentials (or mock the client, which requires reflection)
- Connect to a real database (slow and unpredictable)
- Manage real filesystem permissions for logging
Difficult Replacement: When the business switches to Vonage for SMS, you must modify this controller. If you use SMS in 20 places, you're updating 20 files.
Violates SOLID:
- SRP: The controller handles HTTP requests, database operations, SMS sending, and logging.
- OCP: Adding a new notification channel (Slack) requires modifying the controller.
- DIP: The controller depends on concrete implementations (Twilio, Eloquent), not abstractions.

Why Developers Write Code Like This

We write code like this because:

It's fast to write when prototyping
We're not thinking about the future
We don't know any better (the "just get it done" syndrome)
We're afraid of "over-engineering"

The cost? Technical debt that compounds with every new feature.

5. Solution Overview

Inversion of Control (IoC) is the principle that inverts the flow of control in a system. Instead of your code controlling the flow of execution, the framework or container calls your code at the appropriate times.

Core Idea

Instead of the application creating dependencies and orchestrating logic, the application defines dependencies, and the container provides them when needed.

Main Participants

The Framework/Container: The entity that manages object creation, dependency resolution, and lifecycle.
The Client Code: Your classes (Controllers, Services, etc.) that define what they need.
The Provider: Classes that register dependencies with the container (Service Providers).
The Configuration: The rules that tell the container how to resolve dependencies.

How Objects Collaborate

The container is the "smart factory." When you ask for PaymentService, the container:

Looks at the constructor parameters
Checks the service bindings
Resolves each dependency recursively
Creates the final object with all dependencies injected

Mental Model

Think of your application as a movie.

Without IoC: Actors (your classes) write their own scripts, direct themselves, and build the sets.
With IoC: The Director (the container) tells the actors when to enter, what to say, and hands them their props (dependencies).

The actors only focus on acting. The director handles the orchestration.

Benefits

Decoupling: Classes are isolated from their dependencies
Testability: Dependencies can be mocked
Flexibility: Swap implementations via configuration
Standardization: Consistent object creation across the application

Trade-offs

Indirection: It's harder to trace where implementations come from
Complexity: The container adds a learning curve
Performance: Reflection-based resolution has overhead (though Laravel caches resolutions)

6. UML Diagram

Laravel Inversion of Control Mermaid Diagram

Diagram Explanation

Client declares its dependencies (the DependencyInterface in its constructor).
Container manages bindings between interfaces and concrete classes.
ServiceProviders register these bindings with the Container.
When the Application starts, the Container reads the bindings and can construct any object.
The Client receives the ConcreteDependency through injection, but only depends on the Interface.

7. Vanilla PHP Example

Let's refactor the OrderController using pure PHP to demonstrate IoC.

Before Refactoring

class OrderProcessor
{
    public function process($orderData)
    {
        // Hardcoded database connection
        $db = new Database('localhost', 'root', 'password', 'orders');
        $db->query("INSERT INTO orders ...");

        // Hardcoded email service
        $mailer = new Mailer('smtp.gmail.com', 'user', 'pass');
        $mailer->send('admin@site.com', 'Order processed');

        // Hardcoded logger
        $logger = new FileLogger('/var/log/orders.log');
        $logger->log('Order processed successfully');

        return true;
    }
}

After Refactoring (IoC)

// Step 1: Define interfaces (abstractions)
interface DatabaseInterface
{
    public function query(string $sql): void;
}

interface MailerInterface
{
    public function send(string $to, string $message): void;
}

interface LoggerInterface
{
    public function log(string $message): void;
}

// Step 2: Implement concretions
class MySqlDatabase implements DatabaseInterface
{
    public function __construct(private array $config) {}

    public function query(string $sql): void
    {
        // MySQL implementation
    }
}

class PostgresDatabase implements DatabaseInterface
{
    public function __construct(private array $config) {}

    public function query(string $sql): void
    {
        // PostgreSQL implementation
    }
}

class SmtpMailer implements MailerInterface { /* implementation */ }
class FileLogger implements LoggerInterface { /* implementation */ }

// Step 3: The client (inverted control)
class OrderProcessor
{
    public function __construct(
        private readonly DatabaseInterface $database,
        private readonly MailerInterface $mailer,
        private readonly LoggerInterface $logger
    ) {}

    public function process($orderData): void
    {
        $this->database->query("INSERT INTO orders ...");
        $this->mailer->send('admin@site.com', 'Order processed');
        $this->logger->log('Order processed successfully');
    }
}

// Step 4: The "Container" (simple IoC implementation)
class SimpleContainer
{
    private array $bindings = [];

    public function bind(string $interface, string $concrete): void
    {
        $this->bindings[$interface] = $concrete;
    }

    public function make(string $class): object
    {
        // Reflection to resolve dependencies
        $reflection = new \ReflectionClass($class);
        $constructor = $reflection->getConstructor();

        if (!$constructor) {
            return $reflection->newInstance();
        }

        $parameters = $constructor->getParameters();
        $dependencies = [];

        foreach ($parameters as $parameter) {
            $type = $parameter->getType();
            if (!$type || $type->isBuiltin()) {
                throw new \Exception("Cannot resolve parameter: {$parameter->getName()}");
            }

            $interface = $type->getName();
            $concrete = $this->bindings[$interface] ?? $interface;
            $dependencies[] = $this->make($concrete);
        }

        return $reflection->newInstanceArgs($dependencies);
    }
}

// Step 5: Usage (the container controls the flow)
$container = new SimpleContainer();

// Register bindings (configuration)
$container->bind(DatabaseInterface::class, MySqlDatabase::class);
$container->bind(MailerInterface::class, SmtpMailer::class);
$container->bind(LoggerInterface::class, FileLogger::class);

// The container creates the processor with all dependencies
$processor = $container->make(OrderProcessor::class);
$processor->process($orderData);

What We Improved

Loose Coupling: OrderProcessor only depends on interfaces.
Testability: We can pass mock implementations during testing.
Flexibility: Changing from MySQL to PostgreSQL only requires changing the binding.
Single Responsibility: Each class has one job.
Extensibility: Adding a new logger only requires a new implementation of LoggerInterface.

8. Laravel Internal Example

Laravel is built entirely around IoC. Let's look at where this principle powers the framework.

The Service Container (Core IoC Implementation)

Laravel's Illuminate\Container\Container is the heart of IoC in Laravel. It manages bindings, resolves dependencies, and controls object lifecycles.

// Laravel's Container in action
app()->bind(PaymentGatewayInterface::class, StripeGateway::class);
app()->make(PaymentController::class); // Recursively resolves all dependencies

Service Providers (Configuration Layer)

Service Providers register services with the container. This is where you tell the container how to resolve your dependencies.

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\PaymentGatewayInterface;
use App\Services\StripeGateway;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register binding (configuration)
        $this->app->bind(PaymentGatewayInterface::class, StripeGateway::class);
    }
}

The HTTP Kernel (Flow Control)

The HTTP Kernel is an excellent example of IoC. You don't control the request flow; the Kernel does.

// Kernel.php
protected $middleware = [
    \Illuminate\Http\Middleware\HandleCors::class,
    \Illuminate\Foundation\Http\Middleware\ValidatePostSize::class,
    // ...
];

protected $middlewareGroups = [
    'web' => [
        \Illuminate\Cookie\Middleware\EncryptCookies::class,
        \Illuminate\Session\Middleware\StartSession::class,
        // ...
    ],
];

// The Kernel calls your middleware, not the other way around

Events and Listeners

The Event system is a powerful IoC implementation. You define events and listeners, and the system calls them when needed.

// You define the mapping
protected $listen = [
    OrderCreated::class => [
        SendOrderConfirmationEmail::class,
        NotifyWarehouse::class,
        UpdateInventory::class,
    ],
];

// The system controls the flow:
// 1. Event is fired
// 2. Container resolves listeners
// 3. Listeners are executed in order

Middleware Pipeline

The Pipeline pattern in Laravel uses IoC to control execution flow:

// You define middleware in the pipeline
$response = (new Pipeline($container))
    ->send($request)
    ->through([\App\Http\Middleware\TrimStrings::class])
    ->then(function ($request) {
        return $controller->handle($request);
    });

The pipeline controls the flow, calling each middleware in sequence.

Why Laravel's Implementation Is Elegant

Transparent Resolution: You rarely interact with the container directly.
Autowiring: Dependencies are resolved automatically via reflection.
Contextual Binding: Different implementations can be provided for different contexts.
Tagging: Related services can be grouped and resolved together.
Deferred Providers: Services are only loaded when needed, improving performance.

9. Real Laravel Application Example

Let's build a complete example of a Notification System using IoC principles.

Scenario

You're building a SaaS platform that needs to send notifications via email, SMS, and Slack. Different users have different notification preferences. The system should be easy to extend with new notification channels.

Implementation

Step 1: Define the Core Interface

// app/Contracts/NotificationChannel.php
namespace App\Contracts;

interface NotificationChannel
{
    public function send(string $recipient, string $message): void;
}

Step 2: Implement Channels

// app/Notifications/Channels/EmailChannel.php
namespace App\Notifications\Channels;

use App\Contracts\NotificationChannel;
use Illuminate\Support\Facades\Mail;
use App\Mail\NotificationMessage;

class EmailChannel implements NotificationChannel
{
    public function send(string $recipient, string $message): void
    {
        Mail::to($recipient)->send(new NotificationMessage($message));
    }
}

// app/Notifications/Channels/SmsChannel.php
namespace App\Notifications\Channels;

use App\Contracts\NotificationChannel;
use Twilio\Rest\Client;

class SmsChannel implements NotificationChannel
{
    public function __construct(
        private readonly Client $twilio
    ) {}

    public function send(string $recipient, string $message): void
    {
        $this->twilio->messages->create($recipient, [
            'from' => config('services.twilio.from'),
            'body' => $message,
        ]);
    }
}

// app/Notifications/Channels/SlackChannel.php
namespace App\Notifications\Channels;

use App\Contracts\NotificationChannel;
use Illuminate\Support\Facades\Http;

class SlackChannel implements NotificationChannel
{
    public function send(string $recipient, string $message): void
    {
        Http::post(config('services.slack.webhook_url'), [
            'text' => $message,
            'channel' => $recipient,
        ]);
    }
}

Step 3: The Notification Manager (Service)

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

use App\Contracts\NotificationChannel;
use App\Models\User;
use Illuminate\Support\Collection;

class NotificationService
{
    private Collection $channels;

    public function __construct()
    {
        $this->channels = collect();
    }

    public function addChannel(string $name, NotificationChannel $channel): self
    {
        $this->channels->put($name, $channel);
        return $this;
    }

    public function notify(User $user, string $message): void
    {
        $preferences = $user->notification_preferences ?? ['email'];

        foreach ($preferences as $channelName) {
            if ($this->channels->has($channelName)) {
                $recipient = $this->getRecipient($user, $channelName);
                $this->channels->get($channelName)->send($recipient, $message);
            }
        }
    }

    private function getRecipient(User $user, string $channel): string
    {
        return match($channel) {
            'email' => $user->email,
            'sms' => $user->phone,
            'slack' => $user->slack_channel,
            default => '',
        };
    }
}

Step 4: Service Provider (Configuration)

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

use App\Contracts\NotificationChannel;
use App\Notifications\Channels\EmailChannel;
use App\Notifications\Channels\SmsChannel;
use App\Notifications\Channels\SlackChannel;
use App\Services\NotificationService;
use Illuminate\Support\ServiceProvider;

class NotificationServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register individual channels (singletons)
        $this->app->singleton(EmailChannel::class);
        $this->app->singleton(SmsChannel::class);
        $this->app->singleton(SlackChannel::class);

        // Register the notification service
        $this->app->singleton(NotificationService::class, function ($app) {
            $service = new NotificationService();

            // Add all available channels
            $service->addChannel('email', $app->make(EmailChannel::class));
            $service->addChannel('sms', $app->make(SmsChannel::class));
            $service->addChannel('slack', $app->make(SlackChannel::class));

            return $service;
        });
    }
}

Step 5: Controller

// app/Http/Controllers/NotificationController.php
namespace App\Http\Controllers;

use App\Models\User;
use App\Services\NotificationService;
use Illuminate\Http\Request;

class NotificationController extends Controller
{
    public function __construct(
        private readonly NotificationService $notificationService
    ) {}

    public function send(Request $request, User $user)
    {
        $this->notificationService->notify(
            $user,
            $request->input('message')
        );

        return response()->json(['message' => 'Notification sent']);
    }
}

The Magic of IoC in Action

The container resolves NotificationService and all its dependencies.
The service provider configures which channels are available.
The controller doesn't know about Twilio, Slack, or Mail. It just calls notify().
Adding a new channel (e.g., Telegram) only requires:
- Creating a TelegramChannel class
- Adding it to the service provider
- Nothing else! The controller is untouched.

10. SOLID Principles Mapping

D - Dependency Inversion Principle (DIP)

This is the most direct mapping. DIP states that high-level modules should not depend on low-level modules; both should depend on abstractions.

High-level module: NotificationService (manages notifications)
Low-level module: SmsChannel (sends SMS)
Abstraction: NotificationChannel interface

NotificationService depends on NotificationChannel, not SmsChannel directly. The container provides the concrete implementation.

O - Open/Closed Principle (OCP)

The NotificationService is closed for modification but open for extension.

Closed: We never modify NotificationService to add a new channel.
Open: We add a new class implementing NotificationChannel and register it in the service provider.

L - Liskov Substitution Principle (LSP)

All channel implementations (EmailChannel, SmsChannel, SlackChannel) are substitutable for each other. The NotificationService uses them interchangeably, and they all satisfy the NotificationChannel contract.

S - Single Responsibility Principle (SRP)

Each class has a single responsibility:

EmailChannel: Sends emails
SmsChannel: Sends SMS
NotificationService: Orchestrates notification delivery
NotificationController: Handles HTTP requests

I - Interface Segregation Principle (ISP)

The NotificationChannel interface is focused and minimal. It has exactly one method: send(). No class is forced to implement methods it doesn't use.

11. Trade-offs

Benefits

Flexibility: Swapping implementations is a configuration change, not a code change.
Testability: Mock dependencies easily during unit testing.
Extensibility: Add new features without modifying existing code.
Maintainability: Changes to one component don't cascade to others.
Parallel Development: Teams can work on different components independently.

Costs

Indirection: It's harder to trace code execution. You see NotificationChannel and need to find which concrete class is bound.
Configuration Overhead: You need to configure bindings (Service Providers) for every abstraction.
Learning Curve: New developers need to understand the container, reflection, and binding mechanisms.
Performance: Reflection-based resolution is slower than direct instantiation (though Laravel's cache mitigates this).
Over-engineering Risk: Adding interfaces and abstractions for simple, stable dependencies adds complexity without benefit.

When Is Complexity Justified?

Use IoC when:

The dependency is likely to change (external APIs, business rules)
The dependency has significant configuration overhead
You need to test the class in isolation
The class is used in multiple places across the application

Avoid IoC when:

The dependency is a simple data container (DTO)
The dependency is stable and unlikely to change (PHP built-in classes)
You're building a one-off script or prototype

12. When NOT To Use It

3 Green Flags (USE IT)

External Integrations: APIs, payment gateways, notification services, cloud providers.
Business Logic: Complex domain logic that needs extensive testing.
Database Access: Repository patterns, query builders, ORM abstractions.

3 Red Flags (AVOID IT)

Data Transfer Objects (DTOs): Simple data containers with no behavior don't need IoC.
Utility Functions: Stateless helper functions (e.g., str_slug(), array_flatten()) don't benefit from IoC.
Stable Internal Dependencies: PHP core classes (e.g., DateTime, SplFileInfo) are unlikely to change and don't need abstraction.

13. Common Mistakes

1. The Service Locator Anti-Pattern

// BAD: Using the container as a service locator
class OrderService
{
    public function process(Order $order): void
    {
        $logger = app(LoggerInterface::class); // Hidden dependency!
        $logger->info('Processing order');
    }
}

Problem: The dependency is hidden. You can't see what the class needs by looking at its constructor. Testing becomes harder because the class depends on the global container.

Fix: Use constructor injection.

// GOOD: Constructor injection
class OrderService
{
    public function __construct(
        private readonly LoggerInterface $logger
    ) {}

    public function process(Order $order): void
    {
        $this->logger->info('Processing order');
    }
}

2. Premature Abstraction

// BAD: Abstracting everything
interface CalculatorInterface
{
    public function add(int $a, int $b): int;
}

class Calculator implements CalculatorInterface
{
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }
}

Problem: You don't need abstraction for a simple, stable operation. This adds complexity without benefit.

Fix: Only abstract when you have multiple implementations or need to mock.

3. Putting Business Logic in Service Providers

// BAD: Service provider doing business logic
class AppServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        $user = User::first(); // Business logic in boot!
        if ($user->isAdmin()) {
            // Do something
        }
    }
}

Problem: Service providers are for registration, not execution. This runs on every request and makes bootstrapping slow.

Fix: Move business logic to services or middleware.

4. Forgetting to Bind Interfaces

// Controller
class ReportController extends Controller
{
    public function __construct(
        private readonly ReportGeneratorInterface $generator
    ) {}
}

// Service Provider (You forgot to bind!)
// No binding for ReportGeneratorInterface

Result: Illuminate\Contracts\Container\BindingResolutionException - Target class not instantiable.

Fix: Always bind interfaces to concrete implementations in a service provider.

5. Resolving Dependencies at the Wrong Time

// BAD: Resolving in the constructor before boot
class UserService
{
    private $settings;

    public function __construct()
    {
        $this->settings = app(SettingsService::class); // Too early!
        // SettingsService might not be fully configured yet
    }
}

Problem: The service provider for SettingsService might not have booted yet.

Fix: Resolve in the method that needs it, or use lazy loading.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is Inversion of Control?
A: A design principle where the framework controls the flow of execution and calls your code, rather than your code calling the framework.
Q: What's the difference between IoC and Dependency Injection?
A: IoC is the broader principle (who controls the flow). DI is a specific implementation of IoC (how dependencies are provided to a class).
Q: How does Laravel's Service Container implement IoC?
A: The container manages object creation and dependency resolution. You bind interfaces to concrete classes, and the container automatically injects them.
Q: What is the app() helper in Laravel?
A: It returns the application instance (the container). You can use it to resolve dependencies, but constructor injection is preferred.
Q: What are Service Providers in Laravel?
A: Classes that register services, bindings, and configurations with the container. They're the configuration layer for IoC.

Senior/Architect

Q: Explain the difference between bind and singleton in Laravel's container.
A: bind creates a new instance every time it's resolved. singleton resolves once and reuses the same instance for the duration of the request.
Q: How would you handle circular dependencies in an IoC container?
A: Circular dependencies (A requires B, B requires A) cause resolution to fail. Solutions include:
- Redesigning the classes to break the cycle
- Using setter injection for one of the dependencies
- Using the Proxy pattern (Laravel's deferred resolution)
Q: What is contextual binding and when would you use it?
A: Contextual binding provides different implementations of an interface based on where it's injected. For example, inject Stripe for PaymentController but PayPal for AdminController.

$this->app->when(PaymentController::class)
          ->needs(PaymentGatewayInterface::class)
          ->give(StripeGateway::class);

$this->app->when(AdminController::class)
          ->needs(PaymentGatewayInterface::class)
          ->give(PayPalGateway::class);

Q: How does Laravel's pipeline pattern relate to IoC?
A: The pipeline controls the flow of execution through middleware. It decides the order of execution, inverting control from the middleware classes to the pipeline itself.
Q: What are the performance implications of using an IoC container?
A: Reflection-based resolution adds overhead. Laravel mitigates this by caching resolved bindings using php artisan config:cache and php artisan optimize. In production, the performance hit is minimal.

15. Interactive Practice Challenge

The Requirement

You're building an e-commerce application. You've inherited the following code for processing returns and refunds. It works, but it's tightly coupled and difficult to maintain.

The Code (POOR DESIGN)

namespace App\Http\Controllers;

use App\Models\Order;
use App\Models\ReturnRequest;
use Illuminate\Http\Request;
use Stripe\StripeClient;

class ReturnController extends Controller
{
    public function process(Request $request, Order $order)
    {
        // Validate the return
        if ($request->input('reason') === '') {
            return response()->json(['error' => 'Reason required'], 400);
        }

        if ($order->status !== 'delivered') {
            return response()->json(['error' => 'Order not delivered'], 400);
        }

        // Create the return request
        $return = new ReturnRequest();
        $return->order_id = $order->id;
        $return->reason = $request->input('reason');
        $return->status = 'pending';
        $return->save();

        // Process refund with Stripe
        $stripe = new StripeClient(env('STRIPE_SECRET'));

        try {
            $refund = $stripe->refunds->create([
                'payment_intent' => $order->stripe_payment_intent,
                'amount' => $order->total * 100, // Stripe uses cents
            ]);

            $return->status = 'refunded';
            $return->refund_id = $refund->id;
            $return->save();

            // Send email notification
            \Mail::to($order->user->email)->send(new \App\Mail\RefundProcessed($return));

            // Log the action
            \Log::info('Return processed', [
                'order_id' => $order->id,
                'return_id' => $return->id,
                'refund_id' => $refund->id,
            ]);

            return response()->json($return, 200);
        } catch (\Exception $e) {
            \Log::error('Refund failed', ['error' => $e->getMessage()]);
            return response()->json(['error' => 'Refund failed'], 500);
        }
    }
}

Your Challenge

Refactor this code using Inversion of Control principles. Specifically, you should:

Extract responsibilities into separate classes (Single Responsibility Principle).
Define abstractions (interfaces) for external services (payment, email, logging).
Create service classes that handle the business logic (return processing, refund processing).
Use dependency injection to provide dependencies to the controller.
Implement a service provider to register the bindings.

Questions to Consider

How would you test this controller?
How would you switch from Stripe to PayPal?
How would you add a new notification channel (SMS) for refund status?
How would you handle different payment gateways for different regions?

(We won't provide the solution—refactor this code and see how much cleaner it becomes!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Inversion of Control is a design principle where the framework controls the flow of execution and provides dependencies to your code, rather than your code controlling the flow and creating dependencies.
One-sentence intuition: Stop being the director; become the actor. Let the framework tell you what to do and give you what you need.
One-sentence decision rule: If a class needs to instantiate or configure a dependency that might change or needs mocking, invert control by injecting that dependency rather than creating it internally.

17. Related Concepts

SOLID Principles

Dependency Inversion (DIP): IoC is the architectural implementation of DIP.
Open/Closed (OCP): IoC enables extension without modification.
Single Responsibility (SRP): IoC forces separation of concerns.

Design Patterns

Dependency Injection: The primary implementation of IoC for object construction.
Factory Pattern: Often used alongside IoC to create complex objects.
Strategy Pattern: IoC is the mechanism for injecting the strategy.
Observer Pattern: Event systems use IoC to resolve and execute listeners.
Pipeline Pattern: Used in middleware to invert control through request processing.

Laravel Internals

Service Container: The core IoC implementation in Laravel.
Service Providers: The configuration layer for IoC bindings.
Facades: A simplified, static interface to services managed by the container.
Middleware: Uses IoC to resolve and execute middleware classes.
Event System: Uses IoC to resolve listeners when events are fired.
Queue System: Uses IoC to resolve job classes and their dependencies.

Enterprise Patterns

Inversion of Control Container: A framework for managing dependencies.
Dependency Injection Container: The specific term used in many frameworks.
Service Locator: An anti-pattern often confused with IoC.
Contextual Dependency Injection: Providing different implementations based on context.

Final Thoughts

Inversion of Control isn't just a "nice-to-have" pattern—it's the foundation upon which Laravel (and most modern frameworks) is built. When you understand IoC, you stop fighting the framework and start leveraging its power.

You begin to see your application not as a collection of scripts, but as a system of interchangeable, testable, and maintainable components. You stop asking, "How do I do X?" and start asking, "How do I design my system so that X is easy to do?"

This is the mark of a senior engineer: not just knowing how to do something, but understanding why the architecture exists and how to leverage it effectively.

The next time you use Laravel's container, middleware, or event system, remember: you're not just writing code; you're participating in a pattern that's stood the test of time. You're inverting control.

Github: Inversion of Control Practice Labs

Why Laravel's Service Container Feels Like Magic: Dependency Injection Explained

Anas Hussain — Tue, 14 Jul 2026 05:34:49 +0000

1. Hook & Problem Statement

You’ve been there. You're building a Laravel application, and everything is going smoothly. You type Route::get('/orders', [OrderController::class, 'index']), define your method, and suddenly—you need to send an email.

You type-hint MailerInterface $mailer in your constructor, and boom—it just works. You don't instantiate anything. You don't see a new keyword. It feels like the framework reached into the ether, grabbed the object you needed, and handed it to you.

"How did that get there?" you ask yourself. "Is it voodoo? Is it magic?"

For many developers, the Laravel Service Container remains a black box. It’s the "magic" behind the scenes that we accept, but don't truly understand. This causes a problem: when the magic breaks, you’re left helpless. When you have to write your own services, you default to new and static calls, creating code that is impossible to test and impossible to change.

Today, we’re going to take the wizard hat off the Service Container and look at the engineering underneath. We are going to demystify the magic.

2. Why This Pattern/Concept Exists

Before we can understand the container, we must understand the problem it solves.

The Coupling Catastrophe

Imagine a PaymentProcessor that relies on a StripeAPI class. If you create the Stripe object inside the PaymentProcessor using new StripeAPI(), you have created a tight coupling.

class PaymentProcessor {
    public function __construct() {
        $this->stripe = new StripeAPI(); // Hard dependency
    }
}

The Pain That Existed Before

Before patterns like Dependency Injection (DI) became mainstream, developers faced a "Big Ball of Mud."

Impossible to Test: How do you test the PaymentProcessor without actually charging a credit card? You can't mock StripeAPI because it's hardcoded.
Impossible to Replace: What happens when the business decides to switch from Stripe to PayPal? You have to rip open the PaymentProcessor and rewrite it. This violates the Open/Closed Principle (OCP).
The "Ripple Effect": If StripeAPI requires a new HttpClient in its constructor, you now have to update every single place where you call new StripeAPI().

Why Large Applications Need It

As your application scales, the complexity of object graphs grows. Consider a User Service that needs a Logger, a Mailer, and a Repository. Those dependencies might need their own dependencies.

Manually managing this chain of new statements (new A(new B(new C()))) becomes a maintenance nightmare. The Container solves the problem of managing object construction and lifecycle, allowing you to focus on the business logic rather than the plumbing.

The bottom line: We need a way to ask for what we need, without knowing how to build it. We need to shift the responsibility of building objects to a "factory" of factories.

3. Real World Analogy

The Restaurant
Think of your Laravel Application as a high-end restaurant. You (the Controller) are the waiter. The Kitchen (the Service Container) is in the back.

The Bad Way (No DI): If you, the waiter, had to grow the vegetables, butcher the meat, and bake the bread every time a customer ordered a burger, you would be terrible at your job. You are tightly coupled to the food supply chain.
The DI Way: You walk to the kitchen pass (the Constructor) and say, "I need a Burger with a side of Fries." You don't care which chef makes it, what oven they use, or where the beef came from. You just know that if you ask the kitchen for it, you will receive a prepared item.
Analogy Mapping:
- Waiter (Client): The OrderController.
- The Request (Order): The __construct or __invoke method.
- The Kitchen (Container): The Laravel Service Container.
- The Recipe (Binding): The Service Provider ($this->app->bind).
- The Chef (Factory): The build process that resolves the dependencies.

The kitchen handles the complexity so the waiter can focus on service.

4. The Pain (Bad Design)

Let’s look at a typical "Dependency Hell" situation in a Laravel application.

class PdfExporter
{
    public function export(Invoice $invoice): string
    {
        // 1. Hard dependency on a specific library
        $dompdf = new Dompdf();

        // 2. Hard dependency on the Filesystem to save it
        $path = storage_path('app/invoices/');
        if (!is_dir($path)) {
            mkdir($path, 0777, true);
        }

        $html = view('invoices.pdf', compact('invoice'))->render();
        $dompdf->loadHtml($html);
        $dompdf->render();
        $output = $dompdf->output();
        file_put_contents($path . $invoice->id . '.pdf', $output);

        return $path . $invoice->id . '.pdf';
    }
}

Why is this terrible?

Tight Coupling: PdfExporter is tied to Dompdf. If you want to use Tcpdf, you must change this code.
Testing Nightmare: To unit test this, you must generate a real PDF and write to the file system. Your tests will be slow, fragile, and require disk space.
Violates SRP: This class is doing a lot. It's generating the HTML, saving the file, and generating the PDF.
Magic Strings: The path is hardcoded.

This code is rigid. It cannot be extended, and it is resistant to change.

5. Solution Overview

Dependency Injection is a principle that states: A class should not instantiate its dependencies; it should ask for them.

Core Idea

Instead of a class looking for its dependencies (via new or static calls), it receives them from the outside.

Main Participants

The Client: The class that needs a service (e.g., PdfExporter).
The Dependencies: The services the client needs (e.g., PdfInterface, FileSystemInterface).
The Injector: The entity that creates the dependencies and passes them to the client (e.g., the Laravel Service Container).

Mental Model

Think of the __construct method as a contract. It is a promise: "If you (the Container) give me these objects, I will handle the rest." You write your code to be handed objects, rather than hunting for them.

Benefits

Loose Coupling: Your class only depends on the interface, not the implementation.
High Testability: You can pass "Mock" objects into the constructor easily.
Code Reusability: The dependency can be swapped out for different environments.

Trade-offs

Abstraction Overhead: You will have more interfaces and classes.
Indirection: It's sometimes harder to trace where an implementation is coming from.

6. UML Diagram

Laravel Service Container Architecture

Explanation: The Container is aware of ConcreteDependencyA and ConcreteDependencyB. The Client only knows about the DependencyInterface. The Container injects the correct concrete implementation into the Client at runtime.

7. Vanilla PHP Example

Let's refactor the PdfExporter using pure PHP 8+ syntax to show the power of DI.

Before Refactoring

(As seen in the "Pain" section—hardcoded Dompdf, file paths, etc.)

After Refactoring

Step 1: Define Interfaces (The Contract)

interface PdfGeneratorInterface
{
    public function generate(string $html): string; // returns PDF binary string
}

interface FileStorageInterface
{
    public function save(string $path, string $content): bool;
}

Step 2: Create Implementations

class DompdfGenerator implements PdfGeneratorInterface
{
    public function __construct(
        private array $options = [] // configuration passed via constructor
    ) {}

    public function generate(string $html): string
    {
        $dompdf = new \Dompdf\Dompdf($this->options);
        $dompdf->loadHtml($html);
        $dompdf->render();
        return $dompdf->output();
    }
}

class LocalFileStorage implements FileStorageInterface
{
    public function __construct(
        private string $basePath
    ) {}

    public function save(string $path, string $content): bool
    {
        $fullPath = rtrim($this->basePath, '/') . '/' . ltrim($path, '/');
        $directory = dirname($fullPath);
        if (!is_dir($directory)) {
            mkdir($directory, 0777, true);
        }
        return file_put_contents($fullPath, $content) !== false;
    }
}

Step 3: The Refactored Client

class PdfExporter
{
    // Dependency Injection via Constructor Promotion (PHP 8)
    public function __construct(
        private readonly PdfGeneratorInterface $pdfGenerator,
        private readonly FileStorageInterface $fileStorage
    ) {}

    public function export(Invoice $invoice): string
    {
        $html = view('invoices.pdf', compact('invoice'))->render();
        $pdfContent = $this->pdfGenerator->generate($html);

        $path = "invoices/{$invoice->id}.pdf";
        $this->fileStorage->save($path, $pdfContent);

        return $path;
    }
}

Step 4: The Manual Injector (The "Container")

// This is essentially what Laravel does for you.
$generator = new DompdfGenerator(['isRemoteEnabled' => true]);
$storage = new LocalFileStorage(storage_path('app'));

$exporter = new PdfExporter($generator, $storage);
$exporter->export($invoice);

What did we improve?

Testability: In a test, we can pass a MockPdfGenerator that returns a dummy string without hitting the file system or the PDF library.
Open/Closed: If we need a TcpdfGenerator, we just implement the interface. We don't touch PdfExporter.
Single Responsibility: Each class has one job.

8. Laravel Internal Example

Where does Laravel use this? Everywhere.

The HTTP Kernel

Have you ever looked inside app/Http/Kernel.php? It handles middleware.
When a Request comes in, the Kernel resolves the Router and the ControllerDispatcher. It doesn't new them; it asks the container for them.

The `handle` Method in Controllers

Laravel doesn't just resolve Controllers; it resolves the parameters inside them.

class InvoiceController {
    public function show(InvoiceRepository $repo, int $id) { ... }
}

When Laravel routes to this controller, it looks at the method signature. It uses the Container to build InvoiceRepository (and all its sub-dependencies) and injects them, alongside the primitive $id.

Service Providers

Service Providers are the central location for "Binding" things into the container. This is how we tell the container which concrete class to use when an interface is requested.

// In a Service Provider
public function register(): void
{
    $this->app->bind(PdfGeneratorInterface::class, DompdfGenerator::class);
}

This is the "recipe" that tells the container: "When someone asks for PdfGeneratorInterface, give them DompdfGenerator."

9. Real Laravel Application Example

Let's build a Payment Gateway System for an e-commerce app.

Scenario: You support Stripe and PayPal. The business logic (like processing the cart) should not care which gateway is used.

Step 1: The Interface

namespace App\Contracts\Payment;

interface PaymentGatewayInterface
{
    public function charge(array $customerData, float $amount): array;
    public function refund(string $transactionId, float $amount): bool;
}

Step 2: Concrete Implementations

namespace App\Services\Payment;

use App\Contracts\Payment\PaymentGatewayInterface;

class StripeGateway implements PaymentGatewayInterface { ... }

class PayPalGateway implements PaymentGatewayInterface { ... }

Step 3: The Controller

namespace App\Http\Controllers;

use App\Contracts\Payment\PaymentGatewayInterface;

class CheckoutController extends Controller
{
    public function __construct(
        private readonly PaymentGatewayInterface $paymentGateway
    ) {}

    public function store(Request $request)
    {
        // The controller uses the interface.
        // It doesn't know if it's Stripe or PayPal.
        $result = $this->paymentGateway->charge(
            $request->only(['email', 'amount']),
            $request->amount
        );

        return response()->json($result);
    }
}

Step 4: Binding in a Service Provider

namespace App\Providers;

use App\Contracts\Payment\PaymentGatewayInterface;
use App\Services\Payment\StripeGateway;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Magic! We bind the interface to the concrete class.
        // Now, whenever a controller asks for PaymentGatewayInterface,
        // it gets StripeGateway.
        $this->app->bind(PaymentGatewayInterface::class, StripeGateway::class);
    }
}

Now, if the business wants to switch to PayPal for a specific country, you can use Contextual Binding in the service provider, or update a single line in the Service Provider. The Controller is clean and unbothered.

10. SOLID Principles Mapping

Dependency Injection is the enabler of SOLID.

D - Dependency Inversion Principle (DIP):
This is the big one. DI enforces DIP. High-level modules (CheckoutController) should not depend on low-level modules (StripeGateway). Both should depend on abstractions (PaymentGatewayInterface). DI is the mechanism that makes this physical separation possible.
O - Open/Closed Principle (OCP):
The CheckoutController is closed for modification (we don't touch it) but open for extension (we can add PayPalGateway and change the binding). The container makes this extension pluggable.
S - Single Responsibility Principle (SRP):
By injecting dependencies, we force classes to focus on their core job. The CheckoutController handles HTTP requests. The StripeGateway handles API calls. If we instantiated dependencies with new, the controller would be responsible for knowing the Stripe API key, which violates SRP.
L - Liskov Substitution Principle (LSP):
The container relies on this. Since StripeGateway and PayPalGateway implement the same interface, they are substitutable for each other. The controller (which uses the interface) will work correctly regardless of which one is passed in.

11. Trade-offs

Benefits

Flexibility: You can swap implementations by changing a single line in a Service Provider.
Testability: The ability to mock dependencies is the single greatest benefit to unit testing.
Decoupled Architecture: Changes to one part of the system are less likely to break another part.

Costs

Indirection: It is harder to follow the "flow" of code. You see a PaymentGatewayInterface and have to figure out which concrete class is bound to it.
Overhead: You create more files (interfaces, service providers, DTOs). For tiny, one-off scripts, this might be overkill.
Complexity: If you are using the Service Container heavily, you need to understand features like Contextual Binding, Tags, and Service Providers to debug effectively.

When is it justified?

You should use DI when you are building logic that is likely to change (e.g., business rules, external integrations) or when you need to unit test the class.

12. When NOT To Use It

3 Green Flags (USE IT)

External Services: You are integrating with an external API (e.g., Mailchimp, AWS S3).
Persistence Layer: You need to interact with a database or cache.
Business Logic: You have complex domain logic that requires extensive unit testing.

3 Red Flags (AVOID IT)

Data Transfer Objects (DTOs): A DTO usually holds simple, typed data (e.g., UserInput). It rarely needs dependencies. Autowiring a DTO is usually overkill.
Tiny Scripts: For a simple Artisan command that merely clears a cache, using a straight Cache::flush() (Facade) is much faster and easier than injecting a contract.
Controllers with Primitive Types: Sometimes a controller just needs a $request or a $userId. Laravel handles this, but don't create a service class just to inject an int.

13. Common Mistakes

1. Overengineering (The "Just in Case" Syndrome)

"I might need to switch from MySQL to Postgres, so I'll define an interface!"
While a valid concern, many developers prematurely abstract simple CRUD operations. Only create the abstraction when you actually have two implementations, or you specifically need it for mocking. YAGNI (You Ain't Gonna Need It) applies here.

2. Confusing Service Providers with Business Logic

Putting business logic inside boot() or register() methods of Service Providers.

// BAD: Service Provider doing business logic
public function boot() {
    $user = User::first(); // NO! This runs on every request!
}

Service Providers are only for registering services. boot() should only run registration logic (e.g., Route::macro, Gate::define).

3. Using the Container as a Service Locator

// The "Service Locator" Anti-Pattern
class OrderService {
    public function process(Order $order) {
        $payment = app(PaymentInterface::class); // BAD!
    }
}

You are calling app() inside the class. This hides the dependency. The class is no longer "self-documenting" via its constructor. Always use Constructor Injection.

4. Not Providing Default Values

If you don't bind an interface in the Service Provider, Laravel will try to instantiate the interface directly and fail with a binding error.
Always ensure your bindings exist in the register() method.

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is Dependency Injection? A: It is a design pattern where a class receives its dependencies from an external source rather than creating them internally.
Q: How does Laravel know what to inject when I type-hint an interface? A: Laravel uses the Service Container. You must define a binding in a Service Provider (usually AppServiceProvider) that tells the Container which concrete class to use for that interface.
Q: What is the difference between bind and singleton in the Service Container? A: bind creates a new instance every time it is resolved. singleton resolves the instance once and reuses that same instance for the rest of the request lifecycle.
Q: Is dependency injection the same as the Service Container? A: No. Dependency Injection is the pattern (how to structure code). The Service Container is the tool (a helper) that automates the injection process in Laravel.

Senior/Architect

Q: Explain the difference between Constructor Injection, Setter Injection, and Method Injection. Which is preferred and why? A: Constructor Injection (dependencies in __construct) is preferred because it ensures the object is in a valid state after instantiation. Setter Injection allows optional dependencies to be set later, but it can lead to "temporal coupling" (where the object is partially built). Method Injection passes dependencies directly into a specific method, useful for runtime variations (e.g., a payment method).
Q: How would you handle auto-resolving dependencies for dependencies that have primitive arguments (like a $apiKey)? A: You use Contextual Binding in a Service Provider ($this->app->when(Service::class)->needs('$apiKey')->give('value')) or use a Factory Pattern to build the object.
Q: How does Laravel's Container handle circular dependencies? A: By default, it will throw a LogicException (Circular dependency detected). The container cannot build a class that requires itself (e.g., A requires B, B requires A).
Q: What are the performance implications of using the Container heavily? A: Reflective resolution (auto-discovery) is slower than hardcoded new statements. However, Laravel caches the resolved bindings using php artisan optimize, which turns the resolution into an array lookup, mitigating most performance issues.

15. Interactive Practice Challenge

You are a developer on a team building a SaaS application. You have inherited the following code. It works, but it's fragile and impossible to test.

Your Task: Refactor this code to use Dependency Injection. Define the necessary interfaces, create implementation classes, and update the Service Provider.

The Requirement:
We need to send a welcome email when a user registers. The UserRegistrationService uses the SendGridEmail library directly. It also interacts with the User model directly using an Eloquent static call.

// BAD CODE
use App\Models\User;
use SendGrid\Mail\Mail;

class UserRegistrationService
{
    public function register(array $data): User
    {
        // Validates that email is unique
        if (User::where('email', $data['email'])->exists()) {
            throw new \Exception('User already exists');
        }

        // Creates the user
        $user = User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'password' => bcrypt($data['password']),
        ]);

        // Sends welcome email via SendGrid
        $email = new Mail();
        $email->setFrom("admin@example.com", "Admin");
        $email->setSubject("Welcome!");
        $email->addTo($user->email, $user->name);
        $email->addContent("text/html", "Hello {$user->name}");

        $sendgrid = new \SendGrid(getenv('SENDGRID_API_KEY'));
        $response = $sendgrid->send($email);

        if ($response->statusCode() !== 202) {
            \Log::error('Failed to send welcome email', ['user' => $user->id]);
        }

        return $user;
    }
}

Think about: How would you test this? How would you swap the email service for Mailgun? How would you mock the database check?

(We won't provide the solution here—put your Senior Engineer hat on and refactor it!)

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: Dependency Injection is the design principle where a class asks for what it needs (via its constructor) rather than looking for it itself.
One-sentence intuition: Stop building your tools inside the factory; bring the tools to the worker.
One-sentence decision rule: If a class has logic that is hard to test or likely to change, pull that logic out and inject it; otherwise, keep it simple.

17. Related Concepts

SOLID Principles: Dependency Injection is the practical implementation of the Dependency Inversion Principle (DIP). It works in tandem with Open/Closed to allow extension.
Design Patterns:
- Factory Pattern: Often used alongside DI. A Factory creates complex objects, while DI uses the Factory to provide the object.
- Strategy Pattern: DI is how you inject the specific Strategy into the Context.
- Observer Pattern: The Event system in Laravel uses the Container to resolve listeners.
Laravel Internals:
- Service Providers: The configuration layer where you register bindings.
- Facades: The "light switch" to the container.
- Eloquent Models: While Eloquent doesn't strictly rely on DI for its core, you can inject Repository interfaces into your controllers to abstract Eloquent's query builder.
Enterprise Patterns:
- Inversion of Control (IoC): DI is a subset of the IoC principle. The framework (Container) takes over the control of object lifecycle.

Github: Dependency Injection Practice Labs

Dependency Inversion Principle (DIP)

Anas Hussain — Wed, 08 Jul 2026 05:44:07 +0000

The Dependency Inversion Principle (DIP) is the final "D" in SOLID. It states two critical rules:

High-level modules should not depend on low-level modules. Both should depend on abstractions.
Abstractions should not depend on details. Details should depend on abstractions.

In simple terms: Your core business logic should not rely on specific tools or external technologies. Instead, both your logic and your tools should rely on a common blueprint (Interface).

The Real-World Example: Imagine you buy a brand-new smartphone

The Bad Design (Tight Coupling): Imagine if the phone manufacturer hardwired the charging cable directly inside your home's living room wall outlet. Your phone would charge perfectly in that one spot. But if you went to a coffee shop, or if you moved to a new house, your phone would be completely useless because it is tightly coupled to one specific wall.
The Good Design (Dependency Inversion): The smartphone manufacturer and the house architect agree on a common abstraction: the USB-C port.
The phone doesn't care if the power comes from a wall socket, a laptop port, an airplane seat, or a portable power bank.
It only depends on the shape of the USB-C contract. You can swap the power source instantly without modifying your phone.

❌ The Wrong Way: Depending directly on low-level tools (Violates DIP)

Here, the high-level NotificationManager depends directly on a specific low-level tool (MySQLDatabase).

class MySQLDatabase {
    public function saveLog($message) {
        echo "Saving log to MySQL database: $message\n";
    }
}

class NotificationManager {
    private $database;

    public function __construct() {
        // ❌ Tightly coupled! High-level class directly instantiates the low-level class.
        $this->database = new MySQLDatabase(); 
    }

    public function sendAlert($message) {
        // Sending alert logic...
        $this->database->saveLog($message);
    }
}

The Problem: If your company decides to switch from MySQL to MongoDB or Firebase next week, you are forced to open up and completely rewrite your NotificationManager class, risking bugs in your alert system.

✅The Right Way: Inverting the dependency (Adheres to DIP)

We introduce an interface (the USB-C port) between the high-level class and the low-level tool. Both now look up to the abstraction.

Step 1: Create the Abstraction (The Blueprint)

interface LoggerInterface {
    public function log(string $message): void;
}

Step 2: Make low-level tools adapt to the blueprint

class MySqlLogger implements LoggerInterface {
    public function log(string $message): void {
        echo "Saved to MySQL: $message\n";
    }
}

class MongoDbLogger implements LoggerInterface {
    public function log(string $message): void {
        echo "Saved to MongoDB: $message\n";
    }
}

Step 3: Inject the abstraction into the high-level class

The NotificationManager now only knows about the interface. It has no idea (and does not care) what database is being used behind the scenes.

class NotificationManager {
    // Rely completely on the Abstraction (Interface)
    public function __construct(
        private LoggerInterface $logger
    ) {}

    public function sendAlert($message) {
        // Sending alert logic...
        $this->logger->log($message);
    }
}

Why this helps you

Effortless Tech Swaps: You can change your database, payment gateway, or email provider by changing a single line of setup code, without touching your main business logic.
Flawless Testing: You can pass a fake "MockLogger" into the NotificationManager during automated testing so your tests run lightning fast without actually writing data to a real database.
Loose coupling: Reduces dependencies between modules, making the code more flexible and easier to test.
Flexibility: Enables changes to implementations without affecting clients.
Maintainability: Makes code easier to understand and modify.

The main reason 90% of engineers fail to use the Dependency Inversion Principle (DIP) is that they confuse it with Dependency Injection (DI).
They think that by passing a class into a constructor __construct($mysqlDatabase), they are applying DIP. They aren't. Passing a concrete, specific class into another class is just Dependency Injection. DIP requires an Interface (an abstraction) to step in and flip the ownership of the relationship.
Here is how to clear up the confusion and make definitive, master-level architectural decisions.

The 3 Main Confusions Cleared Up

1. Confusion: "Is Dependency Inversion the same thing as Dependency Injection?"

Reality: No. They are entirely different concepts that work together:
Dependency Injection (DI) is a technique for passing a tool into a class (e.g., passing a key into a lock instead of making the lock build its own key).
Dependency Inversion (DIP) is an architectural goal that states high-level policies should not depend on low-level details. You use DI to achieve DIP.

2. Confusion: "Does DIP mean every single new keyword in PHP is a sin?"

Reality: No. This confusion leads to massive over-engineering. You do not need interfaces for raw data objects, entities, or value objects (like new User(), new DateTime(), or new Collection()). You only apply DIP to Services and Infrastructure—classes that perform tasks or talk to external resources (like databases, APIs, file systems, and payment gateways).

3. Confusion: "Who actually owns the interface?"

Reality: In traditional programming, the low-level database or API team defines the structure, and the business logic has to match it. DIP completely inverts this. The high-level business logic defines what it needs, and the low-level database adapters must bend to fit that shape.

The Ultimate DIP Clean Code Check

You are violating DIP if you see your high-level controllers or business services look like this:

class OrderController {
    public function checkout() {
        // ❌ Direct concrete instantiation. 
        // This controller is trapped inside Stripe's ecosystem forever.
        $payment = new StripePaymentGateway(); 
        $payment->charge();
    }
}

The 3-Step Decision Matrix (How to Choose)

When deciding whether to create an abstraction line for a class in PHP, use this mental map:

START DIP_Design_Check

    IF Class_Talks_To_External_Resources_Outside_RAM IS True THEN

        IF Tool_Belongs_To_External_Vendor_Or_Package IS True THEN
            EXECUTE Apply_DIP_Wrap_In_Interface_Immediately

        ELSE
            IF Highly_Likely_To_Change_Tools IS True THEN
                EXECUTE Apply_DIP_Interface
            ELSE
                EXECUTE Direct_Type_Hint_Is_Fine
            END IF
        END IF

    ELSE
        IF Is_Core_Business_Entity IS True THEN
            EXECUTE Do_NOT_Use_DIP_Instantiate_Safely_With_New
        ELSE
            EXECUTE Leave_It_Alone
        END IF

    END IF

END DIP_Design_Check

The "Boundary" Rule: If a class crosses the boundary of your application to talk to the outside world (a payment provider, an SMS gateway, Amazon S3 storage), always apply DIP. Create an interface.
The "Volatile Dependency" Test: Ask yourself: "If this software package or vendor shuts down tomorrow, goes bankrupt, or triples their prices, how many files do I have to rewrite?" If the answer is more than one config or provider file, your system lacks Dependency Inversion.
The Mockability Factor: When writing unit tests, do you need to avoid hitting a live server (like preventing a real charge on a credit card)? If yes, you need an interface so you can swap the real service with a MockPaymentGateway during your test sweeps.

Summary for Decision Making

High-level modules (Controllers, Domain Use Cases, Business Logic) contain the identity and rules of your app.
Low-level modules (MySQL, Redis, AWS, Twilio, Stripe) are merely utility workers.

Refference
Wikepedia

The Laravel Blueprint: Mastering DIP (example)

Let's look at how a Junior developer tightly couples their code to a specific tool, and how a Laravel Master uses Contracts to execute Dependency Inversion.

❌ The Junior Approach (Violates DIP)

Imagine your Laravel application needs to upload user avatars to Amazon S3. A junior developer injects the concrete S3 client directly into a service.

namespace App\Services;

use Aws\S3\S3Client; // ❌ Tightly coupled to Amazon's official SDK!

class ProfileAvatarService
{
    protected $s3;

    public function __construct()
    {
        // ❌ The high-level service creates its own low-level tool.
        $this->s3 = new S3Client([
            'version' => 'latest',
            'region'  => 'us-east-1'
        ]);
    }

    public function updateAvatar($user, $file)
    {
        // Concrete Amazon-specific method execution
        $this->s3->putObject([
            'Bucket' => 'my-avatars',
            'Key'    => "avatars/{$user->id}.jpg",
            'Body'   => fopen($file, 'r')
        ]);
    }
}

Why this fails Laravel Mastery: Your app is trapped in AWS. If your company moves to Google Cloud Storage or DigitalOcean Spaces to save money, you have to find every file referencing S3Client, delete the code, and completely rewrite your upload logic.

The Laravel Mastery Approach (Adheres to DIP)

Laravel handles this using its native Storage Contracts (Illuminate\Contracts\Filesystem\Filesystem). Your high-level business code only talks to the contract. The infrastructure tools (S3, local disk, SFTP) are forced to adapt to what the contract demands.

Step 1: Depend entirely on the Abstraction

Your service doesn't know about Amazon, Google, or local hard drives. It only knows about the Laravel Filesystem contract.

namespace App\Services;

// We import the standard abstract Contract, NOT a concrete SDK package!
use Illuminate\Contracts\Filesystem\Filesystem;

class ProfileAvatarService
{
    // Laravel's Service Container automatically injects the active driver here
    public function __construct(
        protected Filesystem $storage
    ) {}

    public function updateAvatar($user, $file)
    {
        // The common "HDMI plug" method that works on ANY storage system
        $this->storage->put("avatars/{$user->id}.jpg", file_get_contents($file));
    }
}

Step 2: Swap the low-level details in .env

Because both your service and Laravel's drivers depend on the same underlying abstraction, you don't need to change a single line of PHP code to swap out the technology. You just update your configuration or your environment file:

# Switch from Amazon S3 to Local Storage instantly without breaking the app:
FILESYSTEM_DISK=s3
# FILESYSTEM_DISK=local
# FILESYSTEM_DISK=gcs

Step 3: How Laravel wires it up under the hood

If you ever build a custom storage solution (like a custom database-driven file system), you register it in a Service Provider using the Service Container:

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Illuminate\Contracts\Filesystem\Filesystem;
use App\Services\CustomDatabaseStorageDriver;

class StorageServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Tell Laravel: Whenever a class asks for the Filesystem Contract,
        // hand them our custom driver implementation.
        $this->app->bind(Filesystem::class, function ($app) {
            return new CustomDatabaseStorageDriver();
        });
    }
}

Why this makes you a Laravel Master

Seamless Testing: When writing a feature test for uploading an avatar, you can call Storage::fake('avatars'). Laravel instantly swaps the real storage engine with an in-memory virtual disk. Your tests execute instantly, and you never accidentally upload junk test images to a live Amazon S3 account.
Plugin Architecture: Your application becomes modular. You can change your cache systems, database engines, mail dispatchers, and queue runners on the fly because your controllers and services only interact with framework contracts.

Interface Segregation Principle (ISP)

Anas Hussain — Mon, 06 Jul 2026 07:56:11 +0000

The interface segregation principle (ISP) states that no code should be forced to depend on methods it does not use. ISP splits interfaces that are very large into smaller and more specific ones so that clients will only have to know about the methods that are of interest to them. Such shrunken interfaces are also called role interfaces. ISP is intended to keep a system decoupled and thus easier to refactor, change, and redeploy.

In simple terms: Keep your interfaces small, specific, and focused. It is much better to have many tiny, specialized interfaces instead of one giant "fat" interface that forces classes to write useless code.

Importance in object-oriented design: Within object-oriented design, interfaces provide layers of abstraction that simplify code and create a barrier preventing coupling to dependencies. A system may become so coupled at multiple levels that it is no longer possible to make a change in one place without necessitating many additional changes. Using an interface or an abstract class can prevent this side effect.

The Real-World Example: Imagine you want to sign up for a local fitness center.

The Giant Interface (Violates ISP): The gym only offers a single "$500/month Ultimate Platinum VIP Pass." This pass includes access to the weight room, the swimming pool, the golf simulator, the childcare center, and the juice bar.
The Problem: You just want to lift weights for 30 minutes. However, you are forced to pay for, carry a card for, and sign waivers for the swimming pool and childcare center, even though you don't swim and don't have kids.
The Segregated Interface (Adheres to ISP): The gym splits its services. You buy a "Weight Room Only Pass." Parents buy a "Childcare Pass." Swimmers buy a "Pool Pass." You only interact with, pay for, and use exactly what you need.

❌ The Wrong Way: The "Fat" Interface (Violates ISP)

Imagine an interface for handling corporate office employees.

interface Employee {
    public function codeSoftware();
    public function manageTeam();
    public function cleanBuilding();
}

If you try to create a Developer class using this interface, you run into a major problem. Developers don't clean buildings or manage teams. You are forced to write useless filler code just to satisfy the PHP compiler.

class Developer implements Employee {
    public function codeSoftware() {
        echo "Writing clean code...\n";
    }

    // ❌ Violates ISP! Forced to implement a method they don't use
    public function manageTeam() {
        return null; 
    }

    // ❌ Violates ISP! Forced to write useless code
    public function cleanBuilding() {
        throw new Exception("I am a programmer, not a janitor!");
    }
}

✅The Right Way: Small, Focused Interfaces (Adheres to ISP)

To fix this, break the giant Employee interface into tiny, atomic pieces based on actual actions.

interface Codeable {
    public function codeSoftware();
}

interface Manageable {
    public function manageTeam();
}

interface Cleanable {
    public function cleanBuilding();
}

Now, your PHP classes can cleanly pick and choose exactly which contracts apply to them. No wasted code, no dummy methods, and no fake exceptions.

// The Developer class only cares about coding
class Developer implements Codeable {
    public function codeSoftware() {
        echo "Writing clean code...\n";
    }
}

// A Tech Lead class can do both coding and managing
class TechLead implements Codeable, Manageable {
    public function codeSoftware() { echo "Writing code...\n"; }
    public function manageTeam() { echo "Leading the standup meeting...\n"; }
}

// The Janitor class only cares about cleaning
class Janitor implements Cleanable {
    public function cleanBuilding() {
        echo "Mopping the floors...\n";
    }
}

Why this helps you

Decoupling: Reduces dependencies between classes, making the code more modular and maintainable.
Flexibility: Allows for more targeted implementations of interfaces.
Avoids unnecessary dependencies: Clients don't have to depend on methods they don't use.

The main reason 90% of engineers fail to use the Interface Segregation Principle (ISP) is that they confuse a functional code structure with a business role structure. They create interfaces based on nouns (like interface User or interface Order) instead of behaviors (like CanBeSaved or CanBeEmailed).
This creates massive, bloated contracts that force developers to write empty, useless methods just to satisfy the PHP compiler. Here is how to clear up the confusion and make effortless, high-utility design decisions.

The 3 Main Confusions Cleared Up

1. Confusion: "Does ISP mean I can only have one method per interface?"

Reality: No. An interface can have multiple methods, as long as every single class that implements it needs every single method.
Example: A Cacheable interface might need both get($key) and set($key, $value). They belong together because you cannot practically use a cache that only lets you read but never write.

2. Confusion: "If I have 50 small interfaces, won't my codebase become a mess?"

Reality: It actually makes your codebase much cleaner. In PHP, a single class can implement an unlimited number of interfaces (class User implements Authenticatable, Sluggable, Billable). This is highly flexible, modular, and self-documenting.

3. Confusion: "Can't I just use PHP Traits instead of splitting interfaces?"

Reality: Traits share implementation code (how things work), while interfaces define architectural architectural contracts (what things do). Traits do not solve type-hinting issues. If a controller expects a giant, bloated interface, a Trait won't prevent a developer from calling a method that shouldn't be there.

The Ultimate ISP Smell Test

You are violating ISP if you look at a PHP class and find yourself doing this:

class GuestUser implements FullUserInterface {
    public function getPassword() {
        // ❌ ISP Violation Smell! 
        // Guest users don't have passwords, but the interface forces me to write this.
        return null; 
    }
}

If you ever write return null;, return false;, or throw new Exception("Not implemented"); inside a method required by an interface, your interface is too fat.

The 3-Step Decision Matrix (How to Choose)

When defining a new contract or refactoring an existing one in PHP, use this mental map to ensure ISP compliance:

START ISP_Design_Check

    IF Interface_Named_After_Noun IS True THEN
        EXECUTE Stop_Shift_Focus_To_Verbs_Or_Actions

    ELSE
        IF Every_Implementing_Class_Uses_All_Methods IS True THEN
            EXECUTE Leave_It_Alone_ISP_Compliant
        ELSE
            EXECUTE Split_Interface_Into_Smaller_Pieces
        END IF

    END IF

END ISP_Design_Check

The "Role vs. Header" Rule: Do not bundle administrative methods with operational methods. For instance, do not put a deleteAccount() method into the same interface that handles basic public user profile viewing.
The "-able" Naming Trick: When creating interfaces, try naming them with adjectives ending in "-able" or "-or" (e.g., Loggable, Renderable, Exportable, SmsSender). This naturally forces you to focus on a single, specific behavior rather than a massive corporate role.
Refactor with Interface Inheritance: If you legitimately need a large interface for a complex class, you can still respect ISP by composing it out of smaller interfaces using inheritance:

interface SimpleReader { public function read(); }
interface SimpleWriter { public function write(); }

// Advanced classes can implement this, while simple classes can just use Reader or Writer
interface AdvancedStorage extends SimpleReader, SimpleWriter { 
    public function clearCache(); 
}

Summary for Decision Making

Interfaces should be designed from the perspective of the client class that calls them, not the concrete class that implements them. If a client only needs to read data, give it an interface that only allows reading.

The Laravel Blueprint: Mastering ISP

Let's look at a common mistake when building a standard E-commerce checkout or inventory system in Laravel, and how to solve it like a framework architect.

❌ The Junior Approach (Violates ISP)

A junior developer creates a single, monolithic interface to handle all types of products in the store's inventory. [7]

namespace App\Contracts;

interface ProductContract
{
    public function getPrice(): int;
    public function getWeight(): float;
    public function getShippingDimensions(): array;
}

This interface works perfectly for a physical product like a Laptop. But look what happens when the developer tries to implement it for a Digital E-Book or a Software License:

namespace App\Services;

use App\Contracts\ProductContract;

class EBookProduct implements ProductContract
{
    public function getPrice(): int {
        return 999; // ₹999
    }

    // ❌ ISP VIOLATION! E-books do not have physical weight.
    public function getWeight(): float {
        return 0.0; // Useless filler value to satisfy PHP compiler
    }

    // ❌ ISP VIOLATION! E-books do not ship in boxes.
    public function getShippingDimensions(): array {
        throw new \Exception("Digital products do not have shipping dimensions!");
    }
}

The Problem: Your OrderShippingService iterates over all cart items. If it accidentally calls getShippingDimensions() on an EBookProduct, your entire checkout crashes. The interface forced a digital class to inherit physical real-world problems.

The Laravel Mastery Approach (Adheres to ISP)

To build this like the creators of Laravel, we split the behaviors into small, highly specialized contracts.

Step 1: Segregate the Contracts [8]

namespace App\Contracts;

interface Sellable 
{
    public function getPrice(): int;
}

interface Shippable
{
    public function getWeight(): float;
    public function getShippingDimensions(): array;
}

Step 2: Implement only what is required

Now, our classes cleanly bind themselves to exactly what they are capable of doing.

namespace App\Models;

use App\Contracts\Sellable;
use App\Contracts\Shippable;
use Illuminate\Database\Eloquent\Model;

// Physical products implement both contracts
class Laptop extends Model implements Sellable, Shippable
{
    public function getPrice(): int { return 6500000; }
    public function getWeight(): float { return 2.1; }
    public function getShippingDimensions(): array { return; }
}

// Digital products ONLY implement Sellable
class EBook extends Model implements Sellable
{
    public function getPrice(): int { return 999; }
    // No useless weight or dimension code written here!
}

Step 3: Type-Hint accurately in your Services

Your delivery and shipping managers inside Laravel now type-hint the specific behavioral contract, completely isolating them from digital items.

namespace App\Services;

use App\Contracts\Shippable;

class LogisticsService
{
    // This method strictly accepts items that CAN actually be shipped
    public function calculateShippingCost(Shippable $product)
    {
        $weight = $product->getWeight();
        $dimensions = $product->getShippingDimensions();

        // Calculate carrier rates safely...
    }
}

Laravel's Native Mastery Example: Responsable

Laravel natively uses this exact concept with its Illuminate\Contracts\Support\Responsable interface.
Instead of forcing every controller action or custom object to implement a massive layout matrix, Laravel says: "If your class implements Responsable, it must contain exactly one method: toResponse($request)." When a controller returns that object, Laravel checks if it implements that specific interface and executes it automatically.

Summary for Laravel Developers

When creating custom classes, plugins, or traits in Laravel, ask yourself: "Is any class implementing this contract forced to write dummy return values or throw 'Not Supported' exceptions?"
If the answer is yes, break that contract up into smaller pieces immediately.

Liskov Substitution Principle (LSP)

Anas Hussain — Sat, 04 Jul 2026 04:04:34 +0000

The Liskov substitution principle (LSP) states: Objects of a superclass should be replaceable with objects of its subclasses without breaking the application.

In simple terms: A child class must behave exactly like its parent class, so it doesn't surprise the system. If your code expects a generic parent type, you should be able to pass any child variant into it without causing errors, crashes, or weird behaviors.

Keep in mind: Model your classes based on behaviours not on properties. Model your data based on properties and not on behaviours.

The Real-World Example: Think of a TV remote control that runs on standard AA batteries

The Expectation (Parent): The remote expects a standard AA battery. It assumes the battery will fit the slot, provide 1.5 volts of power, and have a positive and negative terminal.
Good Substitution (LSP Compliant): You run out of Duracell batteries, so you buy a Energizer battery or a cheap store-brand battery. They look a bit different, but they provide exactly 1.5V and fit the slot. The remote still works perfectly.
Bad Substitution (LSP Violation): Imagine a company creates a "Smart AA Battery" that is the exact same physical size, but instead of outputting 1.5V continuously, it requires a smartphone app connection to turn on, or it outputs 12V. If you put it in the remote, it either won't power up or it will fry the remote's circuits.

Even though it is technically an "AA Battery" by shape, it violates the expected behavior of an AA battery.

❌ The Wrong Way: Subclasses that break promises (Violates LSP)

A famous technical example is the Square and Rectangle dilemma. A square is technically a rectangle in geometry, but trying to force it into inheritance breaks code logic.

class Rectangle {
    protected $width;
    protected $height;

    public function setWidth($width) { $this->width = $width; }
    public function setHeight($height) { $this->height = $height; }
    public function getArea() { return $this->width * $this->height; }
}

// Square forces both sides to be equal, changing the fundamental rules
class Square extends Rectangle {
    public function setWidth($width) {
        $this->width = $width;
        $this->height = $width; // Modifies height unexpectedly!
    }
    public function setHeight($height) {
        $this->width = $height; // Modifies width unexpectedly!
        $this->height = $height;
    }
}

Why this breaks the system:
If a developer writes a function expecting a standard Rectangle, they assume changing the width won't touch the height.

function render(Rectangle $rectangle) {
    $rectangle->setWidth(10);
    $rectangle->setHeight(5);

    // If you pass a Rectangle: 10 * 5 = 50 (Correct)
    // If you pass a Square: 5 * 5 = 25 (❌ Broken! The width got silently overwritten)
    echo $rectangle->getArea(); 
}

✅The Right Way: Proper Abstraction (Adheres to LSP)

To fix this, child classes should never change the rules of the parent. If they behave differently, they shouldn't share the same direct inheritance line for those specific properties.

interface Shape {
    public function getArea(): float;
}

class Rectangle implements Shape {
    public function __construct(protected float $width, protected float $height) {}
    public function getArea(): float { return $this->width * $this->height; }
}

class Square implements Shape {
    public function __construct(protected float $side) {}
    public function getArea(): float { return $this->side * $this->side; }
}

Now, you can substitute Rectangle or Square anywhere a Shape is expected, and the getArea() method will always return the correct result without any unexpected side effects.

Why this helps you

Polymorphism: Enables the use of polymorphic behavior, making code more flexible and reusable.
Reliability: Ensures that subclasses adhere to the contract defined by the superclass.
Predictability: Guarantees that replacing a superclass object with a subclass object won't break the program.

The Golden Rules to avoid breaking LSP

Don't throw unexpected exceptions: If the parent method doesn't throw errors, your child method shouldn't throw a MethodNotImplementedException.
Don't weaken preconditions: A child class cannot demand more strict inputs than the parent class.
Don't strengthen postconditions: A child class must return the same type of output data expected by the parent.

The 3 Main Confusions Cleared Up

1. Confusion: "If Class B passes the instanceof check for Class A, isn't it LSP compliant?"

Reality: No. Your PHP compiler only checks syntax, not behavior. If your parent class returns an array, and your child class returns null or throws a NotImplementedException, it passes PHP's syntax checks but completely destroys LSP at runtime.

2. Confusion: "Does LSP mean child classes cannot add new methods?"

Reality: Child classes can add as many new methods as they want. LSP only cares about the inherited methods. The child must not break the existing promises made by the parent methods.

3. Confusion: "Real-world relationships map directly to code inheritance, right?"

Reality: This is the biggest trap in programming. In the real world, an Ostrich is a Bird. But in code, if your Bird class has a fly() method, making Ostrich extends Bird will force you to break LSP because ostriches cannot fly. Code relationships are based on what objects can DO, not what they ARE.

The Ultimate LSP Cheat Sheet (The 3 Violations)

You are violating LSP if your child class does any of these three things:

The Violation	What it looks like in PHP	Why it breaks the app
1. The Slacker	Throws a NotImplementedException or returns false for an inherited method.	Code expecting the parent class will crash unexpectedly.
2. The Secret Agent	Requires a completely different, stricter type of input than the parent.	Code passing valid inputs to the parent will fail on the child.
3. The Traitor	Changes or strips out the data type that the parent promised to return.	Code trying to read the result will trigger an error.

The 3-Step Decision Matrix (How to Choose)

When writing a subclass or implementing an interface in PHP, use this mental map to ensure LSP compliance:

START LSP_Design_Check

    IF Child_Disables_Or_Throws_Error_For_Inherited_Method IS True THEN
        EXECUTE Stop_Do_Not_Use_Inheritance_Use_Composition_Instead

    ELSE
        IF Child_Changes_Expected_Type_Of_Inputs_Or_Outputs IS True THEN
            EXECUTE Fix_Your_Types_To_Match_The_Parent_Exactly
        ELSE
            EXECUTE Leave_It_Alone_LSP_Compliant
        END IF

    END IF

END LSP_Design_Check

The "Throw-Away" Test: Am I about to write a method in my child class that just says throw new Exception("Not supported")? If yes, do not extend that parent.
The "If Instanceof" Smell: Look at your controller code. Do you ever see blocks like this?

if ($payment instanceof CryptoPayment) {
    $payment->connectWallet(); // ❌ LSP Smell!
}
$payment->process();

If you have to explicitly check which child class you are holding to execute unique logic, your abstraction is broken. Move that unique logic inside the process() method itself.

Composition Over Inheritance: If you want Class B to reuse code from Class A, but Class B doesn't share the exact same behaviors, do not use extends. Instead, pass Class A into Class B's constructor (Composition) or use a PHP trait.

Summary for Decision Making

If your code handles a parent class, it should never care, know, or suspect if it is actually holding a child class. The swap should be completely invisible.

The Laravel Blueprint: Mastering LSP

Let's look at how a Junior developer violates LSP in Laravel versus how a Master architectures it using Laravel's Cache system.

❌ The Junior Approach (Violates LSP)

Imagine your app uses Redis for fast caching, but for local development, you use simple File caching. A junior developer creates a custom wrapper but changes the behavioral rules of the output.

namespace App\Services;

use Illuminate\Support\Facades\Cache;

class CustomCacheService
{
    public function getUserData(string $key)
    {
        $data = Cache::get($key);

        // ❌ LSP VIOLATION SMELL!
        // Redis returns an Object, but File cache returns a raw String.
        // The developer has to write conditional logic depending on the driver!
        if (config('cache.default') === 'redis') {
            return json_decode($data);
        }

        return $data; 
    }
}

Why this breaks Laravel Mastery: The application code now cares about which driver is running behind the scenes. If you switch drivers in your .env file, your code logic breaks.

The Laravel Mastery Approach (Adheres to OCP & LSP)

Laravel provides the Illuminate\Contracts\Cache\Repository contract. Any cache driver Laravel uses (Redis, Memcached, Database, File) must strictly adhere to the behavior defined by this contract.
No matter which driver is swapped in via the Service Container, it must return exactly what is expected without requiring if/else checks in your Controller.

Step 1: Trusting the Contract in your Controller

Your controller type-hints the Laravel Contract. It does not care if the data is coming from a hard drive or an in-memory Redis cluster.

namespace App\Http\Controllers;

use Illuminate\Contracts\Cache\Repository as CacheContract;
use App\Models\User;

class UserController extends Controller
{
    // Laravel automatically injects whatever driver is active in config/cache.php
    public function __construct(
        protected CacheContract $cache
    ) {}

    public function show($id)
    {
        // LSP Guarantee: Every single Laravel cache driver MUST return 
        // the item if found, or NULL if it doesn't exist. 
        // No driver is allowed to throw a "FileNotFoundException".
        $user = $this->cache->remember("user:{$id}", 3600, function () use ($id) {
            return User::findOrFail($id);
        });

        return response()->json($user);
    }
}

Step 2: Creating a Custom Driver Safely (Abiding by LSP)

If your company builds a custom internal caching system (e.g., Couchbase) and you want to integrate it into Laravel, your custom driver must follow the rules of the parent Repository contract.

namespace App\Extensions;

use Illuminate\Contracts\Cache\Repository;

class CouchbaseCacheDriver implements Repository
{
    // You MUST implement all methods, and they MUST behave identical to Redis/File
    public function get($key, $default = null)
    {
        $value = $this->couchbase->find($key);

        // LSP Rule: If missing, return the default value (null), 
        // do not throw an error or return false!
        return $value ?? $default; 
    }

    // ... implement other required contract methods
}

Summary for Laravel Developers

When writing extensions, packages, or custom drivers in Laravel, ask yourself: "If I swap this implementation in my .env or Service Provider, will I have to change a single line of code inside my Controllers or Jobs?"
If the answer is yes, your child class has broken the behavioral promises of the parent contract, violating LSP.

Open Closed Principle (OCP)

Anas Hussain — Thu, 02 Jul 2026 08:16:07 +0000

The open-closed principle (OCP) states that software entities should be open for extension, but closed for modification; that is, such an entity can allow its behaviour to be extended without modifying its source code.

In simple terms: You should be able to add new features to your code without changing or breaking the existing code.

Importance:

Extensibility: New features can be added without modifying existing code.
Stability: Reduces the risk of introducing bugs when making changes.

- Flexibility: Adapts to changing requirements more easily.

The Real-World Example: Think of the electrical wall outlet in your home.

Closed for Modification: The outlet is wired permanently behind your drywall. You do not tear down the wall, change the house wiring, or rebuild the electrical grid every time you buy a new device.
Open for Extension: The outlet provides a standard interface (the plug holes). You can plug in a phone charger, a vacuum cleaner, a toaster, or a television.

The outlet does not need to know what appliance you are plugging into it ahead of time. It is open to powering any device, as long as that device fits the standard plug shape.

Imagine you run an online store, and you need to calculate shipping costs for different shipping methods.

❌ The Wrong Way: Modifying the existing class (Violates OCP)

Every time your company decides to offer a new shipping carrier (like DHL or FedEx), you have to open this existing file and add another if/else block.

class ShippingCostCalculator {
    public function calculate($weight, $carrier) {
        if ($carrier === 'FedEx') {
            return $weight * 1.5;
        } elseif ($carrier === 'UPS') {
            return $weight * 1.2;
        }
        // ❌ If you want to add DHL tomorrow, you must modify this file.
        // If you make a typo, you break FedEx and UPS shipping for everyone.
    }
}

✅The Right Way: Extending without modifying (Adheres to OCP)

Instead of one giant class making all the decisions, we create a standard contract (Interface). The main calculator stays closed to modification, but the system is open to extension by simply adding new files.

Step 1: Create the standard "Outlet" (Interface)

interface ShippingRate {
    public function getRate(float $weight): float;
}

Step 2: Create the "Appliances" (Plugging in new features)

To add a new carrier, you just create a completely separate, isolated class file.

class FedExShipping implements ShippingRate {
    public function getRate(float $weight): float {
        return $weight * 1.5;
    }
}

class UpsShipping implements ShippingRate {
    public function getRate(float $weight): float {
        return $weight * 1.2;
    }
}

// Want to add DHL? Just create a new file! No need to touch FedEx or UPS.
class DhlShipping implements ShippingRate {
    public function getRate(float $weight): float {
        return $weight * 2.0;
    }
}

Step 3: Run the system safely

The core logic never changes, no matter how many carriers you add to your company.

class ShippingCostCalculator {
    // This method is CLOSED to modification. It doesn't care about specific brands.
    public function calculate(float $weight, ShippingRate $shippingMethod) {
        return $shippingMethod->getRate($weight);
    }
}

Why this helps you

Extensibility: New features can be added without modifying existing code.
Stability: Reduces the risk of introducing bugs when making changes.
Flexibility: Adapts to changing requirements more easily.
Team Collaboration: Ten different developers can work on ten different shipping methods at the same time without editing the same file and causing code conflicts.

The 3 Main Confusions Cleared Up

1. Confusion: "Closed for modification means I can never touch this file again?"

Reality: No. "Closed" means closed for behavioral changes to existing features, or changes driven by new requirements. If you find a bug in the class, you absolutely must open and modify the file to fix it.

2. Confusion: "Should I create an Interface for every single class?"

Reality: This is the #1 mistake that kills performance and readability. If a class has exactly one implementation that will never change (e.g., a PdfGenerator that only generates PDFs), do not create an interface. Only use interfaces where variance is expected.

3. Confusion: "Does OCP mean I must predict the future?"

Reality: You cannot guess every feature your client will ask for in two years. OCP does not mean predicting the future; it means structuring code so that when the future happens, it is easy to plug in.

The Anti-Pattern vs. The OCP Solution

❌ The 90% Approach: Modifying the existing class (Violates OCP)

Every time a manager asks for a new payment gateway, the engineer opens this class and adds another elseif. One typo can crash the entire checkout system.

class PaymentProcessor {
    public function process($amount, $type) {
        if ($type === 'paypal') {
            // PayPal logic
        } elseif ($type === 'stripe') {
            // Stripe logic
        } elseif ($type === 'crypto') { // ❌ Had to modify this file to add this!
            // Crypto logic
        }
    }
}

The 10% Approach: Using Polymorphism (Adheres to OCP)

We create a contract (Interface). The main processor never changes, no matter how many gateways you add.

interface PaymentGateway {
    public function pay($amount);
}

// The core logic is now CLOSED to modification
class PaymentProcessor {
    public function process($amount, PaymentGateway $gateway) {
        $gateway->pay($amount); // Dynamic execution
    }
}

// OPEN to extension: Just add a new class file!
class StripeGateway implements PaymentGateway {
    public function pay($amount) { /* Stripe logic */ }
}
class CryptoGateway implements PaymentGateway {
    public function pay($amount) { /* Crypto logic */ }
}

The 3-Step Decision Matrix (How to Choose)

When writing or reviewing a PHP class, use this mental map to decide if you need to apply OCP:

  START OCP_Design_Check

    IF Is_Writing_Conditional_Statement IS True THEN

        IF Conditions_Likely_To_Grow_In_Future IS True THEN
            EXECUTE Apply_OCP_Use_An_Interface
        ELSE
            EXECUTE Simple_If_Else_Is_Fine
        END IF

    ELSE
        EXECUTE Leave_It_Alone
    END IF

END OCP_Design_Check

Is it a variation of a type? If you are writing conditions based on "types" (e.g., user_type, payment_method, report_format, export_destination), it is a prime candidate for OCP. Turn those types into separate classes implementing an interface.
Is it a simple binary state? If you are checking if ($user->isActive), leave it alone. Do not create an ActiveUser and InactiveUser class. That is over-engineering.
The "Three Strikes" Rule: If you don't know if a feature will expand, don't guess. Write the simple if/else first. The second time you modify it, let it go. The third time you have to open that file to add another condition, refactor it to OCP immediately.

Summary for Decision Making

Modify code only to fix bugs or optimize existing logic.
Extend code (by adding new files/classes) to add completely new business rules or features.

The Laravel Blueprint: Mastering OCP

In Laravel, the "wall outlet" is an Interface (often called a Contract), and the "appliances" are your classes. Imagine your Laravel app needs to send marketing alerts to users. Initially, your boss asks for SMS alerts via Twilio.

❌ The Junior Approach (Violates OCP)

A junior developer hardcodes Twilio directly into the service.

namespace App\Services;

use Twilio\Rest\Client;

class OrderNotificationService 
{
    public function sendAlert($user, $message) 
    {
        // Hardcoded dependency on Twilio
        $twilio = new Client(config('twilio.sid'), config('twilio.token'));
        $twilio->messages->create($user->phone, ['body' => $message]);
    }
}

The Problem: Two months later, the boss says, "Twilio is too expensive, let's switch to Vonage for SMS, and also add WhatsApp alerts!" You now have to open this class, delete code, and rewrite it. This risks breaking your existing deployment.

The Laravel Mastery Approach (Adheres to OCP)

To write this like a Laravel senior architect, you use a Contract and Laravel's Service Container.

Step 1: Create the "Outlet" (The Contract)

namespace App\Contracts;

interface SmsSender 
{
    public function send(string $to, string $message): bool;
}

Step 2: Create the "Appliances" (The Providers)

Now, create separate classes for each service. If you need to add a new one later, you just create a new file.

namespace App\Services;

use App\Contracts\SmsSender;

class TwilioSender implements SmsSender 
{
    public function send(string $to, string $message): bool {
        // Twilio specific API code here
        return true;
    }
}

class VonageSender implements SmsSender 
{
    public function send(string $to, string $message): bool {
        // Vonage specific API code here
        return true;
    }
}

Step 3: Inject the Contract into your Service

Your service is now closed for modification. It only knows about the interface, not the concrete brands.

namespace App\Services;

use App\Contracts\SmsSender;

class OrderNotificationService 
{
    // Laravel automatically injects the correct sender here!
    public function __construct(
        protected SmsSender $smsSender
    ) {}

    public function sendAlert($user, $message) 
    {
        $this->smsSender->send($user->phone, $message);
    }
}

Step 4: The Magic Switch (AppServiceProvider)

How does Laravel know which appliance is plugged into the outlet? You tell it in your AppServiceProvider.php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use App\Contracts\SmsSender;
use App\Services\TwilioSender;
use App\Services\VonageSender;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // To switch from Twilio to Vonage globally, change exactly ONE line here:
        $this->app->bind(SmsSender::class, TwilioSender::class);
    }
}

Why this makes you a Laravel Master

Zero-Risk Feature Additions: When the boss wants to add WhatsApp tomorrow, you don't touch OrderNotificationService. You just write a WhatsAppSender file and swap it in the Service Provider.
Mocking & Testing: In your feature tests, you can swap the implementation with a fake one (SmsSender::fake()) so you don't accidentally send real text messages during testing.

Single Responsibility Principle (SRP)

Anas Hussain — Tue, 30 Jun 2026 04:32:00 +0000

The single-responsibility principle (SRP) states that there should never be more than one reason for a class to change. In other words, every class should have only one responsibility. A module should be responsible to one, and only one, actor. The term actor refers to a group (consisting of one or more stakeholders or users) that requires a change in the module.

In simple terms: Do one thing, and do it well.

The Real-World Example: Imagine you are hiring a chef for a restaurant.

Bad Design (The "Do-Everything" Chef): You hire a chef who must cook the food, wash the dishes, calculate the restaurant's taxes, and repair the plumbing when a pipe bursts.
The Problem: If the tax laws change, your chef is busy studying accounting instead of cooking. If they mess up the plumbing, the kitchen floods, and the entire restaurant shuts down. One change ruins everything.
Good Design (SRP applied): You hire a chef to cook, a dishwasher to clean, an accountant for taxes, and a plumber for repairs.
The Benefit: If tax laws change, only the accountant changes their workflow. The chef keeps cooking without interruption.

❌ Wrong Approach: A class with too many jobs

This User class handles user data, database connections, and email delivery. It has three reasons to change.

class User {
    private $name;
    private $email;

    public function __construct($name, $email) {
        $this->name = $name;
        $this->email = $email;
    }

    // Job 1: Manage User Data
    public function getName() { return $this->name; }

    // Job 2: Database Operations (Reason to change: Switching database types)
    public function saveToDatabase() {
        echo "Saving user to database...\n";
    }

    // Job 3: Notification Logic (Reason to change: Switching from Email to SMS)
    public function sendWelcomeEmail() {
        echo "Sending email to " . $this->email . "\n";
    }
}

✅ Right Approach: Splitting responsibilities

We break the big class into three tiny, specialized classes. Each has exactly one job.

// 1. Responsible ONLY for user data representation
class User {
    private $name;
    private $email;

    public function __construct($name, $email) {
        $this->name = $name;
        $this->email = $email;
    }

    public function getName() { return $this->name; }
    public function getEmail() { return $this->email; }
}

// 2. Responsible ONLY for saving data
class UserRepository {
    public function save(User $user) {
        echo "Saving " . $user->getName() . " to the database.\n";
    }
}

// 3. Responsible ONLY for sending messages
class EmailService {
    public function sendWelcome(User $user) {
        echo "Sending email to " . $user->getEmail() . "\n";
    }
}

Why this helps you

Maintainability: When classes have a single, well-defined responsibility, they're easier to understand and modify.
Testability: It's easier to write unit tests for classes with a single focus.
Flexibility: Changes to one responsibility don't affect unrelated parts of the system.
Reusability: You can use the EmailService to send emails for orders, resets, or other features.

The 3 Main Confusions Cleared Up for the SRP implementation

1. Confusion: "Does 'one responsibility' mean a class can only have one method?"

Reality: No. A responsibility is a cohesive business role, not a single action.
Example: A UserRepository class can have save(), delete(), findById(), and update(). This is still one responsibility: managing user data storage.

2. Confusion: "What exactly defines a 'reason to change'?"

Reality: Robert C. Martin (the creator of SOLID) clarified that a "reason to change" refers to people, not technology. A responsibility is defined by who requests the change (the actors).
Example: If the Accounting department asks for a change, and the HR department asks for a change, those are two different actors. They should never share the same PHP class.

3. Confusion: "When do I stop splitting classes?"

Reality: Engineers often split code prematurely, creating UserEmailValidator, UserPasswordValidator, and UserAgeValidator before they even need them. This causes "analysis paralysis."

The 3-Step Decision Matrix (How to Choose)

When looking at a PHP class, ask yourself these three strict questions to decide if you need to split it:

Is this class serving more than one business department/actor?

START SRP_Decision_Process

    IF Class_Serves_Multiple_Departments_Or_Actors IS True THEN
        EXECUTE Split_Class_Immediately

    ELSE
        IF Class_Mixes_Different_Technical_Layers IS True THEN
            EXECUTE Split_Class
        ELSE
            EXECUTE Leave_It_Alone
        END IF

    END IF

END SRP_Decision_Process

Who is asking for this feature? If a bug fix for the marketing team's email layout can accidentally break the accounting team's invoice calculation, your class has too many responsibilities.
Are different technical layers mixed? If a single PHP class contains raw SQL queries (SELECT *), HTML markup (<div>), and validation logic (if (empty)), it violates SRP. Split them.
Can I describe the class without using the word "AND"?
- Bad: "This class holds user data and saves it to MySQL and sends a Slack alert." (3 responsibilities)
- Good: "This class sends Slack alerts." (1 responsibility)

Real-World Decision Rule: "Don't Split Until It Hurts"

To avoid over-engineering, follow the Tactical SRP Rule:

Start by writing your code in a single class if the feature is small.
The moment you need to reuse a piece of it (like using the email logic somewhere else), extract it into its own class.
The moment a class grows past 200 lines of code, audit it using the decision matrix above.

The Laravel Blueprint: Mastering SRP

Let's look at a classic Laravel mistake: putting user registration logic, database insertion, profile photo manipulation, and welcome notifications all inside a single Controller method.

❌ The Junior Approach: The "Do-Everything" Controller (Violates SRP)

This controller method has four distinct reasons to change: database changes, validation rules, image optimization tweaks, and notification carrier changes.

namespace App\Http\Controllers;

use App\Models\User;
use Illuminate\Http\Request;
use Intervention\Image\Facades\Image;
use Illuminate\Support\Facades\Mail;

class RegisterController extends Controller
{
    public function store(Request $request)
    {
        // Reason to change 1: Validation rules change
        $request->validate([
            'name' => 'required',
            'email' => 'required|email|unique:users',
            'avatar' => 'required|image'
        ]);

        // Reason to change 2: Handling image manipulation
        $avatar = $request->file('avatar');
        $filename = time() . '.' . $avatar->getClientOriginalExtension();
        Image::make($avatar)->resize(300, 300)->save(public_path('/uploads/' . $filename));

        // Reason to change 3: Database architecture updates
        $user = User::create([
            'name' => $request->name,
            'email' => $request->email,
            'avatar' => $filename,
        ]);

        // Reason to change 4: Switching from Email to Slack/SMS
        Mail::to($user->email)->send(new \App\Mail\WelcomeMail($user));

        return response()->json(['message' => 'User created successfully!'], 201);
    }
}

The Laravel Mastery Approach (Adheres to SRP)

To build this like a framework architect, we segregate the tasks using dedicated Laravel features: Form Requests, Service Classes, and Events/Listeners.

Step 1: Handle Validation via Form Request

The controller doesn't need to know the validation rules. We delegate this to a dedicated request file.

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

class RegisterRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users,email',
            'avatar' => 'required|image|max:2048'
        ];
    }
}

Step 2: Extract Core Logic into a Action/Service Class

We create a dedicated PHP class whose only job is to orchestrate user registration and file handling.

namespace App\Actions;

use App\Models\User;
use App\Events\UserRegistered;
use Illuminate\Http\UploadedFile;

class RegisterNewUser
{
    public function execute(array $data, UploadedFile $avatar): User
    {
        // Handle the file upload logic cleanly
        $path = $avatar->store('avatars', 'public');

        $user = User::create([
            'name' => $data['name'],
            'email' => $data['email'],
            'avatar' => $path,
        ]);

        // Fire an event! This class doesn't care HOW notifications are sent.
        event(new UserRegistered($user));

        return $user;
    }
}

Step 3: Handle Communications via Events & Listeners

When the user is saved, an event fires. A dedicated Listener catches it and sends the mail asynchronously.

namespace App\Listeners;

use App\Events\UserRegistered;
use App\Mail\WelcomeMail;
use Illuminate\Support\Facades\Mail;
use Illuminate\Contracts\Queue\ShouldQueue;

class SendWelcomeNotification implements ShouldQueue
{
    public function handle(UserRegistered $event): void
    {
        // This class only changes if the notification delivery method changes
        Mail::to($event->user->email)->send(new WelcomeMail($event->user));
    }
}

Step 4: The Clean, Slim Master Controller

Now look at the controller. It has exactly one responsibility: Receive the HTTP request and return an HTTP response. It is highly readable and closed to external bugs.

namespace App\Http\Controllers;

use App\Http\Requests\RegisterRequest;
use App\Actions\RegisterNewUser;

class RegisterController extends Controller
{
    public function store(RegisterRequest $request, RegisterNewUser $registerAction)
    {
        // Execution is offloaded to specialized workers
        $user = $registerAction->execute(
            $request->validated(),
            $request->file('avatar')
        );

        return response()->json(['user' => $user], 201);
    }
}

Why this makes you a Laravel Master

Testing Simplicity: You can write a unit test for RegisterNewUser by passing a fake uploaded file without ever rendering an HTTP router or acting like a web browser.
Impeccable Reusability: If you need to register a user via an API Endpoint, a Blade Web Form, or a Terminal Artisan Command, you simply inject the RegisterNewUser action class and run it. You never have to duplicate code.