DEV Community: Anas Hussain

Laravel Facades Explained: Why They Feel So Clean and Powerful

Anas Hussain — Sat, 26 Sep 2026 14:38:05 +0000

1. Hook & Problem Statement

You're building a Laravel application. You need to cache some data. You write:

Cache::put('user_123', $user, 3600);
$user = Cache::get('user_123');

It works beautifully. The code is clean, readable, and expressive. You don't need to worry about instantiating anything. The Cache class is just... there.

Then you need to send an email:

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

Again, it just works. Clean. Simple. Powerful.

But what is Cache? What is Mail?

They're static facades. They look like static methods, but they're actually proxies to objects resolved from the service container.

Many developers use Laravel facades daily without understanding how they work. They're "magic." But behind the scenes, they're a sophisticated implementation of the Facade Pattern.

This pattern provides a simple, static-like interface to complex subsystems while maintaining testability and flexibility.

2. Why This Pattern Exists

The Software Engineering Problem It Solves

The Facade Pattern solves the problem of providing a simplified interface to a complex subsystem. It hides the complexity of the subsystem, making it easier to use.

The Pain That Existed Before

Before the Facade Pattern (or in codebases that don't use it), developers faced:

Complex Initialization: Using a service required multiple steps of configuration and instantiation.
Deep Dependencies: You needed to know the entire dependency graph to use a service.
Verbose Code: Simple operations required many lines of code.
Tight Coupling: Code was tightly coupled to the concrete implementation.
Difficult Testing: Testing required instantiating all dependencies.
Violation of Law of Demeter: Code had to "talk to strangers" to get things done.

Why Large Applications Need It

As applications grow, subsystems become more complex. A simple file storage operation might require:

Setting up the client
Configuring credentials
Handling errors
Managing retries
Logging operations

The Facade Pattern provides:

Simplicity: One method call for complex operations.
Decoupling: Facade hides the subsystem's complexity.
Testability: Facades can be mocked.
Readability: Code reads like plain English.
Consistency: All facades follow the same pattern.

3. Real World Analogy

The Hotel Concierge

Imagine a luxury hotel with hundreds of services: restaurants, spa, gym, laundry, room service, concierge, valet, etc.

The Bad Way:
You have to interact with each service directly:

Call the restaurant for a reservation.
Call the spa for a massage.
Call the valet for your car.
Call the concierge for directions.

You need to know every phone number and procedure.

The Facade Way:
You call the Concierge (the Facade):
"I need a dinner reservation, a massage at 3 PM, my car at 5 PM, and directions to the museum."

The concierge handles all the complexity. You have one point of contact for many services.

Analogy Mapping:

Concierge: The Facade (e.g., Cache, Mail, DB).
Hotel Services: The subsystem (e.g., CacheStore, Mailer, Database).
You: The client code.
Phone Number: The Facade's static-like interface.
Reservation Process: The subsystem's complexity.

Why it works: You don't need to know how the hotel works. You just ask the concierge, and they handle the details.

4. The Pain (Bad Design)

Let's look at code without facades—manually managing dependencies everywhere.

namespace App\Http\Controllers;

use App\Models\Order;
use App\Models\User;
use App\Services\Cache\RedisCacheService;
use App\Services\Mail\MailgunMailer;
use App\Services\Logging\FileLogger;
use App\Services\Storage\S3StorageService;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    private RedisCacheService $cache;
    private MailgunMailer $mailer;
    private FileLogger $logger;
    private S3StorageService $storage;

    public function __construct()
    {
        // Manual initialization—lots of configuration
        $this->cache = new RedisCacheService(
            config('cache.redis.host'),
            config('cache.redis.port'),
            config('cache.redis.password')
        );

        $this->mailer = new MailgunMailer(
            config('services.mailgun.api_key'),
            config('services.mailgun.domain'),
            config('services.mailgun.secret')
        );

        $this->logger = new FileLogger(
            storage_path('logs/orders.log')
        );

        $this->storage = new S3StorageService(
            config('services.s3.key'),
            config('services.s3.secret'),
            config('services.s3.region'),
            config('services.s3.bucket')
        );
    }

    public function store(Request $request)
    {
        // Validate
        $validated = $request->validate([
            'items' => 'required|array',
            'total' => 'required|numeric',
        ]);

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

        // Cache the order
        $this->cache->put('order_' . $order->id, $order, 3600);

        // Send confirmation email
        $user = User::find(auth()->id());
        $this->mailer->send(
            $user->email,
            'Order Confirmation',
            "Your order #{$order->id} has been created."
        );

        // Upload receipt to S3
        $receipt = $this->generateReceipt($order);
        $this->storage->put("receipts/{$order->id}.pdf", $receipt);

        // Log
        $this->logger->log("Order created: {$order->id}");

        return response()->json($order, 201);
    }
}

Why This Is Terrible

Complex Initialization: The constructor is filled with service instantiation and configuration.
Tight Coupling: The controller is coupled to RedisCacheService, MailgunMailer, FileLogger, and S3StorageService.
Duplicate Configuration: If you have 20 controllers, you repeat this initialization 20 times.
Difficult Testing: You can't test without real services or complex mocking.
Violates SRP: The controller handles HTTP requests AND service configuration.
Violates DIP: The controller depends on concrete implementations, not abstractions.

Why Developers Write Code Like This

They're not using facades.
They're not using dependency injection properly.
They're not separating concerns.
They think "it's just configuration."

5. Solution Overview

The Facade Pattern provides a unified, simplified interface to a complex subsystem. In Laravel, facades are static proxies that resolve to services in the container.

Core Idea

Instead of manually instantiating and configuring services, you use a facade that:

Provides a static interface to a service.
Resolves the service from the container.
Delegates all calls to the resolved service.
Handles configuration internally.

Main Participants

Facade Class: The static proxy (e.g., Cache, Mail, DB).
Service Container: Resolves the underlying service.
Underlying Service: The actual service being used (e.g., CacheStore, Mailer).
Client: Your application code that uses the facade.

How Objects Collaborate

Client → Facade → Service Container → Underlying Service

The client calls a static method on the facade. The facade resolves the service from the container. The service executes the operation.

Mental Model

Think of a remote control for your TV.

Remote Control: The Facade (simple interface).
Button Press: The method call.
TV: The underlying service.
Remote's Programming: The facade's resolution logic.

You don't need to know how the TV works. You just press buttons on the remote.

Benefits

Simplicity: Clean, readable code.
Decoupling: Hides subsystem complexity.
Testability: Facades can be mocked.
Consistency: All facades work the same way.
Lazy Loading: Services are only resolved when needed.

Trade-offs

Static Interface: Some argue it's less "pure" OOP.
Indirection: Harder to trace code flow.
Testing Overhead: Need to mock facades with shouldReceive().

6. UML Diagram

Laravel Facade Pattern Mermaid Diagram

Diagram Explanation

Cache is the facade (static interface).
CacheManager is the actual service (real instance).
Store is the interface for cache drivers.
Container resolves the CacheManager.
The facade delegates to the resolved instance.

7. Vanilla PHP Example

Let's build a simple facade system in vanilla PHP.

Before Refactoring (No Facade)

(The terrible code shown above)

After Refactoring (With Facade)

Step 1: The Container

class Container
{
    private array $bindings = [];
    private array $instances = [];

    public function bind(string $abstract, $concrete): void
    {
        $this->bindings[$abstract] = $concrete;
    }

    public function singleton(string $abstract, $concrete): void
    {
        $this->bindings[$abstract] = $concrete;
        $this->instances[$abstract] = null;
    }

    public function make(string $abstract)
    {
        if (isset($this->instances[$abstract])) {
            return $this->instances[$abstract];
        }

        $concrete = $this->bindings[$abstract] ?? $abstract;

        if (is_callable($concrete)) {
            $instance = $concrete($this);
        } else {
            $instance = new $concrete();
        }

        if (isset($this->instances[$abstract])) {
            $this->instances[$abstract] = $instance;
        }

        return $instance;
    }
}

Step 2: The Services

interface CacheStore
{
    public function get(string $key, $default = null);
    public function put(string $key, $value, int $seconds): void;
    public function remember(string $key, int $seconds, callable $callback);
}

class RedisCache implements CacheStore
{
    private array $storage = [];

    public function get(string $key, $default = null)
    {
        return $this->storage[$key] ?? $default;
    }

    public function put(string $key, $value, int $seconds): void
    {
        $this->storage[$key] = $value;
    }

    public function remember(string $key, int $seconds, callable $callback)
    {
        if ($this->get($key) === null) {
            $value = $callback();
            $this->put($key, $value, $seconds);
            return $value;
        }

        return $this->get($key);
    }
}

interface Mailer
{
    public function send(string $to, string $subject, string $body): void;
}

class MailgunMailer implements Mailer
{
    public function send(string $to, string $subject, string $body): void
    {
        echo "Sending email to {$to}: {$subject}\n";
    }
}

Step 3: The Facade Base Class

abstract class Facade
{
    protected static Container $container;

    public static function setContainer(Container $container): void
    {
        static::$container = $container;
    }

    protected static function getFacadeAccessor(): string
    {
        throw new \Exception('Facade does not define getFacadeAccessor');
    }

    public static function resolveFacadeInstance()
    {
        $accessor = static::getFacadeAccessor();
        return static::$container->make($accessor);
    }

    public static function __callStatic($method, $args)
    {
        $instance = static::resolveFacadeInstance();
        return $instance->$method(...$args);
    }
}

Step 4: The Concrete Facades

class Cache extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return 'cache';
    }
}

class Mail extends Facade
{
    protected static function getFacadeAccessor(): string
    {
        return 'mailer';
    }
}

Step 5: Setup and Usage

// Setup the container
$container = new Container();

// Bind services
$container->singleton('cache', function () {
    return new RedisCache();
});

$container->singleton('mailer', function () {
    return new MailgunMailer();
});

// Set the container for facades
Facade::setContainer($container);

// Usage
Cache::put('user_1', ['name' => 'John'], 3600);
$user = Cache::get('user_1');
echo $user['name']; // "John"

$cached = Cache::remember('expensive_computation', 60, function () {
    return ['result' => 42];
});
var_dump($cached); // ['result' => 42]

Mail::send('john@example.com', 'Welcome!', 'Welcome to our app!');
// Output: Sending email to john@example.com: Welcome!

What We Improved

Clean Interface: Cache::put() instead of $cache->put() with manual instantiation.
Lazy Loading: Services are only resolved when called.
Centralized Configuration: Service binding in one place.
Decoupling: Client code doesn't know about service implementation.
Testability: Facades can be mocked (as we'll see later).
Consistency: All facades work the same way.

8. Laravel Internal Example

Laravel's facade system is sophisticated and elegant. Let's look at how it works.

The Facade Base Class

// Illuminate\Support\Facades\Facade
abstract class Facade
{
    protected static $app;
    protected static $resolvedInstance = [];

    public static function getFacadeAccessor()
    {
        throw new \RuntimeException('Facade does not implement getFacadeAccessor');
    }

    public static function shouldReceive()
    {
        $name = static::getFacadeAccessor();

        if (static::isMock()) {
            // Return a mock instance
        }

        return static::$app->make($name);
    }

    public static function __callStatic($method, $args)
    {
        $instance = static::getFacadeRoot();

        if (!$instance) {
            throw new \RuntimeException('Facade root has not been set.');
        }

        return $instance->$method(...$args);
    }
}

Concrete Facades

// Illuminate\Support\Facades\Cache
class Cache extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'cache';
    }
}

// Illuminate\Support\Facades\Mail
class Mail extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'mailer';
    }
}

// Illuminate\Support\Facades\DB
class DB extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'db';
    }
}

// Illuminate\Support\Facades\Log
class Log extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'log';
    }
}

// Illuminate\Support\Facades\Storage
class Storage extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'filesystem';
    }
}

How It Works in Laravel

Registration: Services are registered in the service container.

// In a service provider
$this->app->singleton('cache', function ($app) {
    return new CacheManager($app);
});

Resolution: When you call Cache::put(), the facade resolves 'cache' from the container.
Delegation: The facade delegates the call to the resolved instance.

The Elegance

Lazy Loading: Facades are resolved on first use.
No Manual Configuration: Everything is handled by the container.
Testability: Cache::shouldReceive('get')->andReturn('value')
Consistency: All facades follow the same pattern.
Extensibility: You can create your own facades.

Facades vs. Helper Functions

Laravel also provides helper functions for common facades:

// Facade
Cache::get('key');

// Helper
cache('key');

// Both work!

The helper functions are shorter but less explicit.

9. Real Laravel Application Example

Let's build a Report Generation System using Laravel facades.

Scenario

Your application needs to generate and deliver reports:

Fetch data from the database
Cache results
Generate PDF reports
Send via email
Log all operations
Upload to storage

Implementation

Step 1: The Report Service (Using Facades)

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

use Carbon\Carbon;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Facades\View;

class ReportService
{
    public function generateAndSendReport(string $reportType, array $data, array $recipients): void
    {
        // Generate a unique report key
        $reportKey = $this->generateReportKey($reportType, $data);

        // Check cache
        $reportData = Cache::remember("report_{$reportKey}", 3600, function () use ($reportType, $data) {
            // Fetch data from database
            $results = $this->fetchData($reportType, $data);

            // Log the fetch
            Log::info('Report data fetched', [
                'type' => $reportType,
                'record_count' => count($results),
            ]);

            return $results;
        });

        // Generate PDF
        $pdf = $this->generatePDF($reportType, $reportData);

        // Store the PDF
        $filename = "reports/report_{$reportKey}_" . Carbon::now()->format('Y-m-d_H-i-s') . '.pdf';
        Storage::put($filename, $pdf);

        // Log storage
        Log::info('Report stored', [
            'filename' => $filename,
            'size' => strlen($pdf),
        ]);

        // Send email with attachment
        Mail::send(
            'emails.report',
            ['type' => $reportType, 'date' => Carbon::now()],
            function ($message) use ($recipients, $filename) {
                $message->to($recipients)
                        ->subject("Report: {$this->getReportTitle($filename)}")
                        ->attach(
                            Storage::path($filename),
                            ['as' => 'report.pdf', 'mime' => 'application/pdf']
                        );
            }
        );

        // Log completion
        Log::info('Report delivered', [
            'type' => $reportType,
            'recipients' => $recipients,
            'filename' => $filename,
        ]);
    }

    private function generateReportKey(string $reportType, array $data): string
    {
        $dataHash = md5(json_encode($data));
        return "{$reportType}_{$dataHash}";
    }

    private function fetchData(string $reportType, array $data): array
    {
        // Use DB facade
        return DB::table('reports')
            ->where('type', $reportType)
            ->whereBetween('created_at', $data['date_range'] ?? [])
            ->get()
            ->toArray();
    }

    private function generatePDF(string $reportType, array $data): string
    {
        // Use View facade
        $html = View::make('reports.template', [
            'type' => $reportType,
            'data' => $data,
        ])->render();

        // In a real app, use DomPDF or similar
        return $html;
    }

    private function getReportTitle(string $filename): string
    {
        $parts = explode('_', $filename);
        return $parts[1] ?? 'Report';
    }
}

Step 2: The Controller (Using the Service)

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

use App\Services\ReportService;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Illuminate\Support\Facades\Log;

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

    public function generate(Request $request)
    {
        $validated = $request->validate([
            'type' => 'required|string',
            'date_from' => 'required|date',
            'date_to' => 'required|date|after:date_from',
        ]);

        $this->reportService->generateAndSendReport(
            $validated['type'],
            [
                'date_range' => [$validated['date_from'], $validated['date_to']],
            ],
            [$request->user()->email]
        );

        Log::info('Report generation initiated', [
            'user' => Auth::id(),
            'type' => $validated['type'],
        ]);

        return response()->json(['message' => 'Report is being generated']);
    }
}

Step 3: Custom Facade for the Report Service

// app/Facades/Report.php
namespace App\Facades;

use Illuminate\Support\Facades\Facade;

/**
 * @method static void generateAndSendReport(string $reportType, array $data, array $recipients)
 */
class Report extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'report.service';
    }
}

Step 4: Service Provider Registration

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

use App\Services\ReportService;
use Illuminate\Support\ServiceProvider;

class ReportServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton('report.service', function ($app) {
            return new ReportService();
        });
    }
}

Step 5: Using the Custom Facade

// In a controller or command
use App\Facades\Report;

class WeeklyReportCommand extends Command
{
    public function handle()
    {
        Report::generateAndSendReport(
            'weekly_sales',
            ['date_range' => [now()->subWeek(), now()]],
            ['admin@example.com']
        );
    }
}

Why This Works

Clean Code: The service uses facades for everything—no manual instantiation.
Decoupling: The service doesn't know about the underlying implementations.
Testability: You can mock Cache, DB, Mail, etc.
Readability: The code is expressive and self-documenting.
Consistency: All facades follow the same pattern.

10. SOLID Principles Mapping

S - Single Responsibility Principle (SRP)

Each facade represents a single service:

Cache: Caching operations.
Mail: Email operations.
DB: Database operations.
Log: Logging operations.
Storage: File storage operations.

O - Open/Closed Principle (OCP)

Facades are open for extension but closed for modification:

// You can create your own facades
class Report extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'report.service';
    }
}

// The facade system doesn't need to be modified

D - Dependency Inversion Principle (DIP)

The facade resolves services from the container, which handles the dependencies:

// The facade doesn't depend on concrete implementations
Cache::get('key');

// The container resolves the actual implementation

L - Liskov Substitution Principle (LSP)

All facades work the same way and can be substituted.

I - Interface Segregation Principle (ISP)

Each facade provides a focused interface:

Cache: Only cache operations.
Mail: Only mail operations.

11. Trade-offs

Benefits

Simplicity: Clean, readable code.
Decoupling: Hides subsystem complexity.
Testability: Facades can be mocked.
Consistency: All facades work the same way.
Lazy Loading: Services are resolved only when used.
Extensibility: Create custom facades easily.

Costs

Static Interface: Some argue it's less "pure" OOP.
Indirection: Harder to trace code flow.
Testing Overhead: Need to mock facades with shouldReceive().
Hidden Dependencies: Dependencies aren't explicit in the constructor.

When Is Complexity Justified?

Use facades when:

You want a simple, expressive interface.
The underlying service is complex.
You want to hide implementation details.
You're building a framework or library.

Avoid facades when:

You need explicit dependencies (constructor injection).
You're writing highly testable code.
You're following pure Dependency Injection.

12. When NOT To Use It

3 Green Flags (USE FACADES)

Simple Operations: The code is simple and expressive.
Complex Subsystem: The service has complex configuration.
Framework Code: You're building or extending Laravel.

3 Red Flags (AVOID FACADES)

Explicit Dependencies: You want to see dependencies in the constructor.
Pure DI: You're following strict Dependency Injection.
Complex Logic: The method does many different things.

13. Common Mistakes

1. Using Facades for Business Logic

// BAD: Business logic in controller using facades
class OrderController
{
    public function store(Request $request)
    {
        // ... business logic directly in controller
        Cache::put(...);
        Mail::send(...);
        Log::info(...);
    }
}

// GOOD: Inject a service
class OrderController
{
    private OrderService $orderService;

    public function store(Request $request)
    {
        return $this->orderService->createOrder($request->all());
    }
}

2. Not Mocking Facades in Tests

// BAD: Real facades in tests
public function testOrderCreation()
{
    // Real services are used
    $response = $this->post('/orders', $data);
}

// GOOD: Mock facades
public function testOrderCreation()
{
    Cache::shouldReceive('put')->once();
    Mail::shouldReceive('send')->once();

    $response = $this->post('/orders', $data);
}

3. Creating God Facades

// BAD: God facade doing everything
class Everything extends Facade
{
    protected static function getFacadeAccessor()
    {
        return 'everything';
    }
}

// GOOD: Focused facades
class Cache extends Facade { /* ... */ }
class Mail extends Facade { /* ... */ }
class Log extends Facade { /* ... */ }

4. Using Facades in Service Classes

// BAD: Service class using facades
class OrderService
{
    public function createOrder($data)
    {
        Cache::put(...); // Hard to test
        Mail::send(...); // Hard to test
    }
}

// GOOD: Service class with injected dependencies
class OrderService
{
    private CacheStore $cache;
    private Mailer $mailer;

    public function __construct(CacheStore $cache, Mailer $mailer)
    {
        $this->cache = $cache;
        $this->mailer = $mailer;
    }
}

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is a facade in Laravel?
A: A facade is a static proxy to a service in the container. It provides a simple, expressive interface to complex subsystems.
Q: How do facades work in Laravel?
A: Facades resolve a service from the container and delegate all calls to that service.
Q: What's the difference between a facade and a helper function?
A: Facades are static proxies with a class name. Helper functions are global functions (e.g., cache(), logger()).
Q: When would you use a facade instead of dependency injection?
A: When you want a simple, expressive interface and the service is used in many places.
Q: Can you create custom facades in Laravel?
A: Yes, by extending Illuminate\Support\Facades\Facade and implementing getFacadeAccessor().

Senior/Architect

Q: Explain the difference between facades and the Facade Pattern.
A: The Facade Pattern is a design pattern that provides a simplified interface to a complex system. Laravel's facades are a specific implementation that uses static proxies.
Q: How do you test code that uses facades?
A: Use shouldReceive() to mock the facade's methods.
Q: What are the performance implications of facades?
A: Facades use lazy loading, so performance overhead is minimal. The service is only resolved when first used.
Q: How do facades differ from real static classes?
A: Facades use the container to resolve a real instance. Real static classes don't use the container.
Q: What's the relationship between facades and the service container?
A: Facades resolve services from the container. The container manages the service's lifecycle and dependencies.

15. Interactive Practice Challenge

The Requirement

You're building a Notification System that uses facades everywhere. You need to refactor it to be more testable while keeping the facade interface.

The Code (POOR DESIGN)

namespace App\Services;

use App\Models\User;
use App\Models\Notification;
use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Queue;
use Illuminate\Support\Facades\DB;

class NotificationService
{
    public function sendNotification(User $user, Notification $notification): void
    {
        // Check if user is subscribed
        if (!$this->isSubscribed($user)) {
            Log::info('User not subscribed', ['user' => $user->id]);
            return;
        }

        // Check rate limit
        if ($this->rateLimited($user)) {
            Log::warning('Rate limit exceeded', ['user' => $user->id]);
            return;
        }

        // Send via email
        Mail::to($user->email)->send(new NotificationMail($notification));

        // Send via SMS if enabled
        if ($user->phone && $this->smsEnabled($user)) {
            $this->sendSms($user->phone, $notification->content);
        }

        // Cache the last sent time
        Cache::put("notify_{$user->id}_last", time(), 3600);

        // Log the notification
        DB::table('notifications_log')->insert([
            'user_id' => $user->id,
            'notification_id' => $notification->id,
            'sent_at' => now(),
        ]);

        // Queue a follow-up
        Queue::push(new FollowUpJob($user, $notification));
    }

    private function isSubscribed(User $user): bool
    {
        return Cache::remember("subscribed_{$user->id}", 3600, function () use ($user) {
            return DB::table('subscriptions')
                ->where('user_id', $user->id)
                ->where('active', true)
                ->exists();
        });
    }

    private function rateLimited(User $user): bool
    {
        $lastSent = Cache::get("notify_{$user->id}_last", 0);
        return time() - $lastSent < 60; // 1 minute limit
    }

    private function smsEnabled(User $user): bool
    {
        return $user->preferences['sms'] ?? false;
    }

    private function sendSms(string $phone, string $content): void
    {
        // SMS implementation
        Log::info('SMS sent', ['phone' => $phone]);
    }
}

The Challenges

The code uses facades everywhere, making it difficult to test. You need to:

Make the service testable without removing facades.
Add support for new notification channels (Slack, Push).
Add retry logic for failed notifications.
Add analytics tracking for notification delivery.

Your Task

Refactor this system to be more maintainable while preserving the facade pattern. Specifically:

Extract facade usage into separate services (optional).
Make facades mockable in tests.
Add dependency injection where it makes sense.
Implement proper error handling for each channel.
Create a notification factory for different channels.

Questions to Consider

How do you test code with facades?
How do you handle different notification channels?
How do you implement retry logic?
How do you track delivery metrics?
How do you handle rate limiting across channels?

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

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: A facade provides a simplified, static-like interface to a complex subsystem, hiding its complexity and configuration.
One-sentence intuition: Facades are like a concierge that handles all the details of a complex hotel.
One-sentence decision rule: Use facades for clean, expressive code when the underlying service is complex and used in many places.

17. Related Concepts

SOLID Principles

Single Responsibility: Each facade handles one service.
Open/Closed: Facades can be extended with custom facades.
Dependency Inversion: Facades resolve from the container.
Liskov Substitution: All facades work the same way.

Design Patterns

Facade Pattern: The pattern itself.
Proxy Pattern: Facades are a form of proxy.
Static Factory: Facades resolve services from the container.
Singleton: Services are often singletons.

Laravel Internals

Service Container: Resolves facades.
Service Providers: Register services for facades.
Contracts: Define the interfaces that facades use.
Helpers: Global helper functions.
Eloquent: Uses facades for database operations.

Enterprise Patterns

Facade: The pattern itself.
Service Layer: Often uses facades.
Gateway: Similar to facades for external services.
Proxy: Similar concept.

Final Thoughts

Laravel facades are one of the most misunderstood features of the framework. They look like static methods, but they're actually elegant proxies to the service container.

They provide:

Clean Code: Expressive, readable interfaces.
Decoupling: Hide subsystem complexity.
Testability: Easy to mock.
Consistency: All facades work the same way.

Use facades wisely. They're powerful when used correctly and dangerous when overused.

Remember: Facades are a tool, not a silver bullet. Use them for the right reasons.

Github: Facade Pattern Practice Labs

The Adapter Pattern: A Laravel Developer's Guide to API Integration

Anas Hussain — Wed, 23 Sep 2026 10:44:07 +0000

1. Hook & Problem Statement

You're building a Laravel application. You need to integrate with a third-party payment gateway.

You find a popular package with a clean API:

$payment = new PaymentGateway();
$payment->setApiKey('secret');
$payment->charge(100, 'USD');

You integrate it across 20 different services and controllers. Everything works perfectly.

Then the payment gateway is acquired by another company. The new API is completely different:

$client = new PaymentClient(['api_key' => 'secret']);
$request = new ChargeRequest(['amount' => 100, 'currency' => 'USD']);
$response = $client->send($request);

Now you have to update 20 files. You search your codebase for PaymentGateway and find references everywhere. It's a nightmare.

This is the problem with tight coupling to third-party APIs.

Third-party APIs change. They have complex APIs. They have inconsistent error handling. They have different authentication mechanisms.

The Adapter Pattern is designed to solve this problem. It wraps the third-party API in a consistent interface that your application can depend on.

2. Why This Pattern Exists

The Software Engineering Problem It Solves

The Adapter Pattern solves the problem of making incompatible interfaces work together. It acts as a bridge between your application's expected interface and a third-party API's actual interface.

The Pain That Existed Before

Before the Adapter Pattern (or in codebases that don't use it), developers faced:

Tight Coupling: Application code was tightly coupled to third-party APIs.
API Changes: A vendor API change required changes across the entire codebase.
Inconsistent Interfaces: Different APIs had different patterns and signatures.
Complex Initialization: APIs required complex setup and configuration.
Error Handling Inconsistency: Each API threw different exceptions.
Testing Difficulty: You couldn't easily mock or test third-party APIs.

Why Large Applications Need It

As applications grow, they integrate with more third-party services:

Payment gateways (Stripe, PayPal, Braintree)
Notification services (Twilio, SendGrid, Slack)
Storage providers (AWS S3, GCS, Azure)
CRM systems (Salesforce, HubSpot)
Analytics services (Google Analytics, Mixpanel)
Social media APIs (Twitter, Facebook, LinkedIn)

The Adapter Pattern provides:

Consistent Interface: Your application uses one interface for all services.
Encapsulation: API complexity is hidden behind the adapter.
Testability: Adapters can be mocked for testing.
Flexibility: Swap providers without changing your application code.
Open/Closed Compliance: Add new adapters without modifying existing code.

3. Real World Analogy

The Power Plug Adapter

Imagine you're traveling to a different country. You have a laptop that uses a Type A plug (two flat prongs). The country uses Type C sockets (two round prongs).

You can't connect your laptop directly. The interfaces are incompatible.

The Power Plug Adapter:
The adapter has a Type A socket on one side and Type C prongs on the other.

Type A side: Matches your laptop's plug (your application's interface).
Type C side: Matches the wall socket (the third-party API).
The Adapter: Converts the power (data/requests) between the two.

Analogy Mapping:

Laptop: Your application.
Power Plug (Type A): Your application's expected interface.
Wall Socket (Type C): The third-party API.
Power Adapter: The Adapter Pattern.
Traveler: The developer.
Different Countries: Different third-party APIs.

Why it works: You don't have to change your laptop or the wall socket. The adapter handles the conversion.

4. The Pain (Bad Design)

Let's look at a typical tight coupling to a third-party API.

namespace App\Services;

use Stripe\StripeClient;
use Stripe\Exception\CardException;
use Stripe\Exception\RateLimitException;
use Stripe\Exception\InvalidRequestException;
use Stripe\Exception\AuthenticationException;
use Stripe\Exception\ApiConnectionException;
use Stripe\Exception\ApiErrorException;
use Illuminate\Support\Facades\Log;

class PaymentService
{
    private StripeClient $stripe;

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

    public function processPayment(Order $order): array
    {
        try {
            // Stripe-specific API call
            $intent = $this->stripe->paymentIntents->create([
                'amount' => $order->total * 100,
                'currency' => $order->currency,
                'payment_method' => $order->payment_method_id,
                'confirmation_method' => 'manual',
                'confirm' => true,
                'metadata' => [
                    'order_id' => $order->id,
                    'customer_id' => $order->user_id,
                ],
                'statement_descriptor' => 'Order ' . $order->id,
                'description' => "Order #{$order->id}",
            ]);

            // Stripe-specific response handling
            if ($intent->status === 'requires_action') {
                return [
                    'status' => 'requires_action',
                    'client_secret' => $intent->client_secret,
                    'payment_intent_id' => $intent->id,
                ];
            }

            if ($intent->status === 'succeeded') {
                $order->status = 'paid';
                $order->payment_intent_id = $intent->id;
                $order->save();

                return [
                    'status' => 'succeeded',
                    'payment_intent_id' => $intent->id,
                ];
            }

            return [
                'status' => 'failed',
                'error' => "Unexpected status: {$intent->status}",
            ];

        } catch (CardException $e) {
            // Stripe-specific exception handling
            Log::error('Payment failed: Card error', [
                'error' => $e->getMessage(),
                'decline_code' => $e->getDeclineCode(),
                'order' => $order->id,
            ]);
            return ['status' => 'failed', 'error' => 'Card declined: ' . $e->getMessage()];

        } catch (RateLimitException $e) {
            Log::error('Payment failed: Rate limit', ['error' => $e->getMessage()]);
            return ['status' => 'failed', 'error' => 'Too many requests. Please try again later.'];

        } catch (InvalidRequestException $e) {
            Log::error('Payment failed: Invalid request', ['error' => $e->getMessage()]);
            return ['status' => 'failed', 'error' => 'Invalid payment request.'];

        } catch (AuthenticationException $e) {
            Log::error('Payment failed: Authentication error', ['error' => $e->getMessage()]);
            return ['status' => 'failed', 'error' => 'Payment service authentication failed.'];

        } catch (ApiConnectionException $e) {
            Log::error('Payment failed: Connection error', ['error' => $e->getMessage()]);
            return ['status' => 'failed', 'error' => 'Unable to connect to payment service.'];

        } catch (ApiErrorException $e) {
            Log::error('Payment failed: API error', ['error' => $e->getMessage()]);
            return ['status' => 'failed', 'error' => 'Payment service error.'];
        }
    }

    public function refundPayment(string $paymentIntentId, float $amount): array
    {
        try {
            // Stripe-specific refund
            $refund = $this->stripe->refunds->create([
                'payment_intent' => $paymentIntentId,
                'amount' => $amount * 100,
            ]);

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

        } catch (\Exception $e) {
            Log::error('Refund failed', ['error' => $e->getMessage()]);
            return ['success' => false, 'error' => $e->getMessage()];
        }
    }
}

Why This Is Terrible

Tight Coupling: The service is tightly coupled to Stripe's API and exceptions.
Complex Initialization: The Stripe client is created inside the constructor.
Inconsistent Error Handling: Stripe-specific exceptions are handled directly.
Duplication: If you add PayPal or other payment methods, you'll duplicate this logic.
Difficult Testing: Testing requires mocking the Stripe client or making real API calls.
Violates OCP: Adding a new payment method requires modifying this class.
Violates DIP: The class depends on a concrete implementation (StripeClient).

Why Developers Write Code Like This

It's the "quick and dirty" approach.
They think "we'll only use Stripe."
They don't anticipate API changes.
They haven't learned the Adapter Pattern.

5. Solution Overview

The Adapter Pattern is a structural design pattern that allows objects with incompatible interfaces to work together. It acts as a bridge between two incompatible interfaces.

Core Idea

Instead of your application code directly calling the third-party API, you create an adapter that wraps the third-party API and exposes a consistent interface that your application can depend on.

Main Participants

Target Interface: The interface that your application expects.
Adapter: The class that implements the target interface and wraps the third-party API.
Adaptee: The third-party API that you're adapting.
Client: Your application code that uses the target interface.

How Objects Collaborate

Client → Target Interface ← Adapter → Adaptee (Third-Party API)

The client calls the target interface. The adapter translates the calls to the adaptee's interface.

Mental Model

Think of a translator.

English Speaker: Your application code.
French Speaker: The third-party API.
Translator: The Adapter Pattern.
English Phrases: Your application's expected interface.
French Phrases: The third-party API's interface.

The translator converts English to French, allowing the two to communicate.

Benefits

Decoupling: Application code is decoupled from third-party APIs.
Consistency: All adapters implement the same interface.
Testability: Mock the adapter for testing.
Flexibility: Swap providers without changing application code.
Encapsulation: API complexity is hidden.

Trade-offs

More Classes: You need an adapter for each API.
Boilerplate: You need to write the adapter logic.
Indirection: More layers between your code and the API.

6. UML Diagram

Laravel Adapter Pattern Mermaid Diagram

Diagram Explanation

PaymentInterface is the target interface that the application expects.
StripeAdapter and PayPalAdapter implement the interface.
Each adapter wraps its respective third-party client.
PaymentService depends on the interface, not the concrete adapters.

7. Vanilla PHP Example

Let's refactor the payment service using the Adapter Pattern.

Before Refactoring

(The terrible code shown above)

After Refactoring

Step 1: Define the Target Interface

interface PaymentInterface
{
    public function charge(float $amount, string $currency, string $paymentMethodId): array;
    public function refund(string $paymentIntentId, float $amount): array;
}

Step 2: Create the Stripe Adapter

class StripeAdapter implements PaymentInterface
{
    private \Stripe\StripeClient $stripe;
    private LoggerInterface $logger;

    public function __construct(string $secretKey, LoggerInterface $logger = null)
    {
        $this->stripe = new \Stripe\StripeClient($secretKey);
        $this->logger = $logger ?? new NullLogger();
    }

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

            $this->logger->info('Stripe charge successful', ['intent_id' => $intent->id]);

            return $this->formatResponse($intent);

        } catch (\Exception $e) {
            $this->logger->error('Stripe charge failed', ['error' => $e->getMessage()]);
            return $this->handleStripeException($e);
        }
    }

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

            $this->logger->info('Stripe refund successful', ['refund_id' => $refund->id]);

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

        } catch (\Exception $e) {
            $this->logger->error('Stripe refund failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => $this->getUserFriendlyMessage($e),
            ];
        }
    }

    private function formatAmount(float $amount): int
    {
        return (int)($amount * 100);
    }

    private function formatResponse($intent): array
    {
        return [
            'success' => $intent->status === 'succeeded',
            'status' => $intent->status,
            'payment_intent_id' => $intent->id,
            'client_secret' => $intent->client_secret ?? null,
            'error' => null,
        ];
    }

    private function handleStripeException(\Exception $e): array
    {
        $status = 'failed';
        $error = $this->getUserFriendlyMessage($e);

        // Map Stripe exceptions to friendly messages
        if ($e instanceof \Stripe\Exception\CardException) {
            $error = 'Card declined: ' . $e->getMessage();
        } elseif ($e instanceof \Stripe\Exception\RateLimitException) {
            $error = 'Too many requests. Please try again later.';
        } elseif ($e instanceof \Stripe\Exception\AuthenticationException) {
            $error = 'Payment service authentication failed.';
        } elseif ($e instanceof \Stripe\Exception\ApiConnectionException) {
            $error = 'Unable to connect to payment service.';
        }

        return [
            'success' => false,
            'status' => $status,
            'error' => $error,
        ];
    }

    private function getUserFriendlyMessage(\Exception $e): string
    {
        return 'Payment failed: ' . $e->getMessage();
    }
}

Step 3: Create the PayPal Adapter

class PayPalAdapter implements PaymentInterface
{
    private \PayPal\Rest\ApiContext $apiContext;
    private LoggerInterface $logger;

    public function __construct(string $clientId, string $clientSecret, LoggerInterface $logger = null)
    {
        $this->apiContext = new \PayPal\Rest\ApiContext(
            new \PayPal\Auth\OAuthTokenCredential($clientId, $clientSecret)
        );
        $this->logger = $logger ?? new NullLogger();
    }

    public function charge(float $amount, string $currency, string $paymentMethodId): array
    {
        try {
            $payment = new \PayPal\Api\Payment();
            $payment->setIntent('sale')
                ->setPayer([
                    'payment_method' => 'paypal',
                    'payer_info' => ['payment_method_id' => $paymentMethodId],
                ])
                ->setTransactions([[
                    'amount' => [
                        'total' => number_format($amount, 2, '.', ''),
                        'currency' => $currency,
                    ],
                ]])
                ->setRedirectUrls([
                    'return_url' => 'http://example.com/return',
                    'cancel_url' => 'http://example.com/cancel',
                ]);

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

            $this->logger->info('PayPal charge created', ['payment_id' => $payment->getId()]);

            // Get approval URL
            $approvalUrl = null;
            foreach ($payment->getLinks() as $link) {
                if ($link->getRel() === 'approval_url') {
                    $approvalUrl = $link->getHref();
                    break;
                }
            }

            return [
                'success' => true,
                'status' => 'pending',
                'payment_intent_id' => $payment->getId(),
                'approval_url' => $approvalUrl,
                'error' => null,
            ];

        } catch (\Exception $e) {
            $this->logger->error('PayPal charge failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'status' => 'failed',
                'error' => 'PayPal charge failed: ' . $e->getMessage(),
            ];
        }
    }

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

            $refund = new \PayPal\Api\Refund();
            $refund->setAmount([
                'total' => number_format($amount, 2, '.', ''),
                'currency' => 'USD',
            ]);

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

            $this->logger->info('PayPal refund successful', ['refund_id' => $refunded->getId()]);

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

        } catch (\Exception $e) {
            $this->logger->error('PayPal refund failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => 'Refund failed: ' . $e->getMessage(),
            ];
        }
    }
}

Step 4: The Refactored Service

class PaymentService
{
    private PaymentInterface $payment;

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

    public function processPayment(Order $order): array
    {
        $result = $this->payment->charge(
            $order->total,
            $order->currency,
            $order->payment_method_id
        );

        if ($result['success'] && $result['status'] === 'succeeded') {
            $order->status = 'paid';
            $order->payment_intent_id = $result['payment_intent_id'];
            $order->save();
        }

        return $result;
    }

    public function refundPayment(string $paymentIntentId, float $amount): array
    {
        return $this->payment->refund($paymentIntentId, $amount);
    }
}

Step 5: Usage

// In your service provider or controller
$adapter = new StripeAdapter(config('services.stripe.secret'));
$paymentService = new PaymentService($adapter);

$result = $paymentService->processPayment($order);

// Or with PayPal
$adapter = new PayPalAdapter(
    config('services.paypal.client_id'),
    config('services.paypal.secret')
);
$paymentService = new PaymentService($adapter);

What We Improved

Decoupling: PaymentService doesn't know about Stripe or PayPal.
Consistent Interface: Both adapters implement PaymentInterface.
Centralized Error Handling: API-specific errors are handled in the adapters.
Testability: Mock PaymentInterface for testing.
Open/Closed: Add a new payment method by creating a new adapter.
Encapsulation: API complexity is hidden in the adapters.

8. Laravel Internal Example

Laravel uses the Adapter Pattern extensively. Let's look at some key examples.

Filesystem Adapters

Laravel's Filesystem uses adapters to support different storage providers.

// Illuminate\Contracts\Filesystem\Filesystem (Target Interface)
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
}

// LocalFilesystemAdapter (Local)
class LocalFilesystemAdapter implements Filesystem
{
    private \League\Flysystem\Filesystem $flysystem;

    public function put(string $path, $contents, $options = []): bool
    {
        return $this->flysystem->write($path, $contents);
    }
    // ... implementation
}

// S3FilesystemAdapter (S3)
class S3FilesystemAdapter implements Filesystem
{
    private \League\Flysystem\AwsS3v3\AwsS3Adapter $adapter;

    public function put(string $path, $contents, $options = []): bool
    {
        return $this->adapter->write($path, $contents);
    }
    // ... implementation
}

Why This Is Elegant:

The same Storage::disk('local')->put() works for all drivers.
Adding a new driver only requires creating a new adapter.
The filesystem API is consistent across providers.

Cache Adapters

Laravel's Cache system uses adapters.

// Illuminate\Contracts\Cache\Store (Target Interface)
interface Store
{
    public function get($key);
    public function put($key, $value, $seconds);
    public function increment($key, $value = 1);
    public function decrement($key, $value = 1);
    public function forever($key, $value);
    public function forget($key);
    public function flush();
}

// RedisStore (Adapter)
class RedisStore implements Store
{
    private \Illuminate\Redis\Connections\Connection $redis;

    public function put($key, $value, $seconds)
    {
        // Redis-specific implementation
    }
}

// MemcachedStore (Adapter)
class MemcachedStore implements Store
{
    private \Memcached $memcached;

    public function put($key, $value, $seconds)
    {
        // Memcached-specific implementation
    }
}

Queue Adapters

Laravel's Queue system uses adapters.

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

// DatabaseQueue (Adapter)
class DatabaseQueue implements Queue
{
    private DatabaseConnection $connection;

    public function push($job, $data = '', $queue = null)
    {
        // Database-specific implementation
    }
}

// RedisQueue (Adapter)
class RedisQueue implements Queue
{
    private Connection $redis;

    public function push($job, $data = '', $queue = null)
    {
        // Redis-specific implementation
    }
}

// SqsQueue (Adapter)
class SqsQueue implements Queue
{
    private SqsClient $sqs;

    public function push($job, $data = '', $queue = null)
    {
        // SQS-specific implementation
    }
}

Mail Adapters

Laravel's Mail system uses adapters.

// Illuminate\Contracts\Mail\Mailer (Target Interface)
interface Mailer
{
    public function send($view, array $data = [], $callback = null);
    public function queue($view, array $data = [], $callback = null);
    public function raw($text, $callback = null);
}

// SmtpMailer (Adapter)
class SmtpMailer implements Mailer
{
    private \Swift_Mailer $swift;

    public function send($view, array $data = [], $callback = null)
    {
        // SMTP-specific implementation
    }
}

// MailgunMailer (Adapter)
class MailgunMailer implements Mailer
{
    private MailgunClient $client;

    public function send($view, array $data = [], $callback = null)
    {
        // Mailgun-specific implementation
    }
}

Session Adapters

Laravel's Session system uses adapters.

// Illuminate\Contracts\Session\Session (Target Interface)
interface Session
{
    public function get($name, $default = null);
    public function put($key, $value);
    public function remove($key);
    public function all();
    public function flush();
}

// DatabaseSessionHandler (Adapter)
class DatabaseSessionHandler implements Session
{
    private DatabaseConnection $connection;

    public function put($key, $value)
    {
        // Database-specific implementation
    }
}

// FileSessionHandler (Adapter)
class FileSessionHandler implements Session
{
    private Filesystem $files;

    public function put($key, $value)
    {
        // File-specific implementation
    }
}

9. Real Laravel Application Example

Let's build a Shipping Provider Integration using the Adapter Pattern.

Scenario

Your e-commerce application needs to integrate with multiple shipping providers:

FedEx: Good for domestic, reliable, but expensive.
UPS: Good for international, complex rates.
USPS: Good for small packages, cheap.
DHL: Good for expedited international.

Each provider has a different API, authentication, and response format.

Implementation

Step 1: Define the Target Interface

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

use App\Models\Shipment;
use App\Models\Order;

interface ShippingInterface
{
    public function getRates(Order $order): array;
    public function createShipment(Shipment $shipment): array;
    public function trackShipment(string $trackingNumber): array;
    public function cancelShipment(string $shipmentId): bool;
    public function getServiceTypes(): array;
}

Step 2: Create Result DTOs

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

class ShippingRate
{
    public function __construct(
        public readonly string $service,
        public readonly float $price,
        public readonly string $currency = 'USD',
        public readonly string $delivery_time = '',
        public readonly array $metadata = []
    ) {}
}

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

class ShippingResult
{
    public function __construct(
        public readonly bool $success,
        public readonly ?string $trackingNumber = null,
        public readonly ?string $shipmentId = null,
        public readonly ?string $label = null,
        public readonly ?string $error = null,
        public readonly array $metadata = []
    ) {}
}

Step 3: Create the FedEx Adapter

// app/Services/Shipping/FedExAdapter.php
namespace App\Services\Shipping;

use App\Contracts\ShippingInterface;
use App\DTO\ShippingRate;
use App\DTO\ShippingResult;
use App\Models\Order;
use App\Models\Shipment;
use Illuminate\Support\Facades\Log;

class FedExAdapter implements ShippingInterface
{
    private FedExClient $client;

    public function __construct(string $apiKey, string $password, string $accountNumber)
    {
        $this->client = new FedExClient([
            'api_key' => $apiKey,
            'password' => $password,
            'account_number' => $accountNumber,
            'environment' => config('app.env') === 'production' ? 'live' : 'test',
        ]);
    }

    public function getRates(Order $order): array
    {
        try {
            $response = $this->client->getRates([
                'from_address' => $this->getFromAddress(),
                'to_address' => $this->getToAddress($order),
                'package_weight' => $order->total_weight,
                'package_dimensions' => $this->getDimensions($order),
                'currency' => $order->currency,
            ]);

            $rates = [];
            foreach ($response['rates'] as $rate) {
                $rates[] = new ShippingRate(
                    service: $this->mapServiceType($rate['service_type']),
                    price: (float)$rate['total_charge'],
                    currency: $rate['currency'] ?? 'USD',
                    delivery_time: $rate['delivery_time'] ?? '',
                    metadata: ['service_code' => $rate['service_type']]
                );
            }

            return $rates;

        } catch (\Exception $e) {
            Log::error('FedEx rate fetch failed', ['error' => $e->getMessage()]);
            return [];
        }
    }

    public function createShipment(Shipment $shipment): array
    {
        try {
            $response = $this->client->createShipment([
                'from_address' => $this->getFromAddress(),
                'to_address' => $this->getToAddress($shipment->order),
                'package_weight' => $shipment->order->total_weight,
                'package_dimensions' => $this->getDimensions($shipment->order),
                'service_type' => $this->getServiceCode($shipment->service_type),
                'reference' => $shipment->order->id,
                'insurance' => $shipment->order->subtotal > 1000,
            ]);

            $result = new ShippingResult(
                success: true,
                trackingNumber: $response['tracking_number'],
                shipmentId: $response['shipment_id'],
                label: $response['label_base64'] ?? null,
                metadata: [
                    'service_type' => $response['service_type'],
                    'rate' => $response['rate'] ?? 0,
                ]
            );

            Log::info('FedEx shipment created', ['shipment_id' => $response['shipment_id']]);

            return [
                'success' => true,
                'result' => $result,
            ];

        } catch (\Exception $e) {
            Log::error('FedEx shipment creation failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }

    public function trackShipment(string $trackingNumber): array
    {
        try {
            $response = $this->client->trackShipment($trackingNumber);

            return [
                'success' => true,
                'tracking_number' => $trackingNumber,
                'status' => $response['status'],
                'events' => $response['events'] ?? [],
                'estimated_delivery' => $response['estimated_delivery'] ?? null,
            ];

        } catch (\Exception $e) {
            Log::error('FedEx tracking failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }

    public function cancelShipment(string $shipmentId): bool
    {
        try {
            $this->client->cancelShipment($shipmentId);
            Log::info('FedEx shipment cancelled', ['shipment_id' => $shipmentId]);
            return true;
        } catch (\Exception $e) {
            Log::error('FedEx cancellation failed', ['error' => $e->getMessage()]);
            return false;
        }
    }

    public function getServiceTypes(): array
    {
        return [
            'ground' => 'FedEx Ground',
            'express' => 'FedEx Express',
            'overnight' => 'FedEx Overnight',
            'international' => 'FedEx International',
        ];
    }

    private function getFromAddress(): array
    {
        return [
            'street' => config('shipping.from_address.street'),
            'city' => config('shipping.from_address.city'),
            'state' => config('shipping.from_address.state'),
            'zip' => config('shipping.from_address.zip'),
            'country' => config('shipping.from_address.country'),
        ];
    }

    private function getToAddress(Order $order): array
    {
        return [
            'street' => $order->shipping_address,
            'city' => $order->shipping_city,
            'state' => $order->shipping_state,
            'zip' => $order->shipping_zip,
            'country' => $order->shipping_country,
        ];
    }

    private function getDimensions(Order $order): array
    {
        // Calculate dimensions from order items
        return [
            'length' => $order->dimension_length ?? 10,
            'width' => $order->dimension_width ?? 10,
            'height' => $order->dimension_height ?? 10,
        ];
    }

    private function mapServiceType(string $fedExService): string
    {
        return match($fedExService) {
            'FEDEX_GROUND' => 'ground',
            'FEDEX_2_DAY' => 'express',
            'FEDEX_OVERNIGHT' => 'overnight',
            'FEDEX_INTERNATIONAL' => 'international',
            default => 'ground',
        };
    }

    private function getServiceCode(string $serviceType): string
    {
        return match($serviceType) {
            'ground' => 'FEDEX_GROUND',
            'express' => 'FEDEX_2_DAY',
            'overnight' => 'FEDEX_OVERNIGHT',
            'international' => 'FEDEX_INTERNATIONAL',
            default => 'FEDEX_GROUND',
        };
    }
}

Step 4: Create the UPS Adapter

// app/Services/Shipping/UPSAdapter.php
namespace App\Services\Shipping;

use App\Contracts\ShippingInterface;
use App\DTO\ShippingRate;
use App\DTO\ShippingResult;
use App\Models\Order;
use App\Models\Shipment;
use Illuminate\Support\Facades\Log;

class UPSAdapter implements ShippingInterface
{
    private UPSClient $client;

    public function __construct(string $accessKey, string $userId, string $password)
    {
        $this->client = new UPSClient([
            'access_key' => $accessKey,
            'user_id' => $userId,
            'password' => $password,
        ]);
    }

    public function getRates(Order $order): array
    {
        try {
            $response = $this->client->getShippingRates([
                'from_zip' => config('shipping.from_address.zip'),
                'to_zip' => $order->shipping_zip,
                'to_country' => $order->shipping_country,
                'weight' => $order->total_weight,
                'dimensions' => $this->getDimensions($order),
            ]);

            $rates = [];
            foreach ($response as $rate) {
                $rates[] = new ShippingRate(
                    service: $this->mapServiceType($rate['service']),
                    price: (float)$rate['cost'],
                    currency: 'USD',
                    delivery_time: $rate['delivery_days'] . ' days',
                    metadata: ['service_code' => $rate['service']]
                );
            }

            return $rates;

        } catch (\Exception $e) {
            Log::error('UPS rate fetch failed', ['error' => $e->getMessage()]);
            return [];
        }
    }

    public function createShipment(Shipment $shipment): array
    {
        try {
            $response = $this->client->processShipment([
                'from_address' => $this->getFromAddress(),
                'to_address' => $this->getToAddress($shipment->order),
                'package' => [
                    'weight' => $shipment->order->total_weight,
                    'dimensions' => $this->getDimensions($shipment->order),
                ],
                'service' => $this->getServiceCode($shipment->service_type),
                'reference' => 'Order-' . $shipment->order->id,
            ]);

            $result = new ShippingResult(
                success: true,
                trackingNumber: $response['tracking_number'],
                shipmentId: $response['shipment_id'],
                label: $response['label_base64'] ?? null,
                metadata: [
                    'service_type' => $response['service_type'],
                    'rate' => $response['rate'] ?? 0,
                ]
            );

            Log::info('UPS shipment created', ['shipment_id' => $response['shipment_id']]);

            return [
                'success' => true,
                'result' => $result,
            ];

        } catch (\Exception $e) {
            Log::error('UPS shipment creation failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }

    public function trackShipment(string $trackingNumber): array
    {
        try {
            $response = $this->client->track($trackingNumber);

            return [
                'success' => true,
                'tracking_number' => $trackingNumber,
                'status' => $response['status'],
                'events' => $response['activity'] ?? [],
                'estimated_delivery' => $response['estimated_delivery'] ?? null,
            ];

        } catch (\Exception $e) {
            Log::error('UPS tracking failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }

    public function cancelShipment(string $shipmentId): bool
    {
        try {
            $this->client->cancelShipment($shipmentId);
            Log::info('UPS shipment cancelled', ['shipment_id' => $shipmentId]);
            return true;
        } catch (\Exception $e) {
            Log::error('UPS cancellation failed', ['error' => $e->getMessage()]);
            return false;
        }
    }

    public function getServiceTypes(): array
    {
        return [
            'ground' => 'UPS Ground',
            'express' => 'UPS Express',
            'overnight' => 'UPS Overnight',
            'international' => 'UPS International',
        ];
    }

    // Helper methods (similar to FedEx adapter)
    private function getFromAddress(): array { /* ... */ }
    private function getToAddress(Order $order): array { /* ... */ }
    private function getDimensions(Order $order): array { /* ... */ }
    private function mapServiceType(string $upsService): string { /* ... */ }
    private function getServiceCode(string $serviceType): string { /* ... */ }
}

Step 5: The Shipping Service

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

use App\Contracts\ShippingInterface;
use App\Models\Order;
use App\Models\Shipment;

class ShippingService
{
    public function __construct(
        private readonly ShippingInterface $shipping
    ) {}

    public function getRates(Order $order): array
    {
        return $this->shipping->getRates($order);
    }

    public function createShipment(Shipment $shipment): array
    {
        return $this->shipping->createShipment($shipment);
    }

    public function trackShipment(string $trackingNumber): array
    {
        return $this->shipping->trackShipment($trackingNumber);
    }

    public function cancelShipment(string $shipmentId): bool
    {
        return $this->shipping->cancelShipment($shipmentId);
    }

    public function getServiceTypes(): array
    {
        return $this->shipping->getServiceTypes();
    }
}

Step 6: Service Provider with Factory

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

use App\Contracts\ShippingInterface;
use App\Services\Shipping\FedExAdapter;
use App\Services\Shipping\UPSAdapter;
use App\Services\Shipping\USPSAdapter;
use App\Services\Shipping\DHLAdapter;
use App\Services\ShippingService;
use Illuminate\Support\ServiceProvider;

class ShippingServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        $this->app->singleton(ShippingService::class, function ($app) {
            $provider = config('shipping.default_provider', 'fedex');
            $adapter = $this->createAdapter($provider);

            return new ShippingService($adapter);
        });
    }

    private function createAdapter(string $provider): ShippingInterface
    {
        return match($provider) {
            'fedex' => new FedExAdapter(
                config('shipping.fedex.api_key'),
                config('shipping.fedex.password'),
                config('shipping.fedex.account_number')
            ),
            'ups' => new UPSAdapter(
                config('shipping.ups.access_key'),
                config('shipping.ups.user_id'),
                config('shipping.ups.password')
            ),
            'usps' => new USPSAdapter(
                config('shipping.usps.user_id'),
                config('shipping.usps.password')
            ),
            'dhl' => new DHLAdapter(
                config('shipping.dhl.api_key'),
                config('shipping.dhl.api_secret')
            ),
            default => throw new \Exception("Unsupported shipping provider: {$provider}"),
        };
    }
}

Step 7: Controller

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

use App\Models\Order;
use App\Services\ShippingService;
use Illuminate\Http\Request;

class OrderController extends Controller
{
    public function __construct(
        private readonly ShippingService $shipping
    ) {}

    public function getRates(Order $order)
    {
        $rates = $this->shipping->getRates($order);

        return response()->json([
            'rates' => array_map(fn($rate) => [
                'service' => $rate->service,
                'price' => $rate->price,
                'currency' => $rate->currency,
                'delivery_time' => $rate->delivery_time,
            ], $rates),
        ]);
    }

    public function createShipment(Request $request, Order $order)
    {
        $shipment = new Shipment();
        $shipment->order_id = $order->id;
        $shipment->service_type = $request->input('service');
        $shipment->save();

        $result = $this->shipping->createShipment($shipment);

        if (!$result['success']) {
            return response()->json(['error' => $result['error']], 400);
        }

        return response()->json([
            'success' => true,
            'tracking_number' => $result['result']->trackingNumber,
            'shipment_id' => $result['result']->shipmentId,
        ]);
    }
}

Why This Design Works

Decoupling: Order controller doesn't know about shipping providers.
Consistent Interface: All adapters implement ShippingInterface.
Flexibility: Switch providers by changing configuration.
Testability: Mock ShippingInterface for testing.
Open/Closed: Add a new provider by creating a new adapter.
Encapsulation: Provider-specific complexity is hidden in adapters.

10. SOLID Principles Mapping

O - Open/Closed Principle (OCP)

Add new shipping providers by creating new adapters, without modifying existing code.

// Adding a new provider
class DHLAdapter implements ShippingInterface { /* ... */ }

// No changes to ShippingService or controllers

S - Single Responsibility Principle (SRP)

Each adapter handles one provider.
The service orchestrates shipping operations.
The controller handles HTTP requests.

L - Liskov Substitution Principle (LSP)

All adapters are substitutable for ShippingInterface.

function ship(ShippingInterface $shipping, Order $order)
{
    // Works with any adapter
    return $shipping->createShipment($shipment);
}

D - Dependency Inversion Principle (DIP)

ShippingService depends on ShippingInterface (abstraction), not on concrete adapters.

I - Interface Segregation Principle (ISP)

The interface is focused on shipping operations only.

11. Trade-offs

Benefits

Decoupling: Application code is decoupled from third-party APIs.
Consistency: All adapters implement the same interface.
Testability: Mock the adapter for testing.
Flexibility: Swap providers without changing application code.
Encapsulation: API complexity is hidden.
Open/Closed: Add new providers without modifying existing code.

Costs

More Classes: You need an adapter for each API.
Boilerplate: You need to write the adapter logic.
Indirection: More layers between your code and the API.
Learning Curve: Developers need to understand the pattern.

When Is Complexity Justified?

Use the Adapter Pattern when:

You integrate with 3+ third-party APIs.
The API might change.
You need to be able to swap providers.
You want to test your code without real API calls.

Avoid the Adapter Pattern when:

You only use one API and it won't change.
The API is simple and stable.
The overhead of the pattern isn't justified.

12. When NOT To Use It

3 Green Flags (USE ADAPTER)

Multiple APIs: You integrate with 3+ similar services.
API Changes: The third-party API is likely to change.
Testing Needs: You need to mock the API for testing.

3 Red Flags (AVOID ADAPTER)

Single API: You only use one third-party API.
Stable API: The API is stable and won't change.
Simple API: The API is simple and easy to use.

13. Common Mistakes

1. Over-Engineering

// BAD: Adapter for a simple API
class SimpleApiAdapter implements SimpleInterface
{
    public function getData()
    {
        return new SimpleApi()->fetch();
    }
}

// The API is already simple and won't change

2. Not Handling Adapter Exceptions

// BAD: No exception handling
public function charge($amount)
{
    return $this->api->charge($amount);
}

// GOOD: Exception handling
public function charge($amount)
{
    try {
        return $this->api->charge($amount);
    } catch (ApiException $e) {
        throw new AdapterException($e->getMessage());
    }
}

3. Changing the Target Interface

// BAD: Changing the interface
interface PaymentInterface
{
    public function charge($amount, $currency, $paymentMethodId, $metadata); // New parameter!
}

Fix: Keep the interface stable. Use optional parameters or a new interface.

4. Adapter Doing Too Much

// BAD: Adapter handles caching, logging, and API calls
class Adapter
{
    public function getData()
    {
        $this->cache->get();
        $this->logger->log();
        return $this->api->fetch();
    }
}

Fix: Keep the adapter focused on translation. Use decorators for caching and logging.

5. Not Using Dependency Injection

// BAD: Adapter creates its own dependencies
class StripeAdapter
{
    public function __construct()
    {
        $this->stripe = new StripeClient(env('STRIPE_SECRET'));
    }
}

// GOOD: Dependency injection
class StripeAdapter
{
    public function __construct(StripeClient $stripe)
    {
        $this->stripe = $stripe;
    }
}

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is the Adapter Pattern?
A: A structural pattern that allows objects with incompatible interfaces to work together by acting as a bridge between them.
Q: When would you use the Adapter Pattern?
A: When integrating with third-party APIs, when you need to swap implementations, or when you want to decouple your application from external services.
Q: How does the Adapter Pattern differ from the Facade Pattern?
A: Adapter converts one interface to another. Facade provides a simplified interface to a complex system.
Q: How does Laravel use the Adapter Pattern?
A: In Filesystem adapters, Cache adapters, Queue adapters, Mail adapters, and Session adapters.
Q: What are the benefits of the Adapter Pattern?
A: Decoupling, consistency, testability, flexibility, and encapsulation.

Senior/Architect

Q: Explain the difference between Class Adapter and Object Adapter.
A: Class Adapter uses inheritance (extends the adaptee). Object Adapter uses composition (holds a reference to the adaptee). PHP uses Object Adapter.
Q: How do you handle different exceptions from different adapters?
A: Catch API-specific exceptions and throw a common exception type or return a consistent result array.
Q: How do you test adapters?
A: Use dependency injection to mock the third-party client. Test the adapter's translation logic.
Q: How do you handle adapter configuration?
A: Pass configuration to the adapter's constructor or use a factory to create adapters.
Q: What's the relationship between the Adapter Pattern and the Dependency Inversion Principle?
A: Adapter implements DIP by allowing high-level modules to depend on abstractions (the target interface) rather than concrete third-party APIs.

15. Interactive Practice Challenge

The Requirement

You're building a Notification Delivery System that integrates with multiple notification providers. The current code is tightly coupled to one provider.

The Code (POOR DESIGN)

namespace App\Services;

use Twilio\Rest\Client;
use Illuminate\Support\Facades\Log;

class NotificationService
{
    private Client $twilio;

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

    public function sendSms(string $to, string $message): array
    {
        try {
            $response = $this->twilio->messages->create(
                $to,
                [
                    'from' => config('services.twilio.from'),
                    'body' => $message,
                ]
            );

            Log::info('SMS sent via Twilio', ['to' => $to, 'sid' => $response->sid]);

            return [
                'success' => true,
                'provider' => 'twilio',
                'message_id' => $response->sid,
                'status' => $response->status,
            ];
        } catch (\Exception $e) {
            Log::error('SMS failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }

    public function sendEmail(string $to, string $subject, string $body): array
    {
        // Using SendGrid (another third-party)
        $sendgrid = new \SendGrid(config('services.sendgrid.api_key'));

        $email = new \SendGrid\Mail\Mail();
        $email->setFrom(config('mail.from.address'), config('mail.from.name'));
        $email->setSubject($subject);
        $email->addTo($to);
        $email->addContent('text/plain', $body);

        try {
            $response = $sendgrid->send($email);

            Log::info('Email sent via SendGrid', ['to' => $to]);

            return [
                'success' => $response->statusCode() === 202,
                'provider' => 'sendgrid',
                'status_code' => $response->statusCode(),
            ];
        } catch (\Exception $e) {
            Log::error('Email failed', ['error' => $e->getMessage()]);
            return [
                'success' => false,
                'error' => $e->getMessage(),
            ];
        }
    }
}

The Challenges

The code is tightly coupled to Twilio and SendGrid. New requirements are coming:

"We need to support SMS via Vonage."
"We need to support SMS via Amazon SNS."
"We need to support email via Mailgun."
"We need to support email via Amazon SES."
"We need to support push notifications via Firebase."
"We need to support Slack notifications."

Your Task

Refactor this system using the Adapter Pattern. Specifically:

Define target interfaces for SMS and Email.
Create adapters for each provider:
- TwilioSmsAdapter
- VonageSmsAdapter
- AmazonSnsSmsAdapter
- SendGridEmailAdapter
- MailgunEmailAdapter
- AmazonSesEmailAdapter
Create a factory to create the appropriate adapters based on configuration.
Refactor NotificationService to use the adapters.
Add support for push notifications and Slack.

Questions to Consider

How do you handle different authentication methods?
How do you handle different response formats?
How do you handle rate limiting differences?
How do you handle retry logic?
How do you test the system with different providers?

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

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: The Adapter Pattern bridges incompatible interfaces, allowing your application to work with third-party APIs through a consistent interface.
One-sentence intuition: Wrap a third-party API in an adapter that speaks your application's language.
One-sentence decision rule: If you're integrating with a third-party API that could change or be replaced, use an adapter to decouple your application.

17. Related Concepts

SOLID Principles

Open/Closed: Add new adapters without modifying existing code.
Dependency Inversion: Depend on the target interface, not concrete adapters.
Single Responsibility: Each adapter handles one provider.
Liskov Substitution: All adapters are substitutable.
Interface Segregation: The target interface is focused.

Design Patterns

Facade: Simplifies a complex system.
Decorator: Wraps an object to add behavior.
Proxy: Controls access to an object.
Bridge: Separates abstraction from implementation.
Strategy: Encapsulates interchangeable algorithms.

Laravel Internals

Filesystem: Uses adapters for local, S3, FTP.
Cache: Uses adapters for Redis, Memcached, File.
Queue: Uses adapters for Database, Redis, SQS.
Mail: Uses adapters for SMTP, Mailgun, Postmark.
Session: Uses adapters for Database, File, Redis.
Notification: Uses channels (which are similar to adapters).

Enterprise Patterns

Adapter: The pattern itself.
Wrapper: A common name for adapters.
Driver: In Laravel, drivers are often adapters.
Connector: Another name for adapters in some contexts.

Final Thoughts

Third-party APIs are the lifeblood of modern applications. They handle payments, send notifications, store files, and provide analytics. But they're also unpredictable. They change. They have different interfaces. They have inconsistent error handling.

The Adapter Pattern is your shield against API chaos. It wraps third-party APIs in a consistent interface, decoupling your application from external services.

Every time you integrate with a third-party API, start with an adapter. Your future self will thank you when the API changes or when you need to switch providers.

Remember: Adapters protect your application from the outside world.

Github: Adapter Pattern Practice Labs

The Builder Pattern: Stop Writing 10-Parameter Constructors

Anas Hussain — Sun, 20 Sep 2026 08:39:52 +0000

1. Hook & Problem Statement

You're building a Laravel application. You need to send a report email with attachments, custom headers, CC and BCC recipients, and a custom template.

Your constructor looks like this:

$email = new ReportEmail(
    $recipient,
    $subject,
    $body,
    $attachments,
    $ccRecipients,
    $bccRecipients,
    $headers,
    $template,
    $priority,
    $replyTo,
    $fromAddress,
    $fromName,
    $scheduledAt
);

12 parameters! You can't remember the order. You constantly pass null for optional parameters. When you add a new feature, you have to update every place that creates this object.

This is Constructor Hell. It's a symptom of a deeper problem: objects that have too many configuration options.

Enter the Builder Pattern.

The Builder Pattern is designed to handle the construction of complex objects step by step. It allows you to create objects with many optional parameters without sacrificing readability or maintainability.

2. Why This Pattern Exists

The Software Engineering Problem It Solves

The Builder Pattern solves the problem of constructing complex objects with many optional parameters. It separates the construction of a complex object from its representation, allowing the same construction process to create different representations.

The Pain That Existed Before

Before the Builder Pattern (or in codebases that don't use it), developers faced:

Telescoping Constructor Anti-Pattern: Constructors with 10+ parameters that are impossible to remember.
Optional Parameters Overload: Passing null for every optional parameter.
Invalid State: Objects could be created in an invalid state because parameters were missing.
Immutability Challenges: Complex objects that needed to be immutable but had many configuration options.
Duplicate Code: The same complex object creation code repeated across multiple places.

Why Large Applications Need It

As applications grow, objects become more complex:

Domain Objects: Entities with many attributes and behaviors.
DTOs: Data Transfer Objects with many fields.
Configuration Objects: Objects that hold many configuration options.
Request Objects: Objects that encapsulate complex request data.

The Builder Pattern provides:

Readability: Method chaining makes the code self-documenting.
Flexibility: You can add new configuration options without breaking existing code.
Immutability: Builders can create immutable objects.
Validation: Builders can validate the object state before building.

3. Real World Analogy

Ordering a Custom Pizza

You walk into a pizzeria. You want a custom pizza.

The Bad Way (Telescoping Constructor):
You shout your order in one breath:
"Large, thin crust, tomato sauce, mozzarella, pepperoni, mushrooms, olives, extra cheese, well-done, and can I have it delivered to my friend's house?"

The pizza maker is confused. They forget your order. You realize you don't even remember all the options.

The Builder Way:
The pizzeria has a Pizza Builder:

Step 1: Choose the size (Large).
Step 2: Choose the crust (Thin).
Step 3: Add sauce (Tomato).
Step 4: Add cheese (Mozzarella, Extra cheese).
Step 5: Add toppings (Pepperoni, Mushrooms, Olives).
Step 6: Choose cooking instructions (Well-done).
Step 7: Choose delivery address (Friend's house).

Each step is clear and focused. You can skip optional steps. The builder ensures you end up with a valid pizza.

Analogy Mapping:

Pizza: The complex object being built.
Pizza Builder: The Builder object.
Size, Crust, Sauce: Required configuration.
Toppings: Optional configuration.
Cooking Instructions: Optional configuration.
Delivery Address: Optional configuration.
Final Build(): The method that creates the pizza.

4. The Pain (Bad Design)

Let's look at a typical "Constructor Hell" scenario.

namespace App\Services\Email;

class ReportEmail
{
    private string $to;
    private string $subject;
    private string $body;
    private array $attachments;
    private array $cc;
    private array $bcc;
    private array $headers;
    private string $template;
    private string $priority;
    private string $replyTo;
    private string $fromAddress;
    private string $fromName;
    private ?DateTime $scheduledAt;

    public function __construct(
        string $to,
        string $subject,
        string $body,
        array $attachments = [],
        array $cc = [],
        array $bcc = [],
        array $headers = [],
        string $template = 'default',
        string $priority = 'normal',
        string $replyTo = '',
        string $fromAddress = '',
        string $fromName = '',
        ?DateTime $scheduledAt = null
    ) {
        $this->to = $to;
        $this->subject = $subject;
        $this->body = $body;
        $this->attachments = $attachments;
        $this->cc = $cc;
        $this->bcc = $bcc;
        $this->headers = $headers;
        $this->template = $template;
        $this->priority = $priority;
        $this->replyTo = $replyTo;
        $this->fromAddress = $fromAddress;
        $this->fromName = $fromName;
        $this->scheduledAt = $scheduledAt;
    }

    // Getters and methods...
}

// Usage: Constructor Hell
class ReportService
{
    public function sendReport(Report $report, User $user): void
    {
        $email = new ReportEmail(
            $user->email,
            "Monthly Report - {$report->month}",
            $this->generateReportContent($report),
            [
                ['path' => storage_path("reports/{$report->id}.pdf"), 'name' => 'report.pdf'],
                ['path' => storage_path("reports/{$report->id}.xlsx"), 'name' => 'data.xlsx'],
            ],
            ['manager@company.com', 'team@company.com'],
            [],
            ['X-Report-ID' => $report->id, 'X-Priority' => 'high'],
            'report_template',
            'high',
            'no-reply@company.com',
            config('mail.from.address'),
            config('mail.from.name'),
            null
        );

        Mail::send($email);
    }
}

Why This Is Terrible

Telescoping Constructor: 13 parameters! You can't remember the order.
Passing null and Empty Arrays: Many parameters are optional but still need to be passed.
No Type Safety: You can't enforce which parameters are required vs optional.
Difficult to Read: The constructor call is a wall of text.
Difficult to Maintain: Adding a new parameter requires updating every usage.
No Validation: The object might be in an invalid state.
Duplicate Code: The same complex creation logic is repeated.

Why Developers Write Code Like This

They start with a simple constructor.
Features are added over time.
They don't recognize the Builder Pattern opportunity.
They think "just one more parameter won't hurt."
They're not designing for maintainability.

5. Solution Overview

The Builder Pattern is a creational design pattern that separates the construction of a complex object from its representation. It allows the same construction process to create different representations.

Core Idea

Instead of using a telescoping constructor, you use a builder to construct the object step by step. The builder provides methods for setting each parameter, and a build() method that creates the final object.

Main Participants

Product: The complex object being built (e.g., ReportEmail).
Builder Interface: Defines the steps for building the product.
Concrete Builder: Implements the builder interface with specific methods.
Director (Optional): Orchestrates the building process for common configurations.
Client: Creates the builder, sets parameters, and calls build().

How Objects Collaborate

Client → Builder → setParameterA() → setParameterB() → build() → Product

The client creates a builder, sets parameters using fluent methods, and then calls build() to get the product.

Mental Model

Think of a recipe in a cookbook.

Builder: The cookbook with step-by-step instructions.
Product: The finished dish.
Methods: Each step in the recipe (add flour, add eggs, bake).
Client: The cook following the recipe.

You don't need to know how the dish is made. You just follow the steps. The builder handles the details.

Benefits

Readability: Method chaining makes the code self-documenting.
Flexibility: You can add new parameters without breaking existing code.
Validation: The builder can validate the object state before building.
Immutability: The builder can create immutable objects.
Reusability: The same builder can be used to create different configurations.

Trade-offs

More Classes: You need a builder class and a product class.
Complexity: More moving parts.
Boilerplate: You need to write builder methods for each parameter.

6. UML Diagram

Laravel Builder Pattern Mermaid Diagram

Diagram Explanation

ReportEmail is the product (complex object).
ReportEmailBuilder handles the step-by-step construction.
The builder has fluent methods for setting parameters.
The build() method creates the product.
The validate() method ensures the object is in a valid state.

7. Vanilla PHP Example

Let's refactor the report email using the Builder Pattern.

Before Refactoring (Constructor Hell)

(The terrible code shown above)

After Refactoring

Step 1: Define the Product (Simplified)

class ReportEmail
{
    private string $to;
    private string $subject;
    private string $body;
    private array $attachments;
    private array $cc;
    private array $bcc;
    private array $headers;
    private string $template;
    private string $priority;
    private string $replyTo;
    private string $fromAddress;
    private string $fromName;
    private ?DateTime $scheduledAt;

    // Private constructor - only the builder can create instances
    private function __construct(ReportEmailBuilder $builder)
    {
        $this->to = $builder->getTo();
        $this->subject = $builder->getSubject();
        $this->body = $builder->getBody();
        $this->attachments = $builder->getAttachments();
        $this->cc = $builder->getCc();
        $this->bcc = $builder->getBcc();
        $this->headers = $builder->getHeaders();
        $this->template = $builder->getTemplate();
        $this->priority = $builder->getPriority();
        $this->replyTo = $builder->getReplyTo();
        $this->fromAddress = $builder->getFromAddress();
        $this->fromName = $builder->getFromName();
        $this->scheduledAt = $builder->getScheduledAt();
    }

    // Factory method to create the builder
    public static function builder(): ReportEmailBuilder
    {
        return new ReportEmailBuilder();
    }

    public function send(): void
    {
        // Send the email
        Mail::send($this->template, ['body' => $this->body], function ($message) {
            $message->to($this->to)
                    ->subject($this->subject)
                    ->from($this->fromAddress, $this->fromName);

            if ($this->replyTo) {
                $message->replyTo($this->replyTo);
            }

            foreach ($this->cc as $cc) {
                $message->cc($cc);
            }

            foreach ($this->bcc as $bcc) {
                $message->bcc($bcc);
            }

            foreach ($this->attachments as $attachment) {
                $message->attach($attachment['path'], ['as' => $attachment['name']]);
            }

            foreach ($this->headers as $key => $value) {
                $message->setHeader($key, $value);
            }
        });
    }
}

Step 2: Define the Builder

class ReportEmailBuilder
{
    private string $to;
    private string $subject;
    private string $body;
    private array $attachments = [];
    private array $cc = [];
    private array $bcc = [];
    private array $headers = [];
    private string $template = 'default';
    private string $priority = 'normal';
    private string $replyTo = '';
    private string $fromAddress;
    private string $fromName;
    private ?DateTime $scheduledAt = null;

    public function __construct()
    {
        $this->fromAddress = config('mail.from.address');
        $this->fromName = config('mail.from.name');
    }

    // Required parameters
    public function to(string $to): self
    {
        $this->to = $to;
        return $this;
    }

    public function subject(string $subject): self
    {
        $this->subject = $subject;
        return $this;
    }

    public function body(string $body): self
    {
        $this->body = $body;
        return $this;
    }

    // Optional parameters
    public function attachment(string $path, string $name = null): self
    {
        $this->attachments[] = [
            'path' => $path,
            'name' => $name ?? basename($path),
        ];
        return $this;
    }

    public function attachments(array $attachments): self
    {
        foreach ($attachments as $attachment) {
            if (is_string($attachment)) {
                $this->attachment($attachment);
            } else {
                $this->attachment($attachment['path'], $attachment['name'] ?? null);
            }
        }
        return $this;
    }

    public function cc(string|array $cc): self
    {
        $this->cc = array_merge($this->cc, (array) $cc);
        return $this;
    }

    public function bcc(string|array $bcc): self
    {
        $this->bcc = array_merge($this->bcc, (array) $bcc);
        return $this;
    }

    public function header(string $key, string $value): self
    {
        $this->headers[$key] = $value;
        return $this;
    }

    public function headers(array $headers): self
    {
        $this->headers = array_merge($this->headers, $headers);
        return $this;
    }

    public function template(string $template): self
    {
        $this->template = $template;
        return $this;
    }

    public function priority(string $priority): self
    {
        $this->priority = $priority;
        return $this;
    }

    public function replyTo(string $replyTo): self
    {
        $this->replyTo = $replyTo;
        return $this;
    }

    public function from(string $address, string $name = ''): self
    {
        $this->fromAddress = $address;
        $this->fromName = $name;
        return $this;
    }

    public function scheduledAt(DateTime $dateTime): self
    {
        $this->scheduledAt = $dateTime;
        return $this;
    }

    // Build method
    public function build(): ReportEmail
    {
        $this->validate();
        return new ReportEmail($this);
    }

    // Validation
    private function validate(): void
    {
        if (empty($this->to)) {
            throw new \InvalidArgumentException('Recipient email is required');
        }

        if (empty($this->subject)) {
            throw new \InvalidArgumentException('Subject is required');
        }

        if (empty($this->body)) {
            throw new \InvalidArgumentException('Body is required');
        }

        if (!filter_var($this->to, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException('Invalid recipient email');
        }

        if ($this->fromAddress && !filter_var($this->fromAddress, FILTER_VALIDATE_EMAIL)) {
            throw new \InvalidArgumentException('Invalid from address');
        }
    }

    // Getters for the product
    public function getTo(): string { return $this->to; }
    public function getSubject(): string { return $this->subject; }
    public function getBody(): string { return $this->body; }
    public function getAttachments(): array { return $this->attachments; }
    public function getCc(): array { return $this->cc; }
    public function getBcc(): array { return $this->bcc; }
    public function getHeaders(): array { return $this->headers; }
    public function getTemplate(): string { return $this->template; }
    public function getPriority(): string { return $this->priority; }
    public function getReplyTo(): string { return $this->replyTo; }
    public function getFromAddress(): string { return $this->fromAddress; }
    public function getFromName(): string { return $this->fromName; }
    public function getScheduledAt(): ?DateTime { return $this->scheduledAt; }
}

Step 3: Usage

class ReportService
{
    public function sendReport(Report $report, User $user): void
    {
        $email = ReportEmail::builder()
            ->to($user->email)
            ->subject("Monthly Report - {$report->month}")
            ->body($this->generateReportContent($report))
            ->attachment(storage_path("reports/{$report->id}.pdf"), 'report.pdf')
            ->attachment(storage_path("reports/{$report->id}.xlsx"), 'data.xlsx')
            ->cc(['manager@company.com', 'team@company.com'])
            ->header('X-Report-ID', $report->id)
            ->header('X-Priority', 'high')
            ->template('report_template')
            ->priority('high')
            ->replyTo('no-reply@company.com')
            ->from(config('mail.from.address'), config('mail.from.name'))
            ->build();

        $email->send();
    }
}

What We Improved

Readability: The builder chain reads like a sentence.
Flexibility: You can skip optional parameters.
Validation: The builder validates the state before building.
Maintainability: Adding a new parameter only requires adding a builder method.
Immutability: The product is immutable (private constructor).
Self-Documenting: The builder methods describe what they do.

8. Laravel Internal Example

Laravel uses the Builder Pattern extensively. Let's look at some key examples.

Query Builder

Laravel's Query Builder is a perfect example of the Builder Pattern.

// Laravel's Query Builder
$users = DB::table('users')
    ->select('name', 'email')
    ->where('active', true)
    ->where('age', '>', 18)
    ->orderBy('name')
    ->limit(10)
    ->get();

Why This Is Elegant:

Fluent Interface: Method chaining makes the query read like English.
Step-by-Step Construction: Each method adds to the query.
Flexibility: You can add conditions conditionally.
Immutability: Each method returns a new query instance.

Eloquent Query Builder

Eloquent also uses the Builder Pattern.

// Eloquent Query Builder
$users = User::where('active', true)
    ->whereHas('posts', function ($query) {
        $query->where('published', true);
    })
    ->with('profile')
    ->orderBy('created_at', 'desc')
    ->paginate(15);

HTTP Request Builder

Laravel's HTTP client uses the Builder Pattern.

// HTTP Client Builder
$response = Http::withHeaders([
    'X-Custom-Header' => 'value',
    'Authorization' => 'Bearer token',
])
->withOptions([
    'timeout' => 30,
    'verify' => false,
])
->withCookies(['session' => 'value'], 'example.com')
->asJson()
->post('https://api.example.com/data', [
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);

Mail Builder

Laravel's Mail system uses a builder-like approach.

// Mail Builder
Mail::to($user)
    ->cc($manager)
    ->bcc($team)
    ->subject('Welcome!')
    ->view('emails.welcome')
    ->attach(storage_path('files/welcome.pdf'))
    ->send();

Validator Builder

Laravel's validation uses a builder for rules.

// Validator Builder
$validator = Validator::make($data, [
    'name' => 'required|string|max:255',
    'email' => 'required|email|unique:users',
    'age' => 'integer|min:18',
]);

Database Schema Builder

Laravel's Schema Builder is another great example.

// Schema Builder
Schema::create('users', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->string('email')->unique();
    $table->timestamp('email_verified_at')->nullable();
    $table->string('password');
    $table->rememberToken();
    $table->timestamps();
});

Why This Is Elegant:

Fluent Interface: Each method adds to the schema.
Self-Documenting: The method names describe the column types.
Flexibility: You can add columns conditionally.
Validation: The builder ensures the schema is valid.

9. Real Laravel Application Example

Let's build a Report Builder for generating complex business reports with multiple sections, filters, formats, and delivery options.

Scenario

Your application needs to generate reports with:

Multiple data sources
Filters (date range, categories, statuses)
Formatting options (chart type, column visibility, sorting)
Delivery options (email, download, webhook)
Scheduling options (immediate, scheduled, recurring)

Implementation

Step 1: Define the Product

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

class Report
{
    private string $title;
    private array $sections;
    private array $filters;
    private array $formatting;
    private array $dataSources;
    private array $deliveryOptions;
    private ?string $schedule = null;
    private ?string $timezone = null;
    private ?string $emailSubject = null;
    private ?string $emailBody = null;
    private array $recipients = [];

    // Private constructor
    private function __construct(ReportBuilder $builder)
    {
        $this->title = $builder->getTitle();
        $this->sections = $builder->getSections();
        $this->filters = $builder->getFilters();
        $this->formatting = $builder->getFormatting();
        $this->dataSources = $builder->getDataSources();
        $this->deliveryOptions = $builder->getDeliveryOptions();
        $this->schedule = $builder->getSchedule();
        $this->timezone = $builder->getTimezone();
        $this->emailSubject = $builder->getEmailSubject();
        $this->emailBody = $builder->getEmailBody();
        $this->recipients = $builder->getRecipients();
    }

    public static function builder(): ReportBuilder
    {
        return new ReportBuilder();
    }

    public function generate(): string
    {
        // Generate the report
        $content = '';
        foreach ($this->sections as $section) {
            $content .= $this->generateSection($section);
        }
        return $content;
    }

    private function generateSection(array $section): string
    {
        // Generate each section
        return '';
    }

    // Getters
    public function getTitle(): string { return $this->title; }
    public function getSections(): array { return $this->sections; }
    public function getFilters(): array { return $this->filters; }
    public function getFormatting(): array { return $this->formatting; }
    public function getDataSources(): array { return $this->dataSources; }
    public function getDeliveryOptions(): array { return $this->deliveryOptions; }
    public function getSchedule(): ?string { return $this->schedule; }
    public function getTimezone(): ?string { return $this->timezone; }
    public function getEmailSubject(): ?string { return $this->emailSubject; }
    public function getEmailBody(): ?string { return $this->emailBody; }
    public function getRecipients(): array { return $this->recipients; }
}

Step 2: Define the Builder

// app/Builders/ReportBuilder.php
namespace App\Builders;

use App\DTO\Report;

class ReportBuilder
{
    private string $title;
    private array $sections = [];
    private array $filters = [];
    private array $formatting = [];
    private array $dataSources = [];
    private array $deliveryOptions = [];
    private ?string $schedule = null;
    private ?string $timezone = null;
    private ?string $emailSubject = null;
    private ?string $emailBody = null;
    private array $recipients = [];

    // Required
    public function title(string $title): self
    {
        $this->title = $title;
        return $this;
    }

    // Sections
    public function section(string $name, array $data, string $type = 'table'): self
    {
        $this->sections[] = [
            'name' => $name,
            'data' => $data,
            'type' => $type,
        ];
        return $this;
    }

    public function chartSection(string $name, array $data, string $chartType = 'bar'): self
    {
        $this->sections[] = [
            'name' => $name,
            'data' => $data,
            'type' => 'chart',
            'chart_type' => $chartType,
        ];
        return $this;
    }

    public function summarySection(string $name, array $metrics): self
    {
        $this->sections[] = [
            'name' => $name,
            'data' => $metrics,
            'type' => 'summary',
        ];
        return $this;
    }

    // Data Sources
    public function dataSource(string $name, string $connection, string $query): self
    {
        $this->dataSources[] = [
            'name' => $name,
            'connection' => $connection,
            'query' => $query,
        ];
        return $this;
    }

    public function dataSources(array $sources): self
    {
        foreach ($sources as $source) {
            $this->dataSource(
                $source['name'],
                $source['connection'],
                $source['query']
            );
        }
        return $this;
    }

    // Filters
    public function filter(string $key, $value, string $operator = '='): self
    {
        $this->filters[] = [
            'key' => $key,
            'value' => $value,
            'operator' => $operator,
        ];
        return $this;
    }

    public function dateRange(string $key, string $start, string $end): self
    {
        $this->filters[] = [
            'key' => $key,
            'type' => 'date_range',
            'start' => $start,
            'end' => $end,
        ];
        return $this;
    }

    public function filters(array $filters): self
    {
        foreach ($filters as $filter) {
            if (isset($filter['type']) && $filter['type'] === 'date_range') {
                $this->dateRange($filter['key'], $filter['start'], $filter['end']);
            } else {
                $this->filter($filter['key'], $filter['value'], $filter['operator'] ?? '=');
            }
        }
        return $this;
    }

    // Formatting
    public function formatting(array $options): self
    {
        $this->formatting = array_merge($this->formatting, $options);
        return $this;
    }

    public function sortBy(string $column, string $direction = 'asc'): self
    {
        $this->formatting['sort_by'] = $column;
        $this->formatting['sort_direction'] = $direction;
        return $this;
    }

    public function columns(array $columns): self
    {
        $this->formatting['columns'] = $columns;
        return $this;
    }

    public function withTotals(): self
    {
        $this->formatting['show_totals'] = true;
        return $this;
    }

    public function withPercentages(): self
    {
        $this->formatting['show_percentages'] = true;
        return $this;
    }

    // Delivery Options
    public function delivery(string $method, array $options = []): self
    {
        $this->deliveryOptions[] = [
            'method' => $method,
            'options' => $options,
        ];
        return $this;
    }

    public function emailDelivery(array $recipients, string $subject = null, string $body = null): self
    {
        $this->recipients = array_merge($this->recipients, $recipients);
        $this->emailSubject = $subject;
        $this->emailBody = $body;

        return $this->delivery('email', [
            'recipients' => $recipients,
            'subject' => $subject,
            'body' => $body,
        ]);
    }

    public function downloadDelivery(string $format = 'pdf'): self
    {
        return $this->delivery('download', ['format' => $format]);
    }

    public function webhookDelivery(string $url, array $headers = []): self
    {
        return $this->delivery('webhook', [
            'url' => $url,
            'headers' => $headers,
        ]);
    }

    // Scheduling
    public function schedule(string $cron, string $timezone = 'UTC'): self
    {
        $this->schedule = $cron;
        $this->timezone = $timezone;
        return $this;
    }

    public function immediate(): self
    {
        $this->schedule = 'immediate';
        return $this;
    }

    // Build method
    public function build(): Report
    {
        $this->validate();
        return new Report($this);
    }

    // Validation
    private function validate(): void
    {
        if (empty($this->title)) {
            throw new \InvalidArgumentException('Report title is required');
        }

        if (empty($this->sections)) {
            throw new \InvalidArgumentException('Report must have at least one section');
        }

        if (empty($this->dataSources)) {
            throw new \InvalidArgumentException('Report must have at least one data source');
        }
    }

    // Getters for the product
    public function getTitle(): string { return $this->title; }
    public function getSections(): array { return $this->sections; }
    public function getFilters(): array { return $this->filters; }
    public function getFormatting(): array { return $this->formatting; }
    public function getDataSources(): array { return $this->dataSources; }
    public function getDeliveryOptions(): array { return $this->deliveryOptions; }
    public function getSchedule(): ?string { return $this->schedule; }
    public function getTimezone(): ?string { return $this->timezone; }
    public function getEmailSubject(): ?string { return $this->emailSubject; }
    public function getEmailBody(): ?string { return $this->emailBody; }
    public function getRecipients(): array { return $this->recipients; }
}

Step 3: Usage

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

use App\DTO\Report;
use App\Builders\ReportBuilder;
use Illuminate\Http\Request;

class ReportController extends Controller
{
    public function generate(Request $request)
    {
        $report = Report::builder()
            ->title('Monthly Sales Report')

            // Add sections
            ->section('Overview', [
                ['total_sales' => '$125,430', 'orders' => 1245, 'avg_order' => '$100.75'],
            ], 'summary')

            ->chartSection('Sales Trends', [
                ['month' => 'Jan', 'sales' => 12000],
                ['month' => 'Feb', 'sales' => 15000],
                ['month' => 'Mar', 'sales' => 18000],
            ], 'line')

            ->section('Top Products', [
                ['product' => 'Widget A', 'sales' => 450, 'revenue' => 22500],
                ['product' => 'Widget B', 'sales' => 320, 'revenue' => 16000],
                ['product' => 'Widget C', 'sales' => 280, 'revenue' => 14000],
            ], 'table')

            // Add data sources
            ->dataSource('orders', 'mysql', 'SELECT * FROM orders WHERE status = "completed"')
            ->dataSource('customers', 'mysql', 'SELECT * FROM customers WHERE active = 1')

            // Add filters
            ->dateRange('created_at', '2024-01-01', '2024-12-31')
            ->filter('status', 'completed')
            ->filter('payment_method', ['stripe', 'paypal'], 'in')

            // Formatting
            ->columns(['product', 'sales', 'revenue'])
            ->sortBy('sales', 'desc')
            ->withTotals()
            ->withPercentages()

            // Delivery
            ->emailDelivery(
                ['ceo@company.com', 'finance@company.com'],
                'Monthly Sales Report',
                'Please find the monthly sales report attached.'
            )
            ->downloadDelivery('pdf')
            ->webhookDelivery('https://webhook.company.com/reports', ['X-API-Key' => 'secret'])

            // Schedule
            ->schedule('0 9 1 * *', 'America/New_York')

            ->build();

        // Generate and deliver the report
        $content = $report->generate();

        // Send via email, download, webhook based on delivery options
        $this->deliverReport($report, $content);

        return response()->json(['success' => true]);
    }
}

Why This Design Works

Readability: The builder chain clearly shows what the report contains.
Flexibility: You can add sections, filters, and delivery options as needed.
Validation: The builder validates required fields.
Extensibility: Add new features by adding builder methods.
Immutability: The report is immutable after construction.

10. SOLID Principles Mapping

S - Single Responsibility Principle (SRP)

The builder is responsible for construction.
The product is responsible for its behavior.
The client is responsible for configuring the builder.

O - Open/Closed Principle (OCP)

Add new configuration options by adding builder methods, without modifying existing code.

// Adding a new method doesn't affect existing code
public function withWatermark(string $text): self
{
    $this->formatting['watermark'] = $text;
    return $this;
}

L - Liskov Substitution Principle (LSP)

The builder creates products that are substitutable for the product interface.

D - Dependency Inversion Principle (DIP)

The client depends on the builder abstraction, not on concrete product construction.

I - Interface Segregation Principle (ISP)

The builder has focused methods for each configuration option, not a bloated interface.

11. Trade-offs

Benefits

Readability: The code reads like English.
Flexibility: You can skip optional parameters.
Validation: The builder can validate the object state.
Immutability: The builder can create immutable objects.
Maintainability: Adding new parameters is easy.
Reusability: The same builder can create different configurations.

Costs

More Classes: You need a builder class and a product class.
Complexity: More moving parts.
Boilerplate: You need to write builder methods for each parameter.
Learning Curve: Developers need to understand the pattern.

When Is Complexity Justified?

Use the Builder Pattern when:

Objects have 4+ parameters, especially with many optional ones.
The construction process has multiple steps.
You need to create immutable objects.
The object configuration is complex.
You want to validate the object state before creation.

Avoid the Builder Pattern when:

Objects have 1-3 simple parameters.
The construction process is trivial.
The overhead of the pattern isn't justified.

12. When NOT To Use It

3 Green Flags (USE BUILDER)

Telescoping Constructor: Your constructor has 4+ parameters.
Multiple Optional Parameters: Many parameters are optional.
Complex Construction: The object requires multiple steps to build.

3 Red Flags (AVOID BUILDER)

Simple Objects: 1-3 simple parameters.

// GOOD: Simple constructor
$user = new User($name, $email);

// BAD: Builder for simple object
$user = User::builder()->name('John')->email('john@example.com')->build();

Single Configuration: The object has one fixed configuration.
Performance Critical: The overhead of the builder matters.

13. Common Mistakes

1. Over-Engineering Simple Objects

// BAD: Builder for a simple object
class UserBuilder
{
    private string $name;
    private string $email;

    public function name(string $name): self { $this->name = $name; return $this; }
    public function email(string $email): self { $this->email = $email; return $this; }
    public function build(): User { return new User($this->name, $this->email); }
}

// GOOD: Simple constructor
$user = new User('John Doe', 'john@example.com');

2. Mutable Builder

// BAD: Mutable builder
class Builder
{
    private array $data;

    public function set(string $key, $value): self
    {
        $this->data[$key] = $value;
        return $this;
    }

    public function build(): Product
    {
        // Reuses the same data
        return new Product($this->data);
    }
}

// Problem: Builder state can be modified after use

Fix: Make the builder immutable or reset state after build().

3. Missing Validation

// BAD: No validation
class Builder
{
    public function build(): Product
    {
        return new Product($this->data); // Could be invalid!
    }
}

// GOOD: Validation before building
public function build(): Product
{
    $this->validate();
    return new Product($this->data);
}

4. Builder Interface Pollution

// BAD: Builder with too many methods
interface Builder
{
    public function setA($value): self;
    public function setB($value): self;
    public function setC($value): self;
    // 20 more methods...
    public function build(): Product;
}

Fix: Keep the builder focused on the product being built.

5. Not Handling Required Parameters

// BAD: Required parameters are optional in the builder
class Builder
{
    public function build(): Product
    {
        // Missing required parameters cause runtime errors
        return new Product($this->data);
    }
}

// GOOD: Required parameters are enforced in the constructor
class Builder
{
    public function __construct(string $required)
    {
        $this->required = $required;
    }
}

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is the Builder Pattern?
A: A creational design pattern that separates the construction of a complex object from its representation, allowing the same construction process to create different representations.
Q: When would you use the Builder Pattern?
A: When objects have 4+ parameters, especially with many optional ones, and when the construction process is complex.
Q: How does the Builder Pattern differ from the Factory Pattern?
A: Factory Method creates objects in one step, while Builder creates objects step by step. Builder is better for complex objects with many parameters.
Q: What are the benefits of the Builder Pattern?
A: Readability, flexibility, validation, immutability, and maintainability.
Q: How does Laravel use the Builder Pattern?
A: In Query Builder, Eloquent, HTTP Client, Mail, Schema Builder, and Validation.

Senior/Architect

Q: Explain the difference between a Builder and a Factory.
A: A factory creates objects in one go. A builder constructs objects step by step and is used when the object has many configuration options.
Q: How do you handle required vs optional parameters in a builder?
A: Required parameters can be passed in the builder's constructor. Optional parameters have fluent methods.
Q: What's the relationship between the Builder Pattern and immutability?
A: Builders are ideal for creating immutable objects because they separate construction from representation.
Q: How do you test a class that uses a builder?
A: You can test the builder's validation and the product's behavior separately. Use dependency injection for the builder.
Q: How do you handle builder reuse?
A: You can create multiple products from the same builder by resetting the builder state or using different builder instances.

15. Interactive Practice Challenge

The Requirement

You're building a Notification Builder for a SaaS application. Notifications can be complex with many options.

The Code (POOR DESIGN)

namespace App\Services;

class Notification
{
    private string $type;
    private string $title;
    private string $body;
    private string $recipient;
    private ?string $actionUrl = null;
    private ?string $actionText = null;
    private array $actions = [];
    private string $priority = 'normal';
    private array $attachments = [];
    private ?string $imageUrl = null;
    private ?string $sender = null;
    private array $metadata = [];
    private bool $urgent = false;
    private ?string $scheduleAt = null;
    private string $channel = 'email';

    public function __construct(
        string $type,
        string $title,
        string $body,
        string $recipient,
        ?string $actionUrl = null,
        ?string $actionText = null,
        array $actions = [],
        string $priority = 'normal',
        array $attachments = [],
        ?string $imageUrl = null,
        ?string $sender = null,
        array $metadata = [],
        bool $urgent = false,
        ?string $scheduleAt = null,
        string $channel = 'email'
    ) {
        $this->type = $type;
        $this->title = $title;
        $this->body = $body;
        $this->recipient = $recipient;
        $this->actionUrl = $actionUrl;
        $this->actionText = $actionText;
        $this->actions = $actions;
        $this->priority = $priority;
        $this->attachments = $attachments;
        $this->imageUrl = $imageUrl;
        $this->sender = $sender;
        $this->metadata = $metadata;
        $this->urgent = $urgent;
        $this->scheduleAt = $scheduleAt;
        $this->channel = $channel;
    }
}

class NotificationService
{
    public function sendNotification(array $data): void
    {
        $notification = new Notification(
            $data['type'],
            $data['title'],
            $data['body'],
            $data['recipient'],
            $data['action_url'] ?? null,
            $data['action_text'] ?? null,
            $data['actions'] ?? [],
            $data['priority'] ?? 'normal',
            $data['attachments'] ?? [],
            $data['image_url'] ?? null,
            $data['sender'] ?? null,
            $data['metadata'] ?? [],
            $data['urgent'] ?? false,
            $data['schedule_at'] ?? null,
            $data['channel'] ?? 'email'
        );

        // Send notification...
    }
}

The Challenges

The constructor has 15 parameters! The code is unmaintainable.

New requirements are coming:

"We need to support push notifications with custom sounds."
"We need to support in-app notifications with badges."
"We need to support email notifications with custom templates."
"We need to add notification categories for filtering."
"We need to support notification threading/replies."

Your Task

Refactor this system using the Builder Pattern. Specifically:

Create a NotificationBuilder class with fluent methods for each parameter.
Create a Notification class with a private constructor that takes the builder.
Implement validation in the builder for required fields.
Add support for new features (push sounds, badges, templates, categories) using builder methods.
Refactor the NotificationService to use the builder.
Implement a fluent API that reads like English.

Questions to Consider

How do you handle required vs optional parameters?
How do you handle different notification types (email, push, in-app)?
How do you handle validation for each type?
How do you make the builder extensible for new features?
How do you test the builder and the notification separately?

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

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: The Builder Pattern constructs complex objects step by step, separating construction from representation.
One-sentence intuition: Instead of a giant constructor, use a builder with fluent methods to set each parameter, then call build().
One-sentence decision rule: If your constructor has more than 4 parameters, especially with many optional ones, use a builder.

17. Related Concepts

SOLID Principles

Single Responsibility: The builder handles construction, the product handles behavior.
Open/Closed: Add new builder methods without changing existing code.
Liskov Substitution: Products are substitutable.
Dependency Inversion: Clients depend on the builder abstraction.

Design Patterns

Factory Method: Creates objects in one step.
Abstract Factory: Creates families of objects.
Prototype: Creates objects by cloning.
Singleton: Ensures only one instance.
Fluent Interface: The builder is a fluent interface.

Laravel Internals

Query Builder: DB::table()->select()->where()->get()
Eloquent: User::where()->with()->orderBy()->get()
HTTP Client: Http::withHeaders()->withOptions()->post()
Mail: Mail::to()->cc()->bcc()->send()
Schema Builder: Schema::create()->table()->id()->timestamps()

Enterprise Patterns

Builder: The pattern itself.
DTO: Often built with builders.
Value Object: Immutable objects built with builders.
Domain Object: Complex domain entities built with builders.

Final Thoughts

The new keyword is powerful, but with great power comes great responsibility. Using new everywhere creates tight coupling, scattered logic, and makes your code hard to test and extend.

The Builder Pattern gives you a better way. It centralizes object creation, decouples your code, and makes it easy to add new types.

Every time you find yourself writing new in your controller, ask yourself: "Should this be moved to a factory?"

Remember: Stop creating objects with new. Start using factories. Your future self will thank you.

Github: Builder Pattern Practice Labs

Tired of "new" Everywhere? Learn Factory Method with Laravel

Anas Hussain — Thu, 17 Sep 2026 03:45:40 +0000

1. Hook & Problem Statement

You're building a Laravel application. You need to create a payment processor. So you write:

$processor = new StripePaymentProcessor(
    config('services.stripe.secret'),
    config('services.stripe.webhook_secret')
);

Then you need to create a different processor for another part of the system:

$processor = new PayPalPaymentProcessor(
    config('services.paypal.client_id'),
    config('services.paypal.secret')
);

Then the requirements change. The payment processor now needs a logger, a metrics service, and a cache manager. You find yourself updating every new statement across 15 different controllers and services.

Then the business says: "We want to support a new payment gateway." You search your codebase for new StripePaymentProcessor and new PayPalPaymentProcessor, and you find them scattered across 20 files. You copy-paste the pattern for the new gateway, but you miss a few places. The system breaks in production.

This is the problem with new everywhere.

new creates tight coupling. It spreads object creation logic across your codebase. It makes change expensive and risky.

The Factory Method pattern solves this problem. It centralizes object creation, making your code more flexible, testable, and maintainable.

2. Why This Pattern Exists

The Software Engineering Problem It Solves

The Factory Method pattern solves the problem of centralizing and encapsulating object creation. Instead of using new to create objects directly, you delegate creation to a dedicated method or class.

The Pain That Existed Before

Before the Factory Method pattern (or in codebases that don't use it), developers faced:

Scattered Creation Logic: new statements were everywhere, making changes difficult.
Tight Coupling: The client code was tightly coupled to concrete classes.
Complex Construction: Creating some objects required multiple steps, configuration, and dependencies.
Duplicate Code: The same creation logic was repeated across multiple places.
Difficult Testing: You couldn't easily substitute mock objects because the creation was hardcoded.
Violation of OCP: Adding a new type required modifying the client code.

Why Large Applications Need It

As applications grow, the complexity of object creation grows:

Objects need more configuration.
Objects have complex dependencies.
Objects might need to be created based on runtime conditions.
You might need to switch between different implementations.

The Factory Method pattern provides:

Centralized Creation: One place to change creation logic.
Loose Coupling: Client code depends on abstractions, not concretions.
Open/Closed Compliance: Add new types without changing existing code.
Testability: Inject mock factories for testing.

3. Real World Analogy

The Coffee Shop

Imagine a coffee shop that serves different types of coffee: Espresso, Latte, Cappuccino, and Americano.

The Bad Way:
Every barista (client code) knows how to make every type of coffee. When a customer orders, the barista uses if-else to determine which coffee to make:

if ($order === 'espresso') {
    // 10 steps to make espresso
} elseif ($order === 'latte') {
    // 15 steps to make latte
}

When the coffee recipe changes, every barista must be retrained. When a new coffee is added, every barista must learn it.

The Factory Method Way:
The coffee shop has a Coffee Machine (the factory). The barista (client) tells the machine what coffee they want, and the machine makes it.

Coffee Machine: The Factory.
MakeEspresso(), MakeLatte(): Factory methods.
Barista: The client code.
Customer: The end user.

When a coffee recipe changes, only the machine needs to be updated. When a new coffee is added, you just add a new method to the machine.

Analogy Mapping:

Coffee Shop: The application.
Coffee Machine: The Factory class.
Barista: The client code.
MakeCoffee(): The factory method.
Espresso, Latte: Concrete products.
Coffee: The product interface.

4. The Pain (Bad Design)

Let's look at a typical Laravel controller with scattered new statements.

namespace App\Http\Controllers;

use App\Models\Order;
use App\Services\Payment\StripePaymentProcessor;
use App\Services\Payment\PayPalPaymentProcessor;
use App\Services\Payment\BankTransferProcessor;
use App\Services\Payment\CryptoPaymentProcessor;
use App\Services\Notification\EmailService;
use App\Services\Notification\SmsService;
use App\Services\Logger\FileLogger;
use App\Services\Logger\DatabaseLogger;
use App\Services\Cache\RedisCache;
use App\Services\Cache\FileCache;
use Illuminate\Http\Request;

class PaymentController extends Controller
{
    public function process(Request $request, Order $order)
    {
        // Payment processing
        if ($order->payment_method === 'stripe') {
            $processor = new StripePaymentProcessor(
                config('services.stripe.secret'),
                config('services.stripe.webhook_secret'),
                new FileLogger(storage_path('logs/payments.log')),
                new RedisCache(config('cache.redis'))
            );
            $result = $processor->charge($order);
        } elseif ($order->payment_method === 'paypal') {
            $processor = new PayPalPaymentProcessor(
                config('services.paypal.client_id'),
                config('services.paypal.secret'),
                new FileLogger(storage_path('logs/payments.log')),
                new RedisCache(config('cache.redis'))
            );
            $result = $processor->charge($order);
        } elseif ($order->payment_method === 'bank_transfer') {
            $processor = new BankTransferProcessor(
                new DatabaseLogger(),
                new FileCache(storage_path('cache'))
            );
            $result = $processor->charge($order);
        } else {
            $processor = new CryptoPaymentProcessor(
                new DatabaseLogger(),
                new RedisCache(config('cache.redis'))
            );
            $result = $processor->charge($order);
        }

        // Notifications
        if ($order->user->notification_preference === 'email') {
            $notifier = new EmailService(
                config('mail.from.address'),
                new FileLogger(storage_path('logs/notifications.log'))
            );
        } else {
            $notifier = new SmsService(
                config('services.twilio.sid'),
                config('services.twilio.token'),
                new FileLogger(storage_path('logs/notifications.log'))
            );
        }
        $notifier->send($order->user, "Payment processed for order #{$order->id}");

        return response()->json(['success' => true, 'result' => $result]);
    }
}

Why This Is Terrible

Scattered new Statements: The controller knows how to create every possible payment processor and notification service.
Tight Coupling: The controller is coupled to concrete classes (StripePaymentProcessor, FileLogger, RedisCache).
Duplicated Logic: The logger and cache creation logic is repeated for each payment processor.
Difficult Testing: Testing this controller requires creating real instances of all dependencies.
Violates SRP: The controller handles HTTP requests AND object creation.
Violates OCP: Adding a new payment processor requires modifying this controller.
Configuration Hardcoding: Configuration values are directly accessed and passed to constructors.
Complex Construction: Creating a payment processor is complex and error-prone.

Why Developers Write Code Like This

It's the "quick and dirty" approach.
They think "it's just one object creation."
They don't recognize the pattern opportunity.
They haven't learned to abstract object creation.
The code "works" so they don't refactor.

5. Solution Overview

The Factory Method pattern is a creational design pattern that defines an interface for creating an object, but lets subclasses or implementing classes decide which class to instantiate.

Core Idea

Instead of using new directly, you delegate object creation to a method (or class). The factory method handles the creation logic, and the client code uses the factory to get objects.

Main Participants

Product Interface: Defines the type of object the factory creates.
Concrete Products: The actual objects created by the factory.
Factory Interface: Defines the method for creating products.
Concrete Factories: Implement the factory method to create specific products.
Client: Uses the factory to get products without knowing the details.

How Objects Collaborate

Client → Factory Interface → Concrete Factory → Concrete Product
                                ↓
                            Product Interface

The client asks the factory for a product. The factory creates and returns the appropriate product. The client uses the product through the product interface.

Mental Model

Think of a rental car company.

Rental Company: The Factory (creates cars).
RentCar(): The factory method.
Car: The product interface.
Sedan, SUV, Truck: Concrete products.
Customer: The client.

When a customer requests a car, the rental company decides which type to provide based on availability and customer needs. The customer doesn't need to know how the car is manufactured or prepared.

Benefits

Decoupling: Client code is decoupled from concrete classes.
Centralization: Creation logic is in one place.
Flexibility: Easy to add new product types.
Testability: Mock the factory for testing.
Readability: The factory name describes what it creates.

Trade-offs

More Classes: You need factory classes or methods.
Complexity: More indirection and abstraction.
Over-engineering: Not every object creation needs a factory.

6. UML Diagram

Laravel Factory Pattern Mermaid Diagram

Diagram Explanation

PaymentProcessor is the product interface.
Concrete products implement the interface.
PaymentProcessorFactory has methods to create processors.
PaymentController depends on the factory, not concrete processors.
The factory decides which concrete product to create.

7. Vanilla PHP Example

Let's refactor the payment controller using the Factory Method pattern.

Before Refactoring

(The terrible code shown above)

After Refactoring

Step 1: Define the Product Interface

interface PaymentProcessor
{
    public function charge(Order $order): array;
    public function refund(Order $order, float $amount): array;
    public function cancel(Order $order): bool;
}

Step 2: Implement Concrete Products

// StripeProcessor.php
class StripeProcessor implements PaymentProcessor
{
    private \Stripe\StripeClient $stripe;
    private LoggerInterface $logger;
    private CacheInterface $cache;

    public function __construct(
        string $secretKey,
        string $webhookSecret,
        LoggerInterface $logger,
        CacheInterface $cache
    ) {
        $this->stripe = new \Stripe\StripeClient($secretKey);
        $this->logger = $logger;
        $this->cache = $cache;
    }

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

            $this->logger->info('Stripe charge successful', ['order' => $order->id]);

            return [
                'success' => true,
                'transaction_id' => $intent->id,
                'status' => $intent->status,
            ];
        } catch (\Exception $e) {
            $this->logger->error('Stripe charge failed', ['error' => $e->getMessage()]);
            throw $e;
        }
    }

    public function refund(Order $order, float $amount): array
    {
        // Stripe refund implementation
        return ['success' => true];
    }

    public function cancel(Order $order): bool
    {
        // Stripe cancellation implementation
        return true;
    }
}

// PayPalProcessor.php
class PayPalProcessor implements PaymentProcessor
{
    private \PayPal\Rest\ApiContext $apiContext;
    private LoggerInterface $logger;
    private CacheInterface $cache;

    public function __construct(
        string $clientId,
        string $clientSecret,
        LoggerInterface $logger,
        CacheInterface $cache
    ) {
        $this->apiContext = new \PayPal\Rest\ApiContext(
            new \PayPal\Auth\OAuthTokenCredential($clientId, $clientSecret)
        );
        $this->logger = $logger;
        $this->cache = $cache;
    }

    public function charge(Order $order): array
    {
        // PayPal implementation
        $this->logger->info('PayPal charge successful', ['order' => $order->id]);
        return ['success' => true];
    }

    public function refund(Order $order, float $amount): array
    {
        return ['success' => true];
    }

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

// BankTransferProcessor.php
class BankTransferProcessor implements PaymentProcessor
{
    private LoggerInterface $logger;
    private CacheInterface $cache;

    public function __construct(LoggerInterface $logger, CacheInterface $cache)
    {
        $this->logger = $logger;
        $this->cache = $cache;
    }

    public function charge(Order $order): array
    {
        $reference = 'ORD-' . $order->id . '-' . time();

        $this->logger->info('Bank transfer initiated', ['order' => $order->id]);

        return [
            'success' => true,
            'reference' => $reference,
            'instructions' => 'Please transfer the amount to the provided bank account.',
        ];
    }

    public function refund(Order $order, float $amount): array
    {
        return ['success' => true, 'message' => 'Manual refund required'];
    }

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

Step 3: Define the Factory

// PaymentProcessorFactory.php
class PaymentProcessorFactory
{
    private LoggerInterface $logger;
    private CacheInterface $cache;
    private array $config;

    public function __construct(LoggerInterface $logger, CacheInterface $cache, array $config = [])
    {
        $this->logger = $logger;
        $this->cache = $cache;
        $this->config = $config;
    }

    // Factory method for Stripe
    public function createStripe(): PaymentProcessor
    {
        return new StripeProcessor(
            $this->config['stripe']['secret'] ?? env('STRIPE_SECRET'),
            $this->config['stripe']['webhook_secret'] ?? env('STRIPE_WEBHOOK_SECRET'),
            $this->logger,
            $this->cache
        );
    }

    // Factory method for PayPal
    public function createPayPal(): PaymentProcessor
    {
        return new PayPalProcessor(
            $this->config['paypal']['client_id'] ?? env('PAYPAL_CLIENT_ID'),
            $this->config['paypal']['secret'] ?? env('PAYPAL_SECRET'),
            $this->logger,
            $this->cache
        );
    }

    // Factory method for Bank Transfer
    public function createBankTransfer(): PaymentProcessor
    {
        return new BankTransferProcessor(
            $this->logger,
            $this->cache
        );
    }

    // Generic factory method with type selection
    public function create(string $type): PaymentProcessor
    {
        return match($type) {
            'stripe' => $this->createStripe(),
            'paypal' => $this->createPayPal(),
            'bank_transfer' => $this->createBankTransfer(),
            default => throw new \Exception("Unsupported payment type: {$type}"),
        };
    }
}

Step 4: The Refactored Controller

// PaymentController.php
class PaymentController
{
    private PaymentProcessorFactory $factory;
    private NotificationFactory $notificationFactory;

    public function __construct(
        PaymentProcessorFactory $factory,
        NotificationFactory $notificationFactory
    ) {
        $this->factory = $factory;
        $this->notificationFactory = $notificationFactory;
    }

    public function process(Request $request, Order $order)
    {
        // Create the appropriate processor using the factory
        $processor = $this->factory->create($order->payment_method);

        // Process the payment
        $result = $processor->charge($order);

        // Create and send notification
        $notifier = $this->notificationFactory->create(
            $order->user->notification_preference
        );
        $notifier->send($order->user, "Payment processed for order #{$order->id}");

        return response()->json(['success' => true, 'result' => $result]);
    }
}

What We Improved

Centralized Creation: All payment processor creation is in the factory.
Decoupling: The controller doesn't know about concrete processor classes.
Easy Extension: Add a new processor by adding a factory method.
Configurable: The factory handles configuration.
Testable: Mock the factory for testing.
No new in Controller: The controller is clean and focused.

8. Laravel Internal Example

Laravel uses the Factory Method pattern extensively. Let's look at some key examples.

Database Connection Factory

Laravel's Database system uses a factory to create database connections.

// Illuminate\Database\ConnectionFactory
class ConnectionFactory
{
    public function make(array $config, $name = null): Connection
    {
        $config = $this->parseConfig($config, $name);

        if (isset($config['read'])) {
            return $this->createReadWriteConnection($config);
        }

        return $this->createSingleConnection($config);
    }

    protected function createSingleConnection(array $config): Connection
    {
        $driver = $config['driver'];

        return match($driver) {
            'mysql' => new MySqlConnection($config),
            'pgsql' => new PostgresConnection($config),
            'sqlite' => new SQLiteConnection($config),
            'sqlsrv' => new SqlServerConnection($config),
            default => throw new \Exception("Unsupported driver: {$driver}"),
        };
    }
}

Why This Is Elegant:

The factory centralizes connection creation.
Adding a new database driver requires a new case in the factory.
The client code (DB::connection()) doesn't know about connection creation.

Queue Manager

Laravel's Queue Manager uses factories to create queue drivers.

// Illuminate\Queue\QueueManager
class QueueManager
{
    public function connection(?string $name = null): Queue
    {
        $name = $name ?: $this->getDefaultDriver();

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

    protected function resolve(string $name): Queue
    {
        $config = $this->getConfig($name);
        $driver = $config['driver'];

        return match($driver) {
            'sync' => new SyncQueue(),
            'database' => new DatabaseQueue($config),
            'redis' => new RedisQueue($config),
            'sqs' => new SqsQueue($config),
            default => throw new \Exception("Unsupported driver: {$driver}"),
        };
    }
}

Why This Is Elegant:

The manager acts as a factory for queue connections.
Adding a new driver is a configuration change.
The client code uses Queue::push() without knowing the driver.

Filesystem Manager

Laravel's Filesystem uses factories for drivers.

// Illuminate\Filesystem\FilesystemManager
class FilesystemManager
{
    public function disk(?string $name = null): Filesystem
    {
        $name = $name ?: $this->getDefaultDriver();

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

    protected function resolve(string $name): Filesystem
    {
        $config = $this->getConfig($name);
        $driver = $config['driver'];

        return match($driver) {
            'local' => new LocalFilesystem($config),
            's3' => new S3Filesystem($config),
            default => throw new \Exception("Unsupported driver: {$driver}"),
        };
    }
}

Mail Manager

Laravel's Mail system uses the Factory Method pattern.

// Illuminate\Mail\MailManager
class MailManager
{
    public function mailer(?string $name = null): Mailer
    {
        $name = $name ?: $this->getDefaultDriver();

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

    protected function resolve(string $name): Mailer
    {
        $config = $this->getConfig($name);
        $driver = $config['driver'];

        return match($driver) {
            'smtp' => $this->createSmtpDriver($config),
            'sendmail' => $this->createSendmailDriver($config),
            'mailgun' => $this->createMailgunDriver($config),
            'postmark' => $this->createPostmarkDriver($config),
            default => throw new \Exception("Unsupported mailer: {$driver}"),
        };
    }
}

Eloquent Model Factories

Laravel's model factories are a form of the Factory Method pattern.

// Database\Factories\UserFactory
class UserFactory extends Factory
{
    public function definition(): array
    {
        return [
            'name' => fake()->name(),
            'email' => fake()->unique()->safeEmail(),
            'email_verified_at' => now(),
            'password' => 'password',
        ];
    }

    public function admin(): self
    {
        return $this->state(fn () => ['is_admin' => true]);
    }

    public function create(array $attributes = []): User
    {
        return parent::create($attributes);
    }
}

Eloquent Model Creation

Even Eloquent models themselves use factory methods:

// In your models
$user = User::create([
    'name' => 'John Doe',
    'email' => 'john@example.com',
]);

$user = User::make([
    'name' => 'Jane Doe',
    'email' => 'jane@example.com',
]);

Why This Is Elegant:

Static factory methods make object creation intuitive.
The create() method handles both instantiation and persistence.
The make() method handles instantiation without persistence.

9. Real Laravel Application Example

Let's build a Document Export System with multiple export formats using the Factory Method pattern.

Scenario

Your application needs to export documents to different formats: PDF, Excel, CSV, JSON, and XML. Each format has different requirements, configurations, and dependencies.

Implementation

Step 1: Define the Product Interface

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

use App\Models\Document;

interface ExporterInterface
{
    public function export(Document $document, array $options = []): ExportResult;
    public function getMimeType(): string;
    public function getFileExtension(): string;
}

Step 2: Create 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 Concrete Products

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

use App\Contracts\ExporterInterface;
use App\DTO\ExportResult;
use App\Models\Document;
use Dompdf\Dompdf;

class PdfExporter implements ExporterInterface
{
    private Dompdf $dompdf;
    private string $paperSize;
    private string $orientation;

    public function __construct(string $paperSize = 'A4', string $orientation = 'portrait')
    {
        $this->dompdf = new Dompdf();
        $this->paperSize = $paperSize;
        $this->orientation = $orientation;
    }

    public function export(Document $document, array $options = []): ExportResult
    {
        $html = view('exports.pdf_template', [
            'document' => $document,
            'options' => $options,
        ])->render();

        $this->dompdf->loadHtml($html);
        $this->dompdf->setPaper($this->paperSize, $this->orientation);
        $this->dompdf->render();

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

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

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

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

    private function generateFilename(Document $document): string
    {
        return 'document_' . $document->id . '_' . date('Ymd_His');
    }
}

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

use App\Contracts\ExporterInterface;
use App\DTO\ExportResult;
use App\Models\Document;
use PhpOffice\PhpSpreadsheet\Spreadsheet;
use PhpOffice\PhpSpreadsheet\Writer\Xlsx;

class ExcelExporter implements ExporterInterface
{
    private bool $includeHeaders;

    public function __construct(bool $includeHeaders = true)
    {
        $this->includeHeaders = $includeHeaders;
    }

    public function export(Document $document, array $options = []): ExportResult
    {
        $spreadsheet = new Spreadsheet();
        $sheet = $spreadsheet->getActiveSheet();

        $data = $document->getData();
        $headers = $document->getHeaders();

        if ($this->includeHeaders) {
            $col = 'A';
            foreach ($headers as $header) {
                $sheet->setCellValue($col . '1', $header);
                $col++;
            }
        }

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

        $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($document) . '.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';
    }

    private function generateFilename(Document $document): string
    {
        return 'document_' . $document->id . '_' . date('Ymd_His');
    }
}

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

use App\Contracts\ExporterInterface;
use App\DTO\ExportResult;
use App\Models\Document;

class CsvExporter implements ExporterInterface
{
    private string $delimiter;
    private bool $includeHeaders;

    public function __construct(string $delimiter = ',', bool $includeHeaders = true)
    {
        $this->delimiter = $delimiter;
        $this->includeHeaders = $includeHeaders;
    }

    public function export(Document $document, array $options = []): ExportResult
    {
        $output = fopen('php://temp', 'r+');

        $data = $document->getData();
        $headers = $document->getHeaders();

        if ($this->includeHeaders) {
            fputcsv($output, $headers, $this->delimiter);
        }

        foreach ($data as $row) {
            fputcsv($output, $row, $this->delimiter);
        }

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

        return new ExportResult(
            content: $content,
            filename: $this->generateFilename($document) . '.csv',
            mimeType: $this->getMimeType(),
            size: strlen($content)
        );
    }

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

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

    private function generateFilename(Document $document): string
    {
        return 'document_' . $document->id . '_' . date('Ymd_His');
    }
}

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

use App\Contracts\ExporterInterface;
use App\DTO\ExportResult;
use App\Models\Document;

class JsonExporter implements ExporterInterface
{
    public function export(Document $document, array $options = []): ExportResult
    {
        $data = [
            'id' => $document->id,
            'title' => $document->title,
            'data' => $document->getData(),
            'metadata' => $document->getMetadata(),
            'exported_at' => now()->toIso8601String(),
        ];

        $content = json_encode($data, JSON_PRETTY_PRINT);

        return new ExportResult(
            content: $content,
            filename: $this->generateFilename($document) . '.json',
            mimeType: $this->getMimeType(),
            size: strlen($content)
        );
    }

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

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

    private function generateFilename(Document $document): string
    {
        return 'document_' . $document->id . '_' . date('Ymd_His');
    }
}

Step 4: Define the Factory

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

use App\Contracts\ExporterInterface;

class ExporterFactory
{
    private array $config;

    public function __construct(array $config = [])
    {
        $this->config = $config;
    }

    // Factory method with type selection
    public function create(string $format): ExporterInterface
    {
        return match(strtolower($format)) {
            'pdf' => $this->createPdf(),
            'excel', 'xlsx' => $this->createExcel(),
            'csv' => $this->createCsv(),
            'json' => $this->createJson(),
            'xml' => $this->createXml(),
            default => throw new \Exception("Unsupported export format: {$format}"),
        };
    }

    // Individual factory methods for each format
    public function createPdf(): ExporterInterface
    {
        return new PdfExporter(
            $this->config['pdf']['paper_size'] ?? 'A4',
            $this->config['pdf']['orientation'] ?? 'portrait'
        );
    }

    public function createExcel(): ExporterInterface
    {
        return new ExcelExporter(
            $this->config['excel']['include_headers'] ?? true
        );
    }

    public function createCsv(): ExporterInterface
    {
        return new CsvExporter(
            $this->config['csv']['delimiter'] ?? ',',
            $this->config['csv']['include_headers'] ?? true
        );
    }

    public function createJson(): ExporterInterface
    {
        return new JsonExporter();
    }

    public function createXml(): ExporterInterface
    {
        // Add XML exporter
        return new XmlExporter();
    }

    public function createFromDocument(Document $document): ExporterInterface
    {
        return $this->create($document->getDefaultFormat());
    }
}

Step 5: Service Provider

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

use App\Services\Export\ExporterFactory;
use Illuminate\Support\ServiceProvider;

class ExportServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Bind the factory with configuration
        $this->app->singleton(ExporterFactory::class, function ($app) {
            return new ExporterFactory(config('export', []));
        });
    }
}

Step 6: Controller

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

use App\Models\Document;
use App\Services\Export\ExporterFactory;
use Illuminate\Http\Request;

class ExportController extends Controller
{
    public function __construct(
        private readonly ExporterFactory $exporterFactory
    ) {}

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

        try {
            $exporter = $this->exporterFactory->create($format);
            $result = $exporter->export($document, $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()], 400);
        }
    }
}

Why This Design Works

Open/Closed: Add a new format by creating a new exporter class and factory method.
Single Responsibility: Each exporter handles one format.
Testability: Test each exporter and the factory independently.
Flexibility: The factory can create exporters with different configurations.
Readability: The controller doesn't know about export details.

10. SOLID Principles Mapping

O - Open/Closed Principle (OCP)

The Factory Method pattern is a perfect implementation of OCP.

// Open for extension
class XmlExporter implements ExporterInterface { /* ... */ }

// Closed for modification
class ExporterFactory{
    public function create(string $format): ExporterInterface
    {
        // Add new case without changing existing code
        return match($format) {
            // ... existing formats
            'xml' => $this->createXml(),
            default => throw new Exception(...),
        };
    }
}

S - Single Responsibility Principle (SRP)

The factory is responsible for creation.
Each exporter is responsible for its format.
The controller is responsible for HTTP handling.

D - Dependency Inversion Principle (DIP)

The controller depends on the ExporterInterface abstraction (through the factory), not on concrete exporters.

L - Liskov Substitution Principle (LSP)

All exporters are substitutable for ExporterInterface.

function export(ExporterInterface $exporter, Document $doc)
{
    // Works with any exporter
    return $exporter->export($doc);
}

I - Interface Segregation Principle (ISP)

The interface is focused and minimal.

interface ExporterInterface
{
    public function export(Document $document, array $options = []): ExportResult;
    public function getMimeType(): string;
    public function getFileExtension(): string;
}

11. Trade-offs

Benefits

Decoupling: Client code is decoupled from concrete products.
Centralization: Creation logic is in one place.
Extensibility: Easy to add new product types.
Testability: Mock the factory for testing.
Configuration: The factory can handle complex configuration.

Costs

More Classes: You need factory classes and product classes.
Complexity: More indirection.
Learning Curve: Developers need to understand the pattern.
Over-engineering: Not every object needs a factory.

When Is Complexity Justified?

Use the Factory Method pattern when:

Object creation is complex (multiple steps, configuration, dependencies).
You have multiple product types.
You want to decouple client code from concrete products.
You need to test creation logic separately.
The product family is likely to grow.

Avoid the Factory Method pattern when:

Object creation is trivial (simple new with no configuration).
You have only one product type.
The overhead of abstraction isn't justified.

12. When NOT To Use It

3 Green Flags (USE FACTORY METHOD)

Complex Creation: Creating the object requires multiple steps or configuration.
Multiple Types: You have multiple implementations of the same interface.
Likely to Grow: The number of product types will increase.

3 Red Flags (AVOID FACTORY METHOD)

Simple Creation: Object creation is a simple new with no configuration.

// BAD: Factory for trivial creation
class UserFactory { public function create(): User { return new User(); } }

// GOOD: Just use new
$user = new User();

Single Type: You only have one implementation.
Performance Critical: The overhead of indirection isn't worth it.

13. Common Mistakes

1. Creating a Factory for Every Class

// BAD: Factory for every class
class UserFactory { public function create(): User { return new User(); } }
class ProductFactory { public function create(): Product { return new Product(); } }
class OrderFactory { public function create(): Order { return new Order(); } }

Problem: You're adding unnecessary complexity.

Fix: Only create factories for complex creation or multiple types.

2. Factory with Static Methods

// BAD: Static factory
class UserFactory
{
    public static function create(): User { return new User(); }
}

// Usage
$user = UserFactory::create();

Problem: Static methods make testing difficult and create hidden dependencies.

Fix: Use instance methods and inject the factory.

3. Bloated Factory

// BAD: Factory with too many methods
class ExporterFactory
{
    public function createPdf() { /* ... */ }
    public function createExcel() { /* ... */ }
    public function createCsv() { /* ... */ }
    public function createJson() { /* ... */ }
    public function createXml() { /* ... */ }
    public function createHtml() { /* ... */ }
    public function createMarkdown() { /* ... */ }
    public function createRtf() { /* ... */ }
    public function createDocx() { /* ... */ }
}

Problem: The factory becomes a God Class.

Fix: Consider separating into smaller factories or using a generic factory with type-based creation.

4. Factory Returns Concretions

// BAD: Factory returns concrete classes
class ExporterFactory
{
    public function createPdf(): PdfExporter { return new PdfExporter(); }
}

Problem: The client is coupled to the concrete class.

Fix: Return the interface, not the concrete class.

public function createPdf(): ExporterInterface { return new PdfExporter(); }

5. Using Factory When DI Container Is Enough

// BAD: Manual factory when Laravel's container can resolve
class PaymentFactory
{
    public function create(string $type): PaymentProcessor
    {
        return app("payment.{$type}");
    }
}

// GOOD: Use the container
$processor = app('payment.stripe');

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is the Factory Method pattern?
A: A creational design pattern that defines an interface for creating objects but lets subclasses or implementing classes decide which class to instantiate.
Q: What problem does the Factory Method pattern solve?
A: It centralizes object creation, decouples client code from concrete classes, and makes the code easier to extend and test.
Q: How does the Factory Method pattern differ from using new directly?
A: Factory Method encapsulates creation logic, while new creates objects directly in the client code.
Q: When would you use the Factory Method pattern?
A: When object creation is complex, when you have multiple product types, or when you want to decouple client code from concrete products.
Q: How does Laravel use the Factory Method pattern?
A: In database connections, queue drivers, filesystem drivers, mail drivers, and model factories.

Senior/Architect

Q: Explain the difference between Factory Method and Abstract Factory.
A: Factory Method creates one type of product. Abstract Factory creates families of related products.
Q: How do you handle factory method selection without a match statement?
A: Use a registry pattern where strategies are registered with a key.
Q: What's the relationship between Factory Method and Dependency Injection?
A: The Factory Method pattern creates objects, while Dependency Injection provides objects. They often work together.
Q: How do you test a class that uses a factory?
A: Mock the factory and verify that the correct product is created.
Q: How do you handle factory methods with different constructor signatures?
A: Use a factory with explicit methods (createStripe(), createPayPal()) or use a builder pattern for complex creation.

15. Interactive Practice Challenge

The Requirement

You're building a Payment Gateway System for an e-commerce application. The current code uses scattered new statements everywhere.

The Code (POOR DESIGN)

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

use App\Models\Order;
use App\Models\User;
use App\Services\Payment\StripeService;
use App\Services\Payment\PayPalService;
use App\Services\Payment\BankTransferService;
use App\Services\Payment\CryptoService;
use App\Services\Payment\SquareService;
use App\Services\Notification\EmailNotification;
use App\Services\Notification\SmsNotification;
use App\Services\Notification\SlackNotification;
use App\Services\Logger\FileLogger;
use App\Services\Logger\DatabaseLogger;
use App\Services\Logger\CloudLogger;
use App\Services\Cache\RedisCache;
use App\Services\Cache\FileCache;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class PaymentController extends Controller
{
    public function process(Request $request, Order $order)
    {
        $user = $order->user;
        $paymentMethod = $order->payment_method;

        // Payment processing
        $logger = $this->getLogger($order->id);
        $cache = $this->getCache($order->id);

        if ($paymentMethod === 'stripe') {
            $payment = new StripeService(
                config('services.stripe.secret'),
                config('services.stripe.webhook_secret'),
                $logger,
                $cache,
                config('services.stripe.default_currency', 'USD'),
                config('services.stripe.retry_attempts', 3)
            );
        } elseif ($paymentMethod === 'paypal') {
            $payment = new PayPalService(
                config('services.paypal.client_id'),
                config('services.paypal.secret'),
                config('services.paypal.mode', 'sandbox'),
                $logger,
                $cache
            );
        } elseif ($paymentMethod === 'bank_transfer') {
            $payment = new BankTransferService(
                config('services.bank_transfer.account_number'),
                config('services.bank_transfer.routing_number'),
                config('services.bank_transfer.bank_name'),
                $logger
            );
        } elseif ($paymentMethod === 'crypto') {
            $payment = new CryptoService(
                config('services.crypto.api_key'),
                config('services.crypto.default_currency', 'BTC'),
                $logger,
                $cache
            );
        } elseif ($paymentMethod === 'square') {
            $payment = new SquareService(
                config('services.square.access_token'),
                config('services.square.location_id'),
                $logger,
                $cache
            );
        } else {
            throw new \Exception("Unsupported payment method: {$paymentMethod}");
        }

        $result = $payment->charge($order);

        // Notifications
        $notificationLogger = new FileLogger(storage_path('logs/notifications.log'));

        $preferences = $user->notification_preferences ?? ['email'];
        $notificationResults = [];

        foreach ($preferences as $pref) {
            if ($pref === 'email') {
                $notifier = new EmailNotification(
                    config('mail.from.address'),
                    config('mail.from.name'),
                    $notificationLogger
                );
                $notificationResults['email'] = $notifier->send($user, "Payment processed for order #{$order->id}");
            } elseif ($pref === 'sms') {
                $notifier = new SmsNotification(
                    config('services.twilio.sid'),
                    config('services.twilio.token'),
                    config('services.twilio.from'),
                    $notificationLogger
                );
                $notificationResults['sms'] = $notifier->send($user, "Payment processed for order #{$order->id}");
            } elseif ($pref === 'slack') {
                $notifier = new SlackNotification(
                    config('services.slack.webhook_url'),
                    $notificationLogger
                );
                $notificationResults['slack'] = $notifier->send($user, "Payment processed for order #{$order->id}");
            }
        }

        // Log the payment
        Log::info('Payment processed', [
            'order_id' => $order->id,
            'payment_method' => $paymentMethod,
            'amount' => $order->total,
            'result' => $result,
            'notification_results' => $notificationResults,
        ]);

        return response()->json([
            'success' => true,
            'result' => $result,
            'notifications' => $notificationResults,
        ]);
    }

    private function getLogger($orderId)
    {
        if (config('app.env') === 'production') {
            return new CloudLogger(config('services.cloud_logger.api_key'));
        } else {
            return new FileLogger(storage_path("logs/payments_{$orderId}.log"));
        }
    }

    private function getCache($orderId)
    {
        if (config('cache.default') === 'redis') {
            return new RedisCache(config('cache.redis'));
        } else {
            return new FileCache(storage_path("cache/payments_{$orderId}"));
        }
    }
}

The Challenges

The code is a nightmare:

Scattered new statements across the controller.
Tight coupling to payment services, notification services, loggers, and caches.
Complex creation logic with multiple configuration values.
Duplicated logic for logger and cache selection.
Hard to test because of all the dependencies.
Hard to extend for new payment methods or notification channels.

Your Task

Refactor this system using the Factory Method pattern. Specifically:

Define product interfaces for:
- Payment processors
- Notification services
- Loggers
- Cache services
Create factories for each product family:
- PaymentProcessorFactory
- NotificationFactory
- LoggerFactory
- CacheFactory
Implement concrete products for each type.
Refactor the controller to use the factories.
Add support for new payment methods (e.g., PaytmService, RazorpayService) without modifying existing code.
Implement a PaymentFactoryRegistry or PaymentTypeResolver that maps payment types to factories.

Questions to Consider

How do you handle the different constructor signatures for each payment service?
How do you select the right factory for each payment method?
How do you handle configuration inheritance (shared config across services)?
How do you test the controller with mocked factories?
How do you add a new payment method without modifying existing code?

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

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: The Factory Method pattern centralizes object creation in a dedicated method or class, decoupling client code from concrete products.
One-sentence intuition: Instead of using new everywhere, ask a factory to create the object for you.
One-sentence decision rule: If object creation is complex, distributed, or likely to change, use a factory to centralize and encapsulate it.

17. Related Concepts

SOLID Principles

Open/Closed: Factories enable extension without modification.
Single Responsibility: Factories handle creation, products handle business logic.
Dependency Inversion: Clients depend on product interfaces, not concretions.
Liskov Substitution: All products are substitutable through the interface.

Design Patterns

Abstract Factory: Creates families of related products.
Builder: Complex object construction step by step.
Singleton: Ensures only one instance exists.
Prototype: Creates objects by cloning.
Dependency Injection: Provides objects to clients.

Laravel Internals

Service Container: Laravel's built-in factory for resolving dependencies.
Service Providers: Register bindings for the container.
Model Factories: Create test data.
Queue Manager: Factory for queue connections.
Filesystem Manager: Factory for storage drivers.
Mail Manager: Factory for mail drivers.
Database Manager: Factory for database connections.

Enterprise Patterns

Factory Method: The pattern itself.
Abstract Factory: Family of factories.
Repository: Often uses factories to create entities.
Service Layer: Uses factories to create services.
Data Mapper: Uses factories to create domain objects.

Final Thoughts

The new keyword is powerful, but with great power comes great responsibility. Using new everywhere creates tight coupling, scattered logic, and makes your code hard to test and extend.

The Factory Method pattern gives you a better way. It centralizes object creation, decouples your code, and makes it easy to add new types.

Every time you find yourself writing new in your controller, ask yourself: "Should this be moved to a factory?"

Remember: Stop creating objects with new. Start using factories. Your future self will thank you.

Github: Factory Pattern Practice Labs

Stop Writing Massive if-else Blocks: Master the Strategy Pattern in PHP & Laravel

Anas Hussain — Mon, 14 Sep 2026 09:27:43 +0000

1. Hook & Problem Statement

You're a Laravel developer. You need to build a shipping cost calculator.

You start simple. if ($country === 'USA') { return 10; }

Then the business adds: "We need different pricing for express shipping." So you add elseif ($shipping === 'express').

Then: "Different prices for heavy items." Another elseif.

Then: "Discounts for prime members." Another condition.

Then: "Free shipping for orders over $50." Another one.

Before you know it, your method looks like this:

public function calculateShipping($order) {
    if ($order->country === 'USA') {
        if ($order->weight > 20) {
            if ($order->shipping_method === 'express') {
                // 10 lines of complex logic
            } else {
                // 8 lines of complex logic
            }
        } else {
            // More nested conditions...
        }
    } elseif ($order->country === 'Canada') {
        // 20 more lines
    } elseif ($order->country === 'UK') {
        // 20 more lines
    } else {
        // 20 more lines
    }
}

Your function is now 200 lines long. It's unreadable. It's untestable. Adding a new shipping method means understanding the entire mess.

This is the Conditional Apocalypse. And it's the problem the Strategy Pattern was designed to solve.

2. Why This Pattern Exists

The Software Engineering Problem It Solves

The Strategy Pattern solves the problem of having multiple algorithms or behaviors that need to be interchangeable at runtime.

In any non-trivial application, you'll have variations of the same behavior:

Different payment gateways (Stripe, PayPal, etc.)
Different shipping calculators (USPS, FedEx, DHL)
Different notification channels (Email, SMS, Slack)
Different discount calculations (Percentage, Fixed amount, Bulk discount)

The naive approach—using conditional logic—creates tight coupling, code duplication, and violates the Open/Closed Principle.

The Pain That Existed Before

Before the Strategy Pattern (or in codebases that don't use it), developers suffered from:

Massive if-else/switch blocks that grew endlessly with every new requirement.
Duplicated code across different branches.
Tight coupling between the context class and all variations.
Difficult testing: Every branch needed separate test coverage.
Open/Closed Principle violation: Adding a new behavior required modifying existing code.
Low cohesion: A single class handled multiple, unrelated responsibilities.

Why Large Applications Need It

As your application grows, the number of variations increases. A simple shipping calculator might have:

5 countries
3 shipping methods
2 weight tiers
3 customer tiers
4 discount types

That's 5 × 3 × 2 × 3 × 4 = 360 conditional combinations. Adding a new country (×5 = 1800 combinations) becomes a nightmare.

The Strategy Pattern reduces this complexity by:

Extracting each algorithm into its own class.
Making algorithms interchangeable at runtime.
Isolating changes to specific strategies.

3. Real World Analogy

The GPS Navigation System

Imagine you're driving to a destination. Your GPS offers multiple routes:

Fastest Route: Prioritizes highways and speed.
Shortest Route: Prioritizes distance.
Scenic Route: Prioritizes beautiful roads.
Eco Route: Prioritizes fuel efficiency.

The Bad Way:
Your GPS has a single massive function with if-else statements for each route type. Adding a new route (e.g., "Avoid Highways") requires modifying the core GPS logic.

The Strategy Pattern Way:
The GPS has a RouteStrategy interface with a calculateRoute() method.

FastestRouteStrategy implements RouteStrategy
ShortestRouteStrategy implements RouteStrategy
ScenicRouteStrategy implements RouteStrategy
EcoRouteStrategy implements RouteStrategy

The GPS (the context) receives a RouteStrategy and delegates the calculation.

Analogy Mapping:

GPS System: The context class (e.g., ShippingCalculator).
Route Strategy: The strategy interface.
Fastest/Shortest/Scenic Route: Concrete strategies.
Driver: The client code.
Switching routes: Changing the strategy at runtime.
Adding a new route: Creating a new strategy class.

Why it works: The GPS doesn't need to know how each route is calculated. It just delegates. Adding a new route doesn't change the GPS logic.

4. The Pain (Bad Design)

Let's look at a typical conditional nightmare.

namespace App\Services;

use App\Models\Order;

class ShippingCalculator
{
    private array $config;

    public function __construct()
    {
        $this->config = config('shipping');
    }

    public function calculate(Order $order): float
    {
        $total = 0;
        $country = $order->shipping_country;
        $method = $order->shipping_method;
        $weight = $order->total_weight;

        // Base rates by country
        if ($country === 'USA') {
            if ($method === 'standard') {
                if ($weight <= 5) {
                    $total = 5.00;
                } elseif ($weight <= 10) {
                    $total = 8.50;
                } elseif ($weight <= 20) {
                    $total = 12.00;
                } else {
                    $total = 12.00 + (($weight - 20) * 0.50);
                }
            } elseif ($method === 'express') {
                if ($weight <= 5) {
                    $total = 15.00;
                } elseif ($weight <= 10) {
                    $total = 22.50;
                } elseif ($weight <= 20) {
                    $total = 30.00;
                } else {
                    $total = 30.00 + (($weight - 20) * 1.00);
                }
            } elseif ($method === 'overnight') {
                if ($weight <= 5) {
                    $total = 25.00;
                } elseif ($weight <= 10) {
                    $total = 35.00;
                } elseif ($weight <= 20) {
                    $total = 45.00;
                } else {
                    $total = 45.00 + (($weight - 20) * 1.50);
                }
            }
        } elseif ($country === 'Canada') {
            if ($method === 'standard') {
                if ($weight <= 5) {
                    $total = 10.00;
                } elseif ($weight <= 10) {
                    $total = 15.00;
                } elseif ($weight <= 20) {
                    $total = 22.00;
                } else {
                    $total = 22.00 + (($weight - 20) * 0.75);
                }
            } elseif ($method === 'express') {
                // More nested conditions...
            } // And so on...
        } elseif ($country === 'UK') {
            // Another 30 lines...
        } elseif ($country === 'Australia') {
            // Another 30 lines...
        } else {
            // International shipping...
        }

        // Apply discounts
        if ($order->subtotal > 100) {
            $total *= 0.90; // 10% discount
        }

        // Apply prime member discount
        if ($order->user && $order->user->is_prime) {
            $total *= 0.85; // 15% discount
        }

        // Add handling fee for heavy items
        if ($weight > 50) {
            $total += 10.00;
        }

        // Add insurance for valuable items
        if ($order->subtotal > 500) {
            $total += $order->subtotal * 0.02;
        }

        // Add weekend delivery surcharge
        if (now()->isWeekend() && $method === 'overnight') {
            $total += 10.00;
        }

        // Round and return
        return round($total, 2);
    }
}

Why This Is Terrible

Massive Conditional Block: 100+ lines of nested if-else.
Low Cohesion: The class handles US rates, Canadian rates, UK rates, Australian rates, international rates, discounts, prime member discounts, handling fees, insurance, and weekend surcharges.
High Coupling: All logic is tightly coupled in one method.
Difficult Testing: Testing all combinations requires 100+ test cases.
Violates OCP: Adding a new country requires modifying this class.
Violates SRP: This class has at least 10 responsibilities.
Difficult to Read: No one can understand this method.

Why Developers Write Code Like This

We write code like this because:

It's the "quick and dirty" solution.
We don't think about future growth.
We're not familiar with design patterns.
We think "just one more if-else" won't hurt.
We haven't learned to recognize the Strategy pattern opportunity.

5. Solution Overview

The Strategy Pattern is a behavioral design pattern that enables selecting an algorithm's implementation at runtime. It defines a family of algorithms, encapsulates each one, and makes them interchangeable.

Core Idea

Instead of using conditional logic to choose between different behaviors, you:

Define a common interface for all algorithms.
Implement each algorithm in its own class.
Inject the algorithm (strategy) into the context class.

The context delegates the work to the strategy, which is interchangeable at runtime.

Main Participants

Strategy Interface: Defines a common method that all strategies must implement.
Concrete Strategies: Different implementations of the algorithm.
Context: The class that uses the strategy. It holds a reference to a strategy and delegates work to it.
Client: The code that selects and injects the appropriate strategy.

How Objects Collaborate

Client → Context → Strategy Interface → Concrete Strategy A
                                     → Concrete Strategy B
                                     → Concrete Strategy C

The client creates a concrete strategy and injects it into the context. The context uses the strategy without knowing which specific implementation it is.

Mental Model

Think of your car's gear shift.

Strategy Interface: "Gear Selection" (the method you use).
Concrete Strategies: Park, Reverse, Neutral, Drive, Low Gear.
Context: The Car (uses the gear selection).
Client: You (the driver).

When you shift to "Drive," you're selecting a strategy. The car changes how it operates internally (different RPM, torque, etc.) without you knowing the details.

Benefits

Open/Closed: Add new strategies without changing existing code.
Single Responsibility: Each strategy has one job.
Testability: Test each strategy independently.
Flexibility: Swap strategies at runtime.
Readability: No massive conditionals.

Trade-offs

More Classes: Each strategy is a separate class.
Complexity: More moving parts to understand.
Indirection: The client must know which strategy to use.

6. UML Diagram

Laravel Strategy Pattern Mermaid Diagram

Diagram Explanation

ShippingCalculator (Context) holds a reference to ShippingStrategy (Interface).
Concrete Strategies implement the interface with specific algorithms.
DiscountDecorator is a wrapper strategy that applies discounts to other strategies (decorator pattern).
WeightBasedStrategy is a reusable strategy that calculates based on weight tiers.

7. Vanilla PHP Example

Let's refactor the shipping calculator using the Strategy Pattern.

Before Refactoring

(The terrible conditional mess shown above)

After Refactoring

Step 1: Define the Strategy Interface

interface ShippingStrategy
{
    public function calculate(Order $order): float;
}

Step 2: Implement Concrete Strategies

// Base strategy with common functionality
abstract class BaseShippingStrategy implements ShippingStrategy
{
    protected function getBaseRate(string $country, string $method, float $weight): float
    {
        $rates = [
            'USA' => [
                'standard' => [5.00, 8.50, 12.00, 12.00],
                'express' => [15.00, 22.50, 30.00, 30.00],
                'overnight' => [25.00, 35.00, 45.00, 45.00],
            ],
            'Canada' => [
                'standard' => [10.00, 15.00, 22.00, 22.00],
                'express' => [20.00, 28.00, 38.00, 38.00],
                'overnight' => [35.00, 45.00, 55.00, 55.00],
            ],
            // More countries can be added
        ];

        if (!isset($rates[$country][$method])) {
            throw new \Exception("Invalid country or method combination");
        }

        $rateTable = $rates[$country][$method];
        $weightTiers = [5, 10, 20];

        for ($i = 0; $i < count($weightTiers); $i++) {
            if ($weight <= $weightTiers[$i]) {
                return $rateTable[$i];
            }
        }

        // Over 20 lbs: base rate + per-pound charge
        $baseRate = $rateTable[3];
        $excessWeight = $weight - 20;
        $perPoundCharge = match($method) {
            'standard' => 0.50,
            'express' => 1.00,
            'overnight' => 1.50,
            default => 0.50,
        };

        return $baseRate + ($excessWeight * $perPoundCharge);
    }

    protected function getWeekendSurcharge(string $method): float
    {
        if (now()->isWeekend() && $method === 'overnight') {
            return 10.00;
        }
        return 0.00;
    }

    protected function getHeavyItemSurcharge(float $weight): float
    {
        return $weight > 50 ? 10.00 : 0.00;
    }

    protected function getInsuranceSurcharge(float $subtotal): float
    {
        return $subtotal > 500 ? $subtotal * 0.02 : 0.00;
    }
}

// USA Strategy
class USAStrategy extends BaseShippingStrategy
{
    public function calculate(Order $order): float
    {
        $base = $this->getBaseRate('USA', $order->shipping_method, $order->total_weight);
        $weekend = $this->getWeekendSurcharge($order->shipping_method);
        $heavy = $this->getHeavyItemSurcharge($order->total_weight);
        $insurance = $this->getInsuranceSurcharge($order->subtotal);

        return round($base + $weekend + $heavy + $insurance, 2);
    }
}

// Canada Strategy
class CanadaStrategy extends BaseShippingStrategy
{
    public function calculate(Order $order): float
    {
        $base = $this->getBaseRate('Canada', $order->shipping_method, $order->total_weight);
        $weekend = $this->getWeekendSurcharge($order->shipping_method);
        $heavy = $this->getHeavyItemSurcharge($order->total_weight);
        $insurance = $this->getInsuranceSurcharge($order->subtotal);

        return round($base + $weekend + $heavy + $insurance, 2);
    }
}

// UK Strategy
class UKStrategy extends BaseShippingStrategy
{
    public function calculate(Order $order): float
    {
        // UK-specific logic
        $base = 15.00;
        if ($order->total_weight > 10) {
            $base += ($order->total_weight - 10) * 0.60;
        }

        return round($base, 2);
    }
}

// International Strategy
class InternationalStrategy extends BaseShippingStrategy
{
    public function calculate(Order $order): float
    {
        // International flat rate + weight
        $base = 25.00;
        if ($order->total_weight > 5) {
            $base += ($order->total_weight - 5) * 2.00;
        }

        return round($base, 2);
    }
}

// Discount Strategy (Decorator)
class DiscountStrategy implements ShippingStrategy
{
    private ShippingStrategy $wrapped;
    private float $discount;

    public function __construct(ShippingStrategy $wrapped, float $discount)
    {
        $this->wrapped = $wrapped;
        $this->discount = $discount;
    }

    public function calculate(Order $order): float
    {
        $base = $this->wrapped->calculate($order);
        return round($base * (1 - $this->discount), 2);
    }
}

Step 3: The Context

class ShippingCalculator
{
    private ShippingStrategy $strategy;

    public function __construct(ShippingStrategy $strategy)
    {
        $this->strategy = $strategy;
    }

    public function calculate(Order $order): float
    {
        return $this->strategy->calculate($order);
    }

    public function setStrategy(ShippingStrategy $strategy): void
    {
        $this->strategy = $strategy;
    }
}

// Strategy Factory (optional)
class ShippingStrategyFactory
{
    public static function create(Order $order): ShippingStrategy
    {
        $country = $order->shipping_country;

        // Select base strategy
        $strategy = match($country) {
            'USA' => new USAStrategy(),
            'Canada' => new CanadaStrategy(),
            'UK' => new UKStrategy(),
            default => new InternationalStrategy(),
        };

        // Apply discounts
        if ($order->subtotal > 100) {
            $strategy = new DiscountStrategy($strategy, 0.10);
        }

        if ($order->user && $order->user->is_prime) {
            $strategy = new DiscountStrategy($strategy, 0.15);
        }

        return $strategy;
    }
}

Step 4: Usage

// Client code
$order = Order::find(123);

// Using the factory
$strategy = ShippingStrategyFactory::create($order);
$calculator = new ShippingCalculator($strategy);
$shippingCost = $calculator->calculate($order);

// Or manual selection
if ($order->shipping_country === 'USA') {
    $calculator = new ShippingCalculator(new USAStrategy());
} else {
    $calculator = new ShippingCalculator(new InternationalStrategy());
}
$shippingCost = $calculator->calculate($order);

// Or runtime strategy change
$calculator->setStrategy(new CanadaStrategy());
$shippingCost = $calculator->calculate($order);

What We Improved

No Conditionals: The context has no if-else blocks.
Open/Closed: Add a new country by creating a new strategy class.
Single Responsibility: Each strategy handles one country.
Testability: Test each strategy independently.
Reusability: Strategies can be composed (e.g., DiscountStrategy wraps other strategies).
Readability: Each class is small and focused.
Flexibility: Strategies can be swapped at runtime.

8. Laravel Internal Example

Laravel uses the Strategy Pattern extensively. Let's look at some key examples.

Authentication Guards

Laravel's authentication system uses the Strategy Pattern to support different guard types.

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

// SessionGuard (Strategy Implementation)
class SessionGuard implements Guard
{
    // Session-based authentication
}

// TokenGuard (Strategy Implementation)
class TokenGuard implements Guard
{
    // Token-based authentication
}

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

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

    protected function resolve($name): Guard
    {
        // Creates the appropriate guard based on configuration
        $config = $this->getConfig($name);
        $driverMethod = 'create'.ucfirst($config['driver']).'Driver';

        if (method_exists($this, $driverMethod)) {
            return $this->{$driverMethod}($config);
        }
    }
}

Why This Is Elegant:

The interface defines the contract for all guards.
Each guard implements the interface in its own way.
AuthManager (context) delegates to the appropriate guard.
Adding a new guard type doesn't affect existing code.

Filesystem Drivers

Laravel's Filesystem uses the Strategy Pattern to support different storage providers.

// Illuminate\Contracts\Filesystem\Filesystem (Strategy Interface)
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 (Strategy Implementation)
class LocalFilesystem implements Filesystem
{
    // Local filesystem operations
}

// S3Filesystem (Strategy Implementation)
class S3Filesystem implements Filesystem
{
    // S3 operations
}

// The Context: FilesystemManager
class FilesystemManager
{
    public function disk(?string $name = null): Filesystem
    {
        $name = $name ?: $this->getDefaultDriver();

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

    protected function resolve(string $name): Filesystem
    {
        $config = $this->getConfig($name);

        return match($config['driver']) {
            'local' => $this->createLocalDriver($config),
            's3' => $this->createS3Driver($config),
            // More drivers...
        };
    }
}

Why This Is Elegant:

All storage operations are interchangeable.
You can switch between local and S3 without changing code.
Adding a new driver (e.g., Google Cloud) is straightforward.

Queue Drivers

Laravel's Queue system uses the Strategy Pattern.

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

// DatabaseQueue (Strategy Implementation)
class DatabaseQueue implements Queue
{
    // Database queue operations
}

// RedisQueue (Strategy Implementation)
class RedisQueue implements Queue
{
    // Redis queue operations
}

// SqsQueue (Strategy Implementation)
class SqsQueue implements Queue
{
    // SQS queue operations
}

Why This Is Elegant:

The same Queue::push() works regardless of the driver.
Switching drivers is a configuration change.
Each driver handles its own specific logic.

Notification Channels

Laravel's Notifications use the Strategy Pattern for different channels.

// Interface (implicit via method signatures)
class Notification
{
    public function via($notifiable): array
    {
        return ['mail', 'database'];
    }
}

// The Context: ChannelManager
class ChannelManager
{
    public function send($notifiable, $notification, $channels = null): void
    {
        $channels = $channels ?: $notification->via($notifiable);

        foreach ($channels as $channel) {
            // The strategy pattern in action
            $this->channel($channel)->send($notifiable, $notification);
        }
    }
}

Why This Is Elegant:

Each channel (mail, database, slack, etc.) is a strategy.
Adding a new channel only requires implementing the channel interface.
The notification system doesn't care which channels are used.

Validation Rules

Laravel's validation system uses the Strategy Pattern for rules.

// Rule interface
interface Rule
{
    public function passes($attribute, $value): bool;
    public function message(): string;
}

// Custom rules (strategies)
class Uppercase implements Rule
{
    public function passes($attribute, $value): bool
    {
        return strtoupper($value) === $value;
    }

    public function message(): string
    {
        return 'The :attribute must be uppercase.';
    }
}

// Usage
$request->validate([
    'name' => ['required', new Uppercase],
]);

Why This Is Elegant:

Each rule is a self-contained strategy.
You can add custom rules without changing the validation system.
Rules can be combined and reused.

9. Real Laravel Application Example

Let's build a Discount Calculation System using the Strategy Pattern.

Scenario

Your e-commerce application needs to support multiple discount types:

Percentage Discount: 10% off everything.
Fixed Amount Discount: $20 off orders over $100.
Bulk Discount: Buy 2 get 1 free.
Seasonal Discount: Variable discounts based on season.
Referral Discount: 15% off for referred customers.

Implementation

Step 1: Define the Strategy Interface

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

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

interface DiscountStrategy
{
    public function calculate(Order $order): float;
    public function getDescription(): string;
    public function isApplicable(Order $order): bool;
    public function getPriority(): int;
}

Step 2: Implement Concrete Strategies

// app/Services/Discounts/PercentageDiscount.php
namespace App\Services\Discounts;

use App\Contracts\DiscountStrategy;
use App\Models\Order;

class PercentageDiscount implements DiscountStrategy
{
    private float $percentage;
    private string $description;

    public function __construct(float $percentage, string $description = 'Percentage Discount')
    {
        $this->percentage = $percentage;
        $this->description = $description;
    }

    public function calculate(Order $order): float
    {
        return ($order->subtotal * $this->percentage) / 100;
    }

    public function getDescription(): string
    {
        return $this->description . " ({$this->percentage}%)";
    }

    public function isApplicable(Order $order): bool
    {
        return $order->subtotal > 0;
    }

    public function getPriority(): int
    {
        return 10; // Medium priority
    }
}

// app/Services/Discounts/FixedAmountDiscount.php
namespace App\Services\Discounts;

use App\Contracts\DiscountStrategy;
use App\Models\Order;

class FixedAmountDiscount implements DiscountStrategy
{
    private float $amount;
    private float $threshold;
    private string $description;

    public function __construct(float $amount, float $threshold = 0, string $description = 'Fixed Amount Discount')
    {
        $this->amount = $amount;
        $this->threshold = $threshold;
        $this->description = $description;
    }

    public function calculate(Order $order): float
    {
        return min($this->amount, $order->subtotal);
    }

    public function getDescription(): string
    {
        return $this->description . " (\${$this->amount})";
    }

    public function isApplicable(Order $order): bool
    {
        return $order->subtotal >= $this->threshold;
    }

    public function getPriority(): int
    {
        return 20; // Lower priority than percentage
    }
}

// app/Services/Discounts/BulkDiscount.php
namespace App\Services\Discounts;

use App\Contracts\DiscountStrategy;
use App\Models\Order;

class BulkDiscount implements DiscountStrategy
{
    private int $minQuantity;
    private float $discountPercent;

    public function __construct(int $minQuantity = 2, float $discountPercent = 33.33)
    {
        $this->minQuantity = $minQuantity;
        $this->discountPercent = $discountPercent;
    }

    public function calculate(Order $order): float
    {
        $items = $order->items;
        $discount = 0;

        foreach ($items as $item) {
            if ($item['quantity'] >= $this->minQuantity) {
                // Buy 2 get 1 free = 33.33% discount
                $freeItems = floor($item['quantity'] / ($this->minQuantity + 1));
                $discount += $freeItems * $item['price'];
            }
        }

        return $discount;
    }

    public function getDescription(): string
    {
        return "Buy " . ($this->minQuantity + 1) . " get 1 free";
    }

    public function isApplicable(Order $order): bool
    {
        foreach ($order->items as $item) {
            if ($item['quantity'] >= $this->minQuantity + 1) {
                return true;
            }
        }
        return false;
    }

    public function getPriority(): int
    {
        return 5; // High priority
    }
}

// app/Services/Discounts/SeasonalDiscount.php
namespace App\Services\Discounts;

use App\Contracts\DiscountStrategy;
use App\Models\Order;

class SeasonalDiscount implements DiscountStrategy
{
    private array $seasonalRates;

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

    public function calculate(Order $order): float
    {
        $month = now()->month;
        $rate = $this->seasonalRates[$month] ?? 0;

        return ($order->subtotal * $rate) / 100;
    }

    public function getDescription(): string
    {
        $month = now()->month;
        $rate = $this->seasonalRates[$month] ?? 0;
        return "Seasonal Discount ({$rate}%)";
    }

    public function isApplicable(Order $order): bool
    {
        $month = now()->month;
        return isset($this->seasonalRates[$month]) && $this->seasonalRates[$month] > 0;
    }

    public function getPriority(): int
    {
        return 15; // Medium priority
    }
}

// app/Services/Discounts/ReferralDiscount.php
namespace App\Services\Discounts;

use App\Contracts\DiscountStrategy;
use App\Models\Order;

class ReferralDiscount implements DiscountStrategy
{
    private float $percentage;
    private string $description;

    public function __construct(float $percentage = 15)
    {
        $this->percentage = $percentage;
        $this->description = 'Referral Discount';
    }

    public function calculate(Order $order): float
    {
        return ($order->subtotal * $this->percentage) / 100;
    }

    public function getDescription(): string
    {
        return $this->description . " ({$this->percentage}%)";
    }

    public function isApplicable(Order $order): bool
    {
        return $order->user && $order->user->referred_by !== null;
    }

    public function getPriority(): int
    {
        return 5; // High priority
    }
}

Step 3: The Context (Discount Calculator)

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

use App\Contracts\DiscountStrategy;
use App\Models\Order;
use Illuminate\Support\Collection;

class DiscountCalculator
{
    private Collection $strategies;

    public function __construct(array $strategies = [])
    {
        $this->strategies = collect($strategies);
    }

    public function addStrategy(DiscountStrategy $strategy): self
    {
        $this->strategies->push($strategy);
        return $this;
    }

    public function getApplicableStrategies(Order $order): Collection
    {
        return $this->strategies
            ->filter(fn(DiscountStrategy $strategy) => $strategy->isApplicable($order))
            ->sortBy(fn(DiscountStrategy $strategy) => $strategy->getPriority());
    }

    public function calculate(Order $order): array
    {
        $applicable = $this->getApplicableStrategies($order);

        if ($applicable->isEmpty()) {
            return [
                'total_discount' => 0,
                'applied_discounts' => [],
                'final_subtotal' => $order->subtotal,
            ];
        }

        $totalDiscount = 0;
        $appliedDiscounts = [];
        $currentSubtotal = $order->subtotal;

        foreach ($applicable as $strategy) {
            $discount = $strategy->calculate($order);

            // Cap discount at remaining subtotal
            $discount = min($discount, $currentSubtotal);

            if ($discount > 0) {
                $totalDiscount += $discount;
                $currentSubtotal -= $discount;

                $appliedDiscounts[] = [
                    'description' => $strategy->getDescription(),
                    'amount' => $discount,
                    'remaining_subtotal' => $currentSubtotal,
                ];
            }

            // Stop if no more subtotal to discount
            if ($currentSubtotal <= 0) {
                break;
            }
        }

        return [
            'total_discount' => round($totalDiscount, 2),
            'applied_discounts' => $appliedDiscounts,
            'final_subtotal' => round($currentSubtotal, 2),
            'original_subtotal' => $order->subtotal,
        ];
    }
}

Step 4: Service Provider

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

use App\Contracts\DiscountStrategy;
use App\Services\DiscountCalculator;
use App\Services\Discounts\BulkDiscount;
use App\Services\Discounts\FixedAmountDiscount;
use App\Services\Discounts\PercentageDiscount;
use App\Services\Discounts\ReferralDiscount;
use App\Services\Discounts\SeasonalDiscount;
use Illuminate\Support\ServiceProvider;

class DiscountServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        // Register all discount strategies
        $this->app->tag([
            PercentageDiscount::class,
            FixedAmountDiscount::class,
            BulkDiscount::class,
            SeasonalDiscount::class,
            ReferralDiscount::class,
        ], 'discount_strategies');

        // Register the calculator with all strategies
        $this->app->singleton(DiscountCalculator::class, function ($app) {
            $calculator = new DiscountCalculator();

            // Add strategies
            $calculator->addStrategy(new PercentageDiscount(10, 'Standard Discount'));
            $calculator->addStrategy(new FixedAmountDiscount(20, 100, 'Spend $100 get $20 off'));
            $calculator->addStrategy(new BulkDiscount(2, 33.33));
            $calculator->addStrategy(new SeasonalDiscount([
                1 => 5,  // January: 5%
                2 => 0,  // February: 0%
                3 => 0,  // March: 0%
                4 => 0,  // April: 0%
                5 => 0,  // May: 0%
                6 => 0,  // June: 0%
                7 => 0,  // July: 0%
                8 => 0,  // August: 0%
                9 => 0,  // September: 0%
                10 => 0, // October: 0%
                11 => 15, // November: 15%
                12 => 20, // December: 20%
            ]));
            $calculator->addStrategy(new ReferralDiscount(15));

            // You could also add strategies dynamically based on configuration
            $configuredStrategies = config('discounts.strategies', []);
            foreach ($configuredStrategies as $strategyClass) {
                if (class_exists($strategyClass)) {
                    $calculator->addStrategy(app($strategyClass));
                }
            }

            return $calculator;
        });
    }
}

Step 5: Controller

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

use App\Models\Cart;
use App\Services\DiscountCalculator;
use Illuminate\Http\Request;

class CartController extends Controller
{
    public function __construct(
        private readonly DiscountCalculator $discountCalculator
    ) {}

    public function checkout(Request $request)
    {
        $cart = $request->user()->cart;

        // Convert cart to order structure for discount calculation
        $order = (object) [
            'subtotal' => $cart->subtotal,
            'items' => $cart->items->toArray(),
            'user' => $request->user(),
        ];

        $result = $this->discountCalculator->calculate($order);

        return view('checkout', [
            'subtotal' => $order->subtotal,
            'discounts' => $result['applied_discounts'],
            'total_discount' => $result['total_discount'],
            'final_total' => $result['final_subtotal'],
        ]);
    }
}

Why This Design Works

Open/Closed: Add a new discount type by creating a new strategy class.
Single Responsibility: Each discount type is in its own class.
Testability: Test each discount strategy independently.
Flexibility: Discounts can be enabled/disabled by adding/removing strategies.
Composable: Strategies are applied in priority order.
Readability: No massive conditional blocks.

10. SOLID Principles Mapping

O - Open/Closed Principle (OCP)

The Strategy Pattern is the poster child for OCP. You can add new strategies without modifying the context or existing strategies.

// Adding a new discount type
class NewYearDiscount implements DiscountStrategy
{
    public function calculate(Order $order): float
    {
        // New Year special logic
    }
}

// No changes to DiscountCalculator required!

S - Single Responsibility Principle (SRP)

Each strategy has one responsibility: implementing a specific algorithm.

PercentageDiscount: Calculates percentage discounts.
FixedAmountDiscount: Calculates fixed discounts.
BulkDiscount: Calculates bulk discounts.

L - Liskov Substitution Principle (LSP)

All strategies implement the same interface and are substitutable.

function applyDiscount(DiscountStrategy $strategy, Order $order)
{
    // Works with any strategy
    return $strategy->calculate($order);
}

D - Dependency Inversion Principle (DIP)

The context (DiscountCalculator) depends on the DiscountStrategy interface, not on concrete implementations.

I - Interface Segregation Principle (ISP)

The interface is focused and minimal:

interface DiscountStrategy
{
    public function calculate(Order $order): float;
    public function getDescription(): string;
    public function isApplicable(Order $order): bool;
    public function getPriority(): int;
}

No strategy is forced to implement methods it doesn't need.

11. Trade-offs

Benefits

Flexibility: Add new algorithms without changing existing code.
Testability: Test each strategy independently.
Readability: No massive conditionals.
Maintainability: Changes are isolated to specific strategies.
Reusability: Strategies can be reused across different contexts.
Runtime Behavior: Swap strategies at runtime.

Costs

More Classes: Each strategy is a separate class.
Complexity: More moving parts.
Indirection: The client must know which strategy to use.
Over-engineering: Not every conditional needs the Strategy Pattern.

When Is Complexity Justified?

Use the Strategy Pattern when:

You have multiple algorithms for the same task.
The algorithms vary independently from the context.
You need to be able to switch algorithms at runtime.
The number of algorithms is likely to grow.

Avoid the Strategy Pattern when:

You have only one algorithm (YAGNI).
The algorithms are trivial (one line of code).
The logic is tightly coupled and unlikely to change.

12. When NOT To Use It

3 Green Flags (USE STRATEGY)

Multiple Algorithms: You have 3+ ways to perform the same operation.
Runtime Selection: You need to choose the algorithm at runtime.
Likely to Grow: The number of algorithms will increase over time.

3 Red Flags (AVOID STRATEGY)

Single Algorithm: You only have one way to perform the operation.
Trivial Variation: The difference is a single configuration value.

// BAD: Over-engineered strategy
interface DiscountStrategy { public function calculate($order): float; }
class TenPercentDiscount implements DiscountStrategy { /* ... */ }
class TwentyPercentDiscount implements DiscountStrategy { /* ... */ }

// GOOD: Simple configuration
$discount = match($level) {
    'basic' => 0.10,
    'premium' => 0.20,
    default => 0,
};

Tightly Coupled Algorithms: The algorithms share most of their logic.

13. Common Mistakes

1. Strategy Overload (Too Many Strategies)

// BAD: Creating strategies for everything
class AddOneStrategy implements CalculateStrategy { /* ... */ }
class AddTwoStrategy implements CalculateStrategy { /* ... */ }
// 100 strategies for every possible value

Problem: You're creating strategies for trivial variations.

Fix: Use configuration or simple conditionals for trivial variations.

2. Strategy Interface Bloated

// BAD: Bloated interface
interface Strategy
{
    public function execute(): void;
    public function validate(): bool;
    public function getPriority(): int;
    public function getDescription(): string;
    public function getKey(): string;
    public function getConfig(): array;
    public function canExecute(): bool;
    public function onSuccess(): void;
    public function onFailure(): void;
    public function rollback(): void;
}

Problem: Many strategies don't need all these methods.

Fix: Keep the interface focused. Use composition for optional behaviors.

3. Strategy Selection Logic in Client

// BAD: Client decides which strategy
if ($order->country === 'USA') {
    $strategy = new USAStrategy();
} elseif ($order->country === 'Canada') {
    $strategy = new CanadaStrategy();
} else {
    $strategy = new InternationalStrategy();
}

Problem: The strategy selection logic is still in the client.

Fix: Use a factory or resolver to encapsulate the selection logic.

4. Using Strategy for Simple Conditionals

// BAD: Strategy for a simple switch
interface NotificationStrategy { public function send(): void; }
class EmailStrategy implements NotificationStrategy { /* ... */ }
class SmsStrategy implements NotificationStrategy { /* ... */ }

// GOOD: Simple config
$channels = match($preference) {
    'email' => new EmailChannel(),
    'sms' => new SmsChannel(),
    default => new DefaultChannel(),
};

Problem: You're over-engineering simple logic.

Fix: Use the Strategy Pattern only when the logic is complex or likely to grow.

5. Not Handling Strategy Selection

// BAD: Null pointer when no strategy selected
class ShippingCalculator
{
    private ?ShippingStrategy $strategy;

    public function calculate(Order $order): float
    {
        return $this->strategy->calculate($order); // Null if not set!
    }
}

Problem: The strategy might be null.

Fix: Set a default strategy or handle the null case.

public function calculate(Order $order): float
{
    if (!$this->strategy) {
        $this->strategy = new DefaultStrategy();
    }
    return $this->strategy->calculate($order);
}

14. Frequently Asked Interview Questions

Beginner/Intermediate

Q: What is the Strategy Pattern?
A: A behavioral design pattern that enables selecting an algorithm's implementation at runtime by defining a family of algorithms and making them interchangeable.
Q: What are the main participants in the Strategy Pattern?
A: The Strategy Interface, Concrete Strategies, and the Context class.
Q: How does the Strategy Pattern differ from the Factory Pattern?
A: The Factory Pattern creates objects. The Strategy Pattern defines algorithms and makes them interchangeable.
Q: When would you use the Strategy Pattern instead of if-else statements?
A: When you have multiple algorithms for the same task, the algorithms are complex, and the number is likely to grow.
Q: How does Laravel use the Strategy Pattern?
A: In authentication guards, filesystem drivers, queue drivers, notification channels, and validation rules.

Senior/Architect

Q: Explain the difference between the Strategy Pattern and the State Pattern.
A: Both use composition, but they solve different problems. Strategy is about algorithms that are interchangeable. State is about behavior that changes based on state, and the state itself manages the transitions.
Q: How do you handle strategy selection in a large application?
A: Use a Strategy Factory or Resolver that encapsulates the selection logic. The selection can be based on configuration, request parameters, or the object's state.
Q: What's the relationship between the Strategy Pattern and the Dependency Inversion Principle?
A: The Strategy Pattern is an implementation of DIP. The context depends on the abstraction (Strategy Interface), not on concrete strategies.
Q: How do you test a class that uses the Strategy Pattern?
A: You can test the context with mock strategies. You can test each strategy independently. You can test the selection logic (factory) separately.
Q: What's the performance impact of using the Strategy Pattern?
A: Minimal. There's a slight overhead from method calls and object creation, but it's negligible compared to the benefits of maintainability and flexibility.

15. Interactive Practice Challenge

The Requirement

You're building a Notification Delivery System for your SaaS application. The current code uses massive conditionals to handle different notification channels.

The Code (POOR DESIGN)

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

use App\Models\Notification;
use App\Models\User;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Log;
use Illuminate\Support\Facades\Http;
use Twilio\Rest\Client;

class NotificationService
{
    private array $config;

    public function __construct()
    {
        $this->config = config('services');
    }

    public function send(Notification $notification, User $user): array
    {
        $results = [];
        $channels = $user->notification_preferences ?? ['email'];

        foreach ($channels as $channel) {
            if ($channel === 'email') {
                try {
                    Mail::to($user->email)->send(new \App\Mail\NotificationMessage($notification));
                    $results['email'] = ['success' => true];
                    Log::info('Email sent', ['user' => $user->id, 'notification' => $notification->id]);
                } catch (\Exception $e) {
                    $results['email'] = ['success' => false, 'error' => $e->getMessage()];
                    Log::error('Email failed', ['error' => $e->getMessage()]);
                }
            } elseif ($channel === 'sms') {
                try {
                    $twilio = new Client(
                        config('services.twilio.sid'),
                        config('services.twilio.token')
                    );
                    $twilio->messages->create(
                        $user->phone,
                        [
                            'from' => config('services.twilio.from'),
                            'body' => $notification->content,
                        ]
                    );
                    $results['sms'] = ['success' => true];
                    Log::info('SMS sent', ['user' => $user->id, 'notification' => $notification->id]);
                } catch (\Exception $e) {
                    $results['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,
                    ]);
                    $results['slack'] = ['success' => true];
                    Log::info('Slack sent', ['user' => $user->id, 'notification' => $notification->id]);
                } catch (\Exception $e) {
                    $results['slack'] = ['success' => false, 'error' => $e->getMessage()];
                    Log::error('Slack failed', ['error' => $e->getMessage()]);
                }
            } elseif ($channel === 'push') {
                try {
                    $pushService = new \App\Services\PushService();
                    $pushService->send($user->device_token, $notification->title, $notification->content);
                    $results['push'] = ['success' => true];
                } catch (\Exception $e) {
                    $results['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,
                        ],
                    ]);
                    $results['webhook'] = ['success' => true];
                } catch (\Exception $e) {
                    $results['webhook'] = ['success' => false, 'error' => $e->getMessage()];
                }
            } else {
                Log::warning('Unknown channel: ' . $channel);
            }
        }

        return $results;
    }
}

The Challenges

New requirements are piling up:

"We need to add Telegram channel."
"We need to add Microsoft Teams channel."
"We need to add WhatsApp channel."
"We need to add push notifications for mobile apps."
"We need to implement rate limiting per channel."
"We need to retry failed notifications with exponential backoff."
"We need to track notification delivery status in the database."
"We need to send notifications in bulk with batching."

The current code is already unmaintainable. Adding more channels will make it impossible.

Your Task

Refactor this system using the Strategy Pattern. Specifically:

Define a NotificationStrategy interface with methods like send(), supports(), getRateLimit(), getRetryDelay().
Create strategy implementations for each channel:
- EmailStrategy
- SmsStrategy
- SlackStrategy
- PushStrategy
- WebhookStrategy
- Add TelegramStrategy, TeamsStrategy, WhatsAppStrategy as new channels.
Implement a NotificationManager (context) that:
- Holds a collection of strategies.
- Delegates sending to the appropriate strategies.
- Handles batching and rate limiting.
- Implements retry logic with exponential backoff.
Implement a StrategyFactory or StrategyResolver that selects strategies based on user preferences.
Add logging and tracking without duplicating logic across strategies.

Questions to Consider

How should you handle shared logic (logging, tracking) across strategies?
How do you implement rate limiting without duplicating code?
How do you handle retries? Should it be in the strategy or the context?
How do you implement batching for bulk notifications?
How do you test each strategy independently?
How do you handle strategies that require different configuration?

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

16. Final Mental Model

To keep it simple, memorize these three sentences:

One-sentence definition: The Strategy Pattern defines a family of algorithms, encapsulates each one, and makes them interchangeable at runtime.
One-sentence intuition: Instead of writing if-else for every behavior, encapsulate each behavior in its own class and inject the one you need.
One-sentence decision rule: If you have multiple algorithms for the same task and the number is likely to grow, use the Strategy Pattern to avoid conditional hell.

17. Related Concepts

SOLID Principles

Open/Closed: Strategy is the practical implementation of OCP.
Single Responsibility: Each strategy has one job.
Liskov Substitution: All strategies are substitutable.
Dependency Inversion: Context depends on strategy interface.
Interface Segregation: Strategy interfaces are focused.

Design Patterns

Factory Pattern: Often used with Strategy to create strategies.
State Pattern: Similar structure, different intent (state vs algorithm).
Command Pattern: Encapsulates a request as an object.
Decorator Pattern: Can wrap strategies to add behavior.
Chain of Responsibility: Similar but passes through a chain.

Laravel Internals

Authentication Guards: Strategy pattern for auth types.
Filesystem Drivers: Strategy pattern for storage types.
Queue Drivers: Strategy pattern for queue types.
Notification Channels: Strategy pattern for notification types.
Validation Rules: Strategy pattern for validation types.

Enterprise Patterns

Strategy Pattern: The enterprise pattern itself.
Policy Pattern: Similar concept in enterprise systems.
Rule Pattern: For business rules that vary.
Algorithm Pattern: For interchangeable algorithms.

Final Thoughts

The Strategy Pattern is one of the most powerful tools in your OOP toolbox. It's the antidote to the Conditional Apocalypse. It's the pattern that turns massive if-else blocks into clean, extensible, and testable code.

Every time you find yourself writing a long if-else or switch statement, ask yourself: "Is this an algorithm that could be extracted into a strategy?"

Remember: The Strategy Pattern isn't about avoiding conditionals entirely. It's about moving the conditionals to the right place (the factory or resolver) and encapsulating the algorithms in their own classes.

Github: Strategy Pattern Practice Labs

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