State Pattern

Also Known As

TL;DR

Explanation

The State pattern models an object whose behaviour changes based on its current state by delegating to a State object. Each concrete state implements the same interface, and the context simply forwards calls to the current state. Transitioning between states is handled by the state objects themselves or the context. This replaces sprawling if/switch chains on a status field with polymorphism, follows Open/Closed Principle (new states = new classes, not new branches), and localises state-specific behaviour. In PHP, common examples include order workflows, connection states, and document approval processes.

Common Misconception

Why It Matters

Common Mistakes

• Implementing state as a string or integer flag with switch statements — the anti-pattern the State pattern replaces.
• State classes with too much business logic — they should manage transitions and delegate business logic to the context.
• Not preventing invalid transitions — every state should only allow transitions to valid next states.
• Overusing State pattern for objects with 2-3 states where a simple boolean or enum suffices.

Code Examples

// Switch on status string — grows with every new state:
function handleOrder(Order $o): void {
    switch ($o->status) {
        case 'pending': /* ... */ break;
        case 'paid': /* ... */ break;
        case 'shipped': /* ... */ break;
        // Each new status requires modifying this switch
    }
}

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

class PendingState implements OrderState {
    public function pay(Order $o): void    { $o->setState(new PaidState()); }
    public function ship(Order $o): void   { throw new \LogicException('Pay first'); }
    public function cancel(Order $o): void { $o->setState(new CancelledState()); }
}

class PaidState implements OrderState {
    public function pay(Order $o): void    { throw new \LogicException('Already paid'); }
    public function ship(Order $o): void   { $o->setState(new ShippedState()); }
    public function cancel(Order $o): void { $o->setState(new RefundingState()); }
}

References

• ↗ https://refactoring.guru/design-patterns/state

Tags

Related Terms