You start simple. A user is allowed to purchase a premium item if they are active. Easy—you write a quick Eloquent scope. But three months later, the business team changes the rules. Now, a user can only buy that item if they are active, have a verified email, have spent at least $500 in the last 90 days, and are not flagged for suspicious activity.

Suddenly, your code becomes littered with long chains of Eloquent scopes in your queries, and worse, identical blocks of if-else statements in your PHP services to check the exact same logic for already-loaded models.

This is where the codebase starts to smell. We are violating the Single Responsibility Principle, duplicating rules, and creating a maintenance nightmare. To fix this, developers often reach for complex design patterns that end up overengineering the solution, violating the KISS (Keep It Simple, Stupid) principle.

But there is a elegant, highly practical pattern that solves this perfectly without breaking a sweat: The Specification Pattern.

Previous article in refactoring category: https://codecraftdiary.com/2026/06/15/laravel-event-driven-architecture/

The Real-World Problem: The “Premium Customer” Mess

Let’s look at a concrete example. Imagine an e-commerce platform where we need to determine if a customer qualifies for a VIP Discount.

The business rules for a VIP customer are:

1. The account must be active.
2. The user must have a verified email.
3. They must have made at least 5 orders in total.
4. They must not be on our fraud blacklist.

The Naive Laravel Approach

Typically, you see developers solving this in two ways. First, they write a massive query in a controller or service:

// In a Controller or Service
$vipUsers = User::query()
    ->where('is_active', true)
    ->whereNotNull('email_verified_at')
    ->whereHas('orders', function ($query) {
        $query->where('status', 'completed');
    }, '>=', 5)
    ->whereDoesntHave('flags', function ($query) {
        $query->where('type', 'fraud');
    })
    ->get();

// In a Controller or Service
$vipUsers = User::query()
    ->where('is_active', true)
    ->whereNotNull('email_verified_at')
    ->whereHas('orders', function ($query) {
        $query->where('status', 'completed');
    }, '>=', 5)
    ->whereDoesntHave('flags', function ($query) {
        $query->where('type', 'fraud');
    })
    ->get();

This works fine for fetching data from the database. But what happens when you already have a User instance in memory—say, inside a Job or an Event Listener—and you need to check if this specific user qualifies?

You end up duplicating the logic in pure PHP:

public function qualifiesForVipDiscount(User $user): bool
{
    return $user->is_active 
        && $user->email_verified_at !== null
        && $user->orders()->where('status', 'completed')->count() >= 5
        && !$user->flags()->where('type', 'fraud')->exists();
}

public function qualifiesForVipDiscount(User $user): bool
{
    return $user->is_active 
        && $user->email_verified_at !== null
        && $user->orders()->where('status', 'completed')->count() >= 5
        && !$user->flags()->where('type', 'fraud')->exists();
}

Why this breaks the KISS principle:

• Duplication: If the fraud rule changes, you have to find and rewrite both the SQL/Eloquent logic and the in-memory PHP logic.
• Model Bloat: Shoving this into the User model makes it a “God Object” over time.
• Hidden Rules: Your business logic is trapped inside technical database implementation details.

Enter the Specification Pattern

The Specification Pattern solves this by turning a business rule into a first-class citizen—a single, isolated, reusable class.

A strict specification pattern can sometimes get overly complex with abstract syntax trees and custom expression builders. To keep it KISS-compliant, we are going to build a pragmatic version tailored for modern PHP 8.5+ and Laravel.

Let’s define a simple interface for our specifications:

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

interface Specification
{
    /**
     * Check if a given object satisfies the specification in-memory.
     */
    public function isSatisfiedBy(mixed $candidate): bool;

    /**
     * Apply the specification directly to an Eloquent query builder.
     */
    public function apply(Builder $query): void;
}

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

interface Specification
{
    /**
     * Check if a given object satisfies the specification in-memory.
     */
    public function isSatisfiedBy(mixed $candidate): bool;

    /**
     * Apply the specification directly to an Eloquent query builder.
     */
    public function apply(Builder $query): void;
}

Implementing the Specification

Let’s build our IsVipCustomer specification. Instead of writing abstract logic, we put our exact four business rules inside this class.

namespace App\Specifications;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

class IsVipCustomer implements Specification
{
    public function isSatisfiedBy(mixed $candidate): bool
    {
        if (!$candidate instanceof User) {
            return false;
        }

        return $candidate->is_active
            && $candidate->email_verified_at !== null
            && $candidate->orders->where('status', 'completed')->count() >= 5
            && !$candidate->flags->contains('type', 'fraud');
    }

    public function apply(Builder $query): void
    {
        $query->where('is_active', true)
            ->whereNotNull('email_verified_at')
            ->whereHas('orders', function ($q) {
                $q->where('status', 'completed');
            }, '>=', 5)
            ->whereDoesntHave('flags', function ($q) {
                $q->where('type', 'fraud');
            });
    }
}

namespace App\Specifications;

use App\Models\User;
use Illuminate\Database\Eloquent\Builder;

class IsVipCustomer implements Specification
{
    public function isSatisfiedBy(mixed $candidate): bool
    {
        if (!$candidate instanceof User) {
            return false;
        }

        return $candidate->is_active
            && $candidate->email_verified_at !== null
            && $candidate->orders->where('status', 'completed')->count() >= 5
            && !$candidate->flags->contains('type', 'fraud');
    }

    public function apply(Builder $query): void
    {
        $query->where('is_active', true)
            ->whereNotNull('email_verified_at')
            ->whereHas('orders', function ($q) {
                $q->where('status', 'completed');
            }, '>=', 5)
            ->whereDoesntHave('flags', function ($q) {
                $q->where('type', 'fraud');
            });
    }
}

Notice how clean this is. The technical details of how we determine a VIP customer are encapsulated in exactly one file.

Making It Truly Useful: Combining Specifications

Where this pattern completely demolishes standard refactoring approaches is when business requirements change or combine. What if we want to find users who are VIP Customers AND are Located in the EU (for tax or shipping promotions)?

Instead of writing a third massive scope, we can create a simple composition layer. Let’s create an AndSpecification:

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

class AndSpecification implements Specification
{
    private array $specifications;

    public function __construct(Specification ...$specifications)
    {
        $this->specifications = $specifications;
    }

    public function isSatisfiedBy(mixed $candidate): bool
    {
        foreach ($this->specifications as $spec) {
            if (!$spec->isSatisfiedBy($candidate)) {
                return false;
            }
        }
        return true;
    }

    public function apply(Builder $query): void
    {
        foreach ($this->specifications as $spec) {
            $spec->apply($query);
        }
    }
}

namespace App\Specifications;

use Illuminate\Database\Eloquent\Builder;

class AndSpecification implements Specification
{
    private array $specifications;

    public function __construct(Specification ...$specifications)
    {
        $this->specifications = $specifications;
    }

    public function isSatisfiedBy(mixed $candidate): bool
    {
        foreach ($this->specifications as $spec) {
            if (!$spec->isSatisfiedBy($candidate)) {
                return false;
            }
        }
        return true;
    }

    public function apply(Builder $query): void
    {
        foreach ($this->specifications as $spec) {
            $spec->apply($query);
        }
    }
}

Putting It Into Practice (Where It Pays Off)

Let’s look at how this simplifies our daily Laravel tasks. We’ll look at a Controller (database querying) and a Service/Job (in-memory validation).

Scenario A: Querying the Database

Inside your Admin Dashboard controller, you need to list all VIP customers from the EU to send them a special newsletter.

namespace App\Http\Controllers;

use App\Models\User;
use App\Specifications\AndSpecification;
use App\Specifications\IsVipCustomer;
use App\Specifications\IsLocatedInEU;

class VipNewsletterController extends Controller
{
    public function __invoke()
    {
        // Define the composite rule
        $vipInEuSpec = new AndSpecification(
            new IsVipCustomer(),
            new IsLocatedInEU()
        );

        // Apply it directly to the query
        $query = User::query();
        $vipInEuSpec->apply($query);
        
        $users = $query->paginate(30);

        return view('admin.vip-newsletter', compact('users'));
    }
}

namespace App\Http\Controllers;

use App\Models\User;
use App\Specifications\AndSpecification;
use App\Specifications\IsVipCustomer;
use App\Specifications\IsLocatedInEU;

class VipNewsletterController extends Controller
{
    public function __invoke()
    {
        // Define the composite rule
        $vipInEuSpec = new AndSpecification(
            new IsVipCustomer(),
            new IsLocatedInEU()
        );

        // Apply it directly to the query
        $query = User::query();
        $vipInEuSpec->apply($query);
        
        $users = $query->paginate(30);

        return view('admin.vip-newsletter', compact('users'));
    }
}

Scenario B: In-Memory Domain Validation

Now imagine a completely different part of the app. A user clicks “Claim VIP Reward”. The user is already logged in, so we already have the $user instance loaded in memory. We don’t want to hit the database with complex heavy joins again if we can avoid it.

namespace App\Http\Controllers;

use App\Specifications\IsVipCustomer;
use Illuminate\Http\Request;

class RewardController extends Controller
{
    public function claim(Request $request, IsVipCustomer $vipSpec)
    {
        $user = $request->user();

        // Check the exact same business rule in-memory
        if (!$vipSpec->isSatisfiedBy($user)) {
            return response()->json([
                'error' => 'You do not qualify for this reward.'
            ], 403);
        }

        // Process reward...
        return response()->json(['success' => 'Reward claimed!']);
    }
}

namespace App\Http\Controllers;

use App\Specifications\IsVipCustomer;
use Illuminate\Http\Request;

class RewardController extends Controller
{
    public function claim(Request $request, IsVipCustomer $vipSpec)
    {
        $user = $request->user();

        // Check the exact same business rule in-memory
        if (!$vipSpec->isSatisfiedBy($user)) {
            return response()->json([
                'error' => 'You do not qualify for this reward.'
            ], 403);
        }

        // Process reward...
        return response()->json(['success' => 'Reward claimed!']);
    }
}

Why This is NOT Overengineering

If you look at the code above, a skeptic might say: “Why did we create three classes when a couple of Eloquent scopes could do the trick?”

Here is why this approach honors the KISS principle when dealing with real complexity:

1. The “Single Source of Truth” rule: If the marketing team changes the definition of a VIP customer to require 10 orders instead of 5, you change one number in one class. Your controllers, jobs, and models remain completely untouched.
2. Database vs. Memory consistency: Standard Eloquent scopes cannot be run on a regular PHP collection or an already-loaded model without triggering fresh SQL queries. The Specification Pattern bridges this gap natively.
3. Impeccable Testability: Testing complex business logic mixed with controllers is painful. Testing a Specification class is a pure unit test. You pass a mock user, assert true or false, and you’re done in milliseconds.

public function test_user_with_insufficient_orders_is_not_vip()
{
    $user = new User(['is_active' => true, 'email_verified_at' => now()]);
    $user->setRelation('orders', collect()); // 0 orders
    $user->setRelation('flags', collect());

    $spec = new IsVipCustomer();

    $this->assertFalse($spec->isSatisfiedBy($user));
}

public function test_user_with_insufficient_orders_is_not_vip()
{
    $user = new User(['is_active' => true, 'email_verified_at' => now()]);
    $user->setRelation('orders', collect()); // 0 orders
    $user->setRelation('flags', collect());

    $spec = new IsVipCustomer();

    $this->assertFalse($spec->isSatisfiedBy($user));
}

Summary: When to Use It

Don’t use this pattern for simple things like User::where('role', 'admin'). That would be overengineering.

Reach for the Specification Pattern when:

• A business rule is dynamic and changes often based on business requirements.
• You need to use the exact same rule for both database filtering and in-memory validation.
• You need to combine multiple business rules dynamically depending on the context (e.g., matching different combinations of criteria for user segmentation).

By encapsulating volatile business logic into isolated specifications, you keep your models thin, your controllers clean, and your application incredibly adaptive to future changes. It’s Clean Architecture at its most practical level.

The post The Specification Pattern in Laravel: Refactoring Complex Business Rules appeared first on CodeCraft Diary.

This is the classic “Fat Controller” symptom. It makes your code fragile, nearly impossible to unit test, and violates the Single Responsibility Principle. But how do you solve this without introducing unnecessary enterprise-grade complexity? The answer lies in Event-Driven Architecture, kept simple and practical.

Previous article in this category: https://codecraftdiary.com/2026/05/25/state-pattern-vs-enums-in-modern-php/

The Hidden Cost of Tight Coupling

Consider a typical registration process in a Laravel application:

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());

    // Tightly coupled dependencies
    Mail::to($user)->send(new WelcomeEmail($user));
    Log::info('User registered: ' . $user->id);
    Analytics::track('user_signup', ['id' => $user->id]);
    Newsletter::subscribe($user->email);

    return response()->json(['message' => 'Success'], 201);
}

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());

    // Tightly coupled dependencies
    Mail::to($user)->send(new WelcomeEmail($user));
    Log::info('User registered: ' . $user->id);
    Analytics::track('user_signup', ['id' => $user->id]);
    Newsletter::subscribe($user->email);

    return response()->json(['message' => 'Success'], 201);
}

This code is intuitive, yet architecturally toxic. The controller is burdened with infrastructure knowledge. If your Newsletter API slows down, your user registration experiences lag. If the Mail service throws an exception, the entire request fails, potentially causing data inconsistency or frustration. You have created a brittle system where the success of a core operation depends on four secondary services.

The KISS Philosophy: Events and Listeners

The KISS (Keep It Simple, Stupid) principle dictates that we should avoid over-engineering. In Laravel, you don’t need a massive message broker like RabbitMQ or Kafka to achieve decoupling. Laravel’s built-in Event system is perfect for 95% of use cases.

Events act as an intermediary layer. Your controller simply broadcasts the fact that an action occurred, and various listeners react independently.

1. Defining the Event

Think of an event as a “data transfer object” that carries necessary context.

class UserRegistered
{
    public function __construct(public User $user) {}
}

class UserRegistered
{
    public function __construct(public User $user) {}
}

2. The Lean Controller

Now, look at how the controller looks after refactoring:

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());
    
    // Announce the action
    UserRegistered::dispatch($user);

    return response()->json(['message' => 'Success'], 201);
}

public function register(RegisterRequest $request)
{
    $user = User::create($request->validated());
    
    // Announce the action
    UserRegistered::dispatch($user);

    return response()->json(['message' => 'Success'], 201);
}

By decoupling, the controller is now focused solely on persistence and orchestration, not on the side effects.

3. Implementing Asynchronous Listeners

The true power of events in Laravel emerges when you utilize background processing. By implementing the ShouldQueue interface, you move the heavy lifting away from the HTTP request cycle.

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event)
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

class SendWelcomeEmail implements ShouldQueue
{
    public function handle(UserRegistered $event)
    {
        Mail::to($event->user)->send(new WelcomeEmail($event->user));
    }
}

Why This Architecture Scales

When you embrace events, you gain more than just cleaner controllers; you gain system resilience:

1. Fault Tolerance: If your Newsletter service is temporarily unavailable, the listener can automatically retry the task without affecting the user’s registration.
2. Performance: The user receives a 201 response immediately, while secondary tasks (like analytics) run in the background.
3. Extensibility: Need to add a “Push Notification” when a user registers? Just create a new listener. You don’t need to touch the registration controller logic at all, which eliminates the risk of regression bugs.
4. Testing Contracts: You can now test the registration process by asserting that the UserRegistered event was fired, without needing to mock complex external mail or log services.

Sandbox Example

Theory is one thing, but code in action speaks louder. [Here you can see a live example] of what EventDispatcher looks like in an isolated environment and try out how easy it is to add a new listener without changing the core logic.

Try this sandbox example by yourself: https://onlinephp.io/c/1f7b2

Managing Complexity: The “Event Hell” Warning

While events are powerful, they are not a silver bullet. An excess of events—or “Event Hell”—can lead to a “spaghetti” flow where the execution path is impossible to track.

Follow these best practices to maintain sanity:

• Don’t Over-Abstract: If a piece of code is used only in one place and will never change, don’t create an event. A simple function call is more readable.
• Focus on Side Effects: Events are for post-processing. Do not use events for core logic that must happen synchronously for the application to function.
• Descriptive Naming: Use past-tense names (OrderPlaced, InvoiceGenerated). This clearly signifies that the action has already been successfully committed to the database.

Deep Dive: Events vs. Model Observers

A frequent question is: “When should I use Eloquent Observers instead of Events?”

Eloquent Observers are strictly tied to database lifecycle events (e.g., created, updated, deleted). They are excellent when the side effect is always tied to a database change. Events, however, are more abstract. They represent business domain actions. An event like UserLoggedIn or OrderShipped is much more meaningful than a generic updated observer. Choose Events for business intent; use Observers for low-level database consistency.

Handling Failures in Background Jobs

When you move to ShouldQueue, you must plan for failure. In Laravel, you can define how your listeners handle retries:

public $tries = 3;
public $backoff = 60; // Wait 60 seconds between retries

public $tries = 3;
public $backoff = 60; // Wait 60 seconds between retries

This ensures that temporary outages (like a flickering API connection) don’t result in lost data.

Final Thoughts

Refactoring to an event-driven design is not about making your code “fancy.” It is about durability. By insulating your core controllers from volatile external dependencies, you create a codebase that is easier to debug, faster to test, and significantly more adaptable to future requirements. Start small: identify one noisy side effect in your largest controller, and move it into a listener today. Your future self—and your servers—will thank you.

The post Beyond Fat Controllers: Mastering Event-Driven Decoupling in Laravel appeared first on CodeCraft Diary.

• 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.