• Pending
• Paid
• Shipped
• Cancelled

When PHP introduced native Enums, they became the perfect fit for this kind of state modeling. They are type-safe, database-friendly, and much cleaner than arbitrary strings spread across the codebase.

For simple workflows, Enums are often exactly the right solution. The problem begins when states stop being just labels and start accumulating behavior.

This article explores where Enums work well, where they start breaking down, and how the State Pattern can help without introducing unnecessary complexity or framework-heavy abstractions.

Previous articlet in Refactoring cattegory: https://codecraftdiary.com/2026/05/02/mastering-value-objects-in-php/

Enums Are Excellent — Until They Aren’t

For simple workflows, Enums are clean and maintainable.

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

This is ideal when states are primarily used for:

• Filtering and querying data
• Display logic and badges in UI
• Basic validation
• API serialization
• Database persistence

Problems start appearing when business rules become state-dependent. A common first step is adding helper methods directly into the Enum:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function canBeCancelled(): bool
    {
        return match($this) {
            self::Pending, self::Paid => true,
            self::Shipped, self::Cancelled => false,
        };
    }
}

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function canBeCancelled(): bool
    {
        return match($this) {
            self::Pending, self::Paid => true,
            self::Shipped, self::Cancelled => false,
        };
    }
}

This is still perfectly reasonable and respects the KISS principle.

But over time, workflows tend to evolve. A cancellation process may eventually require refunding payments, restocking inventory, notifying external systems, creating audit logs, or dispatching events.

At that point, the Enum slowly stops being a simple value object and starts becoming a workflow engine.

The Hidden Problem: Growing Coupling

Consider how a bloating Enum typically looks in production:

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function cancel(
        Order $order,
        PaymentGateway $gateway,
        InventoryManager $inventory
    ): void {
        match ($this) {
            self::Pending => $order->updateStatus(self::Cancelled),

            self::Paid => $this->executeCancellationWithRefund($order, $gateway, $inventory),

            self::Shipped => throw new LogicException('Cannot cancel a shipped order.'),
            self::Cancelled => throw new LogicException('Order is already cancelled.'),
        };
    }

    private function executeCancellationWithRefund(Order $order, PaymentGateway $gateway, InventoryManager $inventory): void
    {
        $gateway->refund($order->payment_id);
        $inventory->restock($order->items);
        $order->updateStatus(self::Cancelled);
    }
}

enum OrderStatus: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';

    public function cancel(
        Order $order,
        PaymentGateway $gateway,
        InventoryManager $inventory
    ): void {
        match ($this) {
            self::Pending => $order->updateStatus(self::Cancelled),

            self::Paid => $this->executeCancellationWithRefund($order, $gateway, $inventory),

            self::Shipped => throw new LogicException('Cannot cancel a shipped order.'),
            self::Cancelled => throw new LogicException('Order is already cancelled.'),
        };
    }

    private function executeCancellationWithRefund(Order $order, PaymentGateway $gateway, InventoryManager $inventory): void
    {
        $gateway->refund($order->payment_id);
        $inventory->restock($order->items);
        $order->updateStatus(self::Cancelled);
    }
}

The issue here is not the number of lines. The issue is coupling.

The Enum now knows about payment infrastructure, inventory management, business transitions, and side effects. Adding a new state such as PartiallyRefunded now requires modifying a growing conditional structure that centralizes unrelated responsibilities.

This is where applications experience state explosion—the point where transitions and side effects become increasingly difficult to isolate and reason about. At this stage, the code may still look “short,” but it is no longer simple.

The State Pattern: Isolating Behavior

The State Pattern addresses this by moving behavior into dedicated state objects. Instead of one large conditional structure, each state becomes responsible for its own transitions and rules.

1. Define the Workflow Contract

interface OrderState
{
    public function cancel(Order $order): void;
    public function ship(Order $order): void;
    public function toValue(): string;
}

interface OrderState
{
    public function cancel(Order $order): void;
    public function ship(Order $order): void;
    public function toValue(): string;
}

The interface should stay minimal. Only include operations whose behavior actually changes depending on the state.

2. Create Small, Focused State Classes

Each state becomes an isolated, testable component. Look at how clean the responsibilities become:

Pending State

readonly class PendingState implements OrderState
{
    public function cancel(Order $order): void
    {
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Cannot ship an unpaid order.');
    }

    public function toValue(): string
    {
        return 'pending';
    }
}

readonly class PendingState implements OrderState
{
    public function cancel(Order $order): void
    {
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Cannot ship an unpaid order.');
    }

    public function toValue(): string
    {
        return 'pending';
    }
}

Paid State

readonly class PaidState implements OrderState
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function cancel(Order $order): void
    {
        $this->gateway->refund($order->payment_id);
        $this->inventory->restock($order->items);
        
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        $order->transitionTo(new ShippedState());
    }

    public function toValue(): string
    {
        return 'paid';
    }
}

readonly class PaidState implements OrderState
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function cancel(Order $order): void
    {
        $this->gateway->refund($order->payment_id);
        $this->inventory->restock($order->items);
        
        $order->transitionTo(new CancelledState());
    }

    public function ship(Order $order): void
    {
        $order->transitionTo(new ShippedState());
    }

    public function toValue(): string
    {
        return 'paid';
    }
}

Shipped State

readonly class ShippedState implements OrderState
{
    public function cancel(Order $order): void
    {
        throw new LogicException('The order has already been shipped.');
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Order is already shipped.');
    }

    public function toValue(): string
    {
        return 'shipped';
    }
}

readonly class ShippedState implements OrderState
{
    public function cancel(Order $order): void
    {
        throw new LogicException('The order has already been shipped.');
    }

    public function ship(Order $order): void
    {
        throw new LogicException('Order is already shipped.');
    }

    public function toValue(): string
    {
        return 'shipped';
    }
}

Most importantly, adding a new state no longer requires modifying a massive conditional block. This aligns naturally with the Open/Closed Principle.

3. A Pragmatic Hybrid Approach

Completely replacing Enums with raw state objects is often unnecessary in database-driven applications. In practice, the most maintainable approach is a hybrid architecture:

• Enums handle persistence, transport, and API serialization.
• State objects handle business behavior and side effects.

The Enum remains the canonical storage format:

enum OrderStatusEnum: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

enum OrderStatusEnum: string
{
    case Pending = 'pending';
    case Paid = 'paid';
    case Shipped = 'shipped';
    case Cancelled = 'cancelled';
}

Resolving State Behavior Cleanly

Instead of resolving dependencies directly inside the model, a dedicated factory keeps infrastructure concerns isolated from your domain.

readonly class OrderStateFactory
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function make(OrderStatusEnum $status): OrderState
    {
        return match ($status) {
            OrderStatusEnum::Pending => new PendingState(),
            OrderStatusEnum::Paid => new PaidState($this->gateway, $this->inventory),
            OrderStatusEnum::Shipped => new ShippedState(),
            OrderStatusEnum::Cancelled => new CancelledState(),
        };
    }
}

readonly class OrderStateFactory
{
    public function __construct(
        private PaymentGateway $gateway,
        private InventoryManager $inventory,
    ) {}

    public function make(OrderStatusEnum $status): OrderState
    {
        return match ($status) {
            OrderStatusEnum::Pending => new PendingState(),
            OrderStatusEnum::Paid => new PaidState($this->gateway, $this->inventory),
            OrderStatusEnum::Shipped => new ShippedState(),
            OrderStatusEnum::Cancelled => new CancelledState(),
        };
    }
}

Keeping the Model Lightweight

Now, the Order model stays clean and decoupled from infrastructure services. It simply orchestrates the workflow via the factory:

class Order
{
    public OrderStatusEnum $status;
    public int $payment_id;
    public array $items = [];

    public function __construct(
        private readonly OrderStateFactory $stateFactory,
    ) {}

    public function transitionTo(OrderState $state): void
    {
        $this->status = OrderStatusEnum::from($state->toValue());
    }

    public function cancel(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->cancel($this);
    }

    public function ship(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->ship($this);
    }
}

class Order
{
    public OrderStatusEnum $status;
    public int $payment_id;
    public array $items = [];

    public function __construct(
        private readonly OrderStateFactory $stateFactory,
    ) {}

    public function transitionTo(OrderState $state): void
    {
        $this->status = OrderStatusEnum::from($state->toValue());
    }

    public function cancel(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->cancel($this);
    }

    public function ship(): void
    {
        $this->stateFactory
            ->make($this->status)
            ->ship($this);
    }
}

This keeps your persistence simple, business logic isolated, dependencies explicit, and workflows extensible—all without introducing heavy framework abstractions.

Testing Becomes Significantly Easier

One of the biggest advantages of state objects is test isolation. Instead of testing a large Enum with multiple branches and heavy mocking setups, each workflow state can be verified independently:

• PendingStateTest — Verify that cancellation transitions directly to cancelled.
• PaidStateTest — Assert that the payment gateway receives the refund call and inventory is restocked.
• ShippedStateTest — Assert that exceptions are thrown correctly on forbidden actions.

This dramatically reduces test setup complexity and makes transition rules much easier to verify.

When Should You Use Enums vs. State Objects?

Use Enums when:

• The state is primarily a static label.
• Transitions are simple and linear.
• Behavior differences between states are minimal.
• No external services or infrastructure are involved.
• Examples: Blog post status (Draft, Published), user visibility flags, or filtering categories.

Use the State Pattern when:

• Transitions trigger side effects or external APIs.
• States require completely different validation rules.
• Workflows keep expanding with new edge cases.
• Conditional logic (match or if/else) around the same state starts repeating across the codebase.
• Examples: Payment workflows, fulfillment systems, subscription lifecycles, or approval pipelines.

Final Thoughts

Enums are not the enemy. In fact, they are often the best solution for simple state representation.

The real problem starts when business workflows evolve and a single Enum begins accumulating infrastructure dependencies, transition orchestration, side effects, and validation logic. At that point, the issue is no longer code length—it is responsibility density.

The State Pattern is valuable not because it is “more advanced,” but because it isolates change. And in long-lived systems, isolated change is usually what keeps complexity manageable.

The post State Pattern vs. Enums in Modern PHP appeared first on CodeCraft Diary.

If you’ve been following my series on Refactoring & Patterns, you know I’m a fan of the Introduce Parameter Object pattern. But today, I want to go deeper and talk about one of the smallest, yet most powerful building blocks of clean architecture: Value Objects.

Previous article in this category: https://codecraftdiary.com/2026/04/11/fat-controller-laravel-refactor/

The “Price” of Primitive Obsession

Imagine you’re working on an e-commerce platform. You have a Product and a Discount.

public function applyDiscount(float $price, float $discountPercentage):float
{
    if ($discountPercentage < 0 || $discountPercentage > 100) {
        throw new InvalidArgumentException("Invalid discount");
    }

    return $price - ($price * ($discountPercentage / 100));
}

public function applyDiscount(float $price, float $discountPercentage):float
{
    if ($discountPercentage < 0 || $discountPercentage > 100) {
        throw new InvalidArgumentException("Invalid discount");
    }

    return $price - ($price * ($discountPercentage / 100));
}

At first glance, this looks fine. But in a real-world application, that $price is floating around (pun intended) everywhere.

• Is it USD or EUR?
• Does it include VAT?
• What about rounding?

And more importantly: what happens if you accidentally pass $discountPercentage as $price?

PHP won’t complain. Both are floats. You just sold a MacBook for $15.

On top of that, floats introduce precision issues, which makes them a poor choice for financial calculations in the first place.

What Exactly is a Value Object?

A Value Object (VO) is an object that is defined by its value rather than its identity.

Two Value Objects with the same data are considered equal—even if they are different instances.

In modern PHP (8.2+), a well-designed Value Object has three key characteristics:

• Immutability – once created, it cannot change
• Validation – it cannot exist in an invalid state
• Self-documentation – the type clearly expresses intent

A Better Approach: Explicit Domain Types

Let’s refactor the previous example.

final readonly class Price
{
    public function __construct(
        public int $amount, // in cents
        public Currency $currency
    ) {
        if ($this->amount < 0) {
            throw new InvalidPriceException("Price cannot be negative.");
        }
    }

    public function add(Price $other): Price
    {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatchException();
        }

        return new Price($this->amount + $other->amount, $this->currency);
    }

    public function equals(Price $other): bool
    {
        return $this->amount === $other->amount
            && $this->currency === $other->currency;
    }
}

final readonly class Price
{
    public function __construct(
        public int $amount, // in cents
        public Currency $currency
    ) {
        if ($this->amount < 0) {
            throw new InvalidPriceException("Price cannot be negative.");
        }
    }

    public function add(Price $other): Price
    {
        if ($this->currency !== $other->currency) {
            throw new CurrencyMismatchException();
        }

        return new Price($this->amount + $other->amount, $this->currency);
    }

    public function equals(Price $other): bool
    {
        return $this->amount === $other->amount
            && $this->currency === $other->currency;
    }
}

A few important things are happening here:

• Encapsulation – price logic lives inside the Price class
• Type safety – you cannot mix currencies accidentally
• Immutability – every operation returns a new instance
• Precision – using integers avoids float rounding issues

Why This Matters (Especially Today)

With AI-assisted development becoming standard, types matter more than ever.

When you use primitives, tools like GitHub Copilot or ChatGPT have to guess intent.

When you use a Price or EmailAddress object, both humans and AI can:

• understand constraints immediately
• discover available behavior via methods
• avoid invalid states by design

You’re not just writing code—you’re defining a clear contract.

Real-World Refactoring: Email

How often have you written this?

if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {<br>    throw new Exception("Invalid email");<br>}

if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {<br>    throw new Exception("Invalid email");<br>}

If it appears in multiple places, that’s duplication—and a maintenance risk.

Let’s move that logic into a Value Object:

final readonly class EmailAddress
{
    private string $value;

    public function __construct(string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException($value);
        }

        $this->value = strtolower(trim($value));
    }

    public function getDomain(): string
    {
        return substr(strrchr($this->value, "@"), 1);
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

final readonly class EmailAddress
{
    private string $value;

    public function __construct(string $value)
    {
        if (!filter_var($value, FILTER_VALIDATE_EMAIL)) {
            throw new InvalidEmailException($value);
        }

        $this->value = strtolower(trim($value));
    }

    public function getDomain(): string
    {
        return substr(strrchr($this->value, "@"), 1);
    }

    public function __toString(): string
    {
        return $this->value;
    }
}

Now your service layer becomes much cleaner:

// BEFORE
public function registerUser(string $email, string $password) { ... }

// AFTER
public function registerUser(EmailAddress $email, Password $password) { ... }

// BEFORE
public function registerUser(string $email, string $password) { ... }

// AFTER
public function registerUser(EmailAddress $email, Password $password) { ... }

The moment execution reaches registerUser, you already know the email is valid.

Validation is handled at the boundary of your system—not scattered across your codebase.

Logic-Heavy Value Objects

A common mistake is treating Value Objects as simple data containers.

In practice, they should encapsulate behavior related to that data.

Instead of passing:

string $startDate, string $endDate

string $startDate, string $endDate

You can model:

OrderDateRange

OrderDateRange

With methods like:

• overlapsWith()
• isWithinLastMonth()
• getDurationInDays()

This reduces cognitive load in your services and keeps domain logic where it belongs.

When NOT to Use Value Objects

Not everything needs to be a Value Object.

Ask yourself:

• Does this data have validation rules?
• Is it reused in multiple places?
• Does it represent a domain concept (SKU, IBAN, Email, Price)?

If the answer is yes, a Value Object is likely justified.

If you’re building a quick prototype, primitives are fine. Just be aware of the trade-offs.

Performance Considerations

A common concern used to be performance—creating many small objects instead of using primitives.

In modern PHP, object instantiation is highly optimized. The overhead is negligible compared to the cost of bugs caused by invalid states.

More importantly:

• immutable objects are predictable
• they eliminate side effects
• they are naturally safe in concurrent or async contexts

Summary

Refactoring toward Value Objects is one of the most effective ways to improve code quality.

It forces you to think in terms of domain concepts, not just data types.

Practical steps:

• Look at a complex service class
• Find a variable validated in multiple places
• Extract it into a readonly Value Object
• Move related logic into that object

You’ll end up with code that is easier to read, safer to modify, and harder to break.

The post Mastering Value Objects in PHP 8.5+ (2026 Edition) appeared first on CodeCraft Diary.

A controller starts small. Clean. Readable.

Then features get added.

Deadlines hit.

Logic piles up.

And suddenly, you’re staring at a 500-line controller that handles validation, business logic, database writes, API calls, and maybe even a bit of formatting “just for now.”

This is what we call a Fat Controller — and it’s one of the most common maintainability problems in Laravel applications.

In this article, we’ll take a real-world approach and refactor a fat controller into a cleaner, scalable structure using principles inspired by Clean Architecture.

No theory overload. Just practical steps.

Previous Article in this category : https://codecraftdiary.com/2026/03/21/ai-driven-refactoring/

The Problem: A Real Fat Controller Example

Let’s start with something painfully familiar:

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // Validation
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        // Business logic
        $total = 0;

        foreach ($validated['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

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

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

        // Save order
        $order = Order::create([
            'user_id' => $validated['user_id'],
            'total' => $total,
        ]);

        // Save items
        foreach ($validated['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        // External API call
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

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

class OrderController extends Controller
{
    public function store(Request $request)
    {
        // Validation
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        // Business logic
        $total = 0;

        foreach ($validated['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

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

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

        // Save order
        $order = Order::create([
            'user_id' => $validated['user_id'],
            'total' => $total,
        ]);

        // Save items
        foreach ($validated['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        // External API call
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

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

What’s wrong here?

• Controller handles too many responsibilities
• Business logic is not reusable
• Hard to test
• Tight coupling to Eloquent and external APIs
• Changes are risky

Goal: What “Clean” Looks Like

We want to move toward:

• Thin controllers
• Isolated business logic
• Testable services
• Clear boundaries between layers

We’re not going full academic Clean Architecture. We’re applying just enough structure to stay sane.

Step 1: Extract Business Logic into a Service

First, move the core logic out of the controller.

class CreateOrderService
{
    public function handle(array $data): Order
    {
        $total = 0;

        foreach ($data['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

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

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

        $order = Order::create([
            'user_id' => $data['user_id'],
            'total' => $total,
        ]);

        foreach ($data['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

        return $order;
    }
}

class CreateOrderService
{
    public function handle(array $data): Order
    {
        $total = 0;

        foreach ($data['items'] as $item) {
            $product = Product::find($item['id']);

            if (!$product) {
                throw new Exception('Product not found');
            }

            if ($product->stock < $item['quantity']) {
                throw new Exception('Not enough stock');
            }

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

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

        $order = Order::create([
            'user_id' => $data['user_id'],
            'total' => $total,
        ]);

        foreach ($data['items'] as $item) {
            OrderItem::create([
                'order_id' => $order->id,
                'product_id' => $item['id'],
                'quantity' => $item['quantity'],
            ]);
        }

        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);

        return $order;
    }
}

Controller becomes:

class OrderController extends Controller
{
    public function store(Request $request, CreateOrderService $service)
    {
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        $order = $service->handle($validated);

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

class OrderController extends Controller
{
    public function store(Request $request, CreateOrderService $service)
    {
        $validated = $request->validate([
            'user_id' => 'required|exists:users,id',
            'items' => 'required|array',
        ]);

        $order = $service->handle($validated);

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

Improvement:

• Controller is now thin
• Logic is reusable
• Easier to test

But we’re not done yet.

Step 2: Introduce a Data Transfer Object (DTO)

Passing raw arrays is fragile.

Let’s fix that.

class CreateOrderData
{
    public function __construct(
        public int $userId,
        public array $items
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            $data['user_id'],
            $data['items']
        );
    }
}

class CreateOrderData
{
    public function __construct(
        public int $userId,
        public array $items
    ) {}

    public static function fromArray(array $data): self
    {
        return new self(
            $data['user_id'],
            $data['items']
        );
    }
}

Update controller:

$data = CreateOrderData::fromArray($validated);
$order = $service->handle($data);

$data = CreateOrderData::fromArray($validated);
$order = $service->handle($data);

Update service:

public function handle(CreateOrderData $data): Order

public function handle(CreateOrderData $data): Order

Improvement:

• Stronger typing
• Safer refactoring
• Clear contract

Step 3: Decouple External Dependencies

Right now, your service is tightly coupled to:

• Eloquent models
• HTTP client

Let’s extract the webhook logic.

class OrderWebhookService
{
    public function send(Order $order): void
    {
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);
    }
}

class OrderWebhookService
{
    public function send(Order $order): void
    {
        Http::post('https://example.com/webhook', [
            'order_id' => $order->id,
        ]);
    }
}

Inject it:

class CreateOrderService
{
    public function __construct(
        private OrderWebhookService $webhook
    ) {}

    public function handle(CreateOrderData $data): Order
    {
        // logic...

        $this->webhook->send($order);

        return $order;
    }
}

class CreateOrderService
{
    public function __construct(
        private OrderWebhookService $webhook
    ) {}

    public function handle(CreateOrderData $data): Order
    {
        // logic...

        $this->webhook->send($order);

        return $order;
    }
}

Improvement:

• External side effects are isolated
• Easier to mock in tests

Step 4: Make It Testable

Now you can test the service independently:

public function test_it_creates_order()
{
    $service = app(CreateOrderService::class);

    $data = new CreateOrderData(
        userId: 1,
        items: [
            ['id' => 1, 'quantity' => 2],
        ]
    );

    $order = $service->handle($data);

    $this->assertNotNull($order->id);
}

public function test_it_creates_order()
{
    $service = app(CreateOrderService::class);

    $data = new CreateOrderData(
        userId: 1,
        items: [
            ['id' => 1, 'quantity' => 2],
        ]
    );

    $order = $service->handle($data);

    $this->assertNotNull($order->id);
}

Before refactoring, this would require:

• HTTP mocking
• Controller testing
• Complex setup

Now it’s isolated.

Step 5: Optional — Introduce Repositories (Only If Needed)

Don’t overengineer this.

But if your app grows, you might extract:

class ProductRepository
{
    public function find(int $id): ?Product
    {
        return Product::find($id);
    }
}

class ProductRepository
{
    public function find(int $id): ?Product
    {
        return Product::find($id);
    }
}

Then inject it into the service.

When to do this:

• Multiple data sources
• Complex queries
• Domain logic reuse

When NOT to:

• Simple CRUD apps

Before vs After

Common Mistakes to Avoid

1. Moving everything blindly into services

You’ll just create fat services instead of fat controllers.

Keep services focused.

2. Overengineering with too many layers

You don’t need:

• 10 interfaces
• 5 abstractions
• enterprise architecture™

Start simple. Evolve when needed.

3. Ignoring boundaries

Controllers = HTTP
Services = business logic
Models = persistence

Mixing these again = back to chaos.

Key Takeaways

• Fat controllers are a symptom, not the root problem
• The real issue is mixed responsibilities
• Start with service extraction
• Add DTOs for safety
• Isolate side effects (APIs, events)
• Only introduce more abstraction when justified

Final Thought

Clean Architecture in Laravel doesn’t mean rewriting your app into a textbook diagram.

It means one thing:

Making your code easier to change without fear.

And the fastest way to get there?

Start killing your fat controllers — one method at a time.

If this is something you’re dealing with right now, your next step is simple:

Pick your worst controller and extract just one action into a service.

That’s how clean architecture actually starts.

The post Fat Controller Laravel Refactor: Step-by-Step Clean Architecture Guide appeared first on CodeCraft Diary.