create-state

State Pattern Generator

Creates State pattern infrastructure for objects that change behavior based on internal state.

When to Use

Scenario	Example
Object behavior varies by state	Order (pending, paid, shipped)
Many conditionals based on state	Document workflow
State-specific transitions	Subscription lifecycle
Finite state machines	Payment processing

Component Characteristics

StateInterface

• Defines available actions
• Returns new state after transition
• Encapsulates state-specific behavior

Context

• Holds current state
• Delegates actions to state
• Manages state transitions

Concrete States

• Implement behavior for each state
• Handle valid/invalid transitions
• Return appropriate next state

---

Generation Process

Step 1: Analyze State Machine

Determine:

• All possible states
• Actions/transitions between states
• Which actions are valid per state
• Terminal states (no outgoing transitions)

Step 2: Generate State Components

Path: src/Domain/{BoundedContext}/State/

1. {Name}StateInterface.php — State contract with all actions
2. Abstract{Name}State.php — Base class with default (invalid) implementations
3. {StateName}State.php — Concrete state for each state (PendingState, PaidState, etc.)
4. {Name}StateFactory.php — Factory for reconstitution from storage

Path: src/Domain/{BoundedContext}/Exception/

5. InvalidStateTransitionException.php — Exception for invalid transitions

Step 3: Update Entity

Path: src/Domain/{BoundedContext}/Entity/

Update entity to use state pattern with delegation methods.

Step 4: Generate Tests

Path: tests/Unit/Domain/{BoundedContext}/State/

1. {StateName}StateTest.php — Test each concrete state
2. {Entity}StateTransitionTest.php — Test full state machine

---

File Placement

Component	Path
State Interface	src/Domain/{BoundedContext}/State/
Concrete States	src/Domain/{BoundedContext}/State/
State Factory	src/Domain/{BoundedContext}/State/
Entity with State	src/Domain/{BoundedContext}/Entity/
Exception	src/Domain/{BoundedContext}/Exception/
Unit Tests	tests/Unit/Domain/{BoundedContext}/State/

---

Naming Conventions

Component	Pattern	Example
Interface	{Name}StateInterface	OrderStateInterface
Abstract State	Abstract{Name}State	AbstractOrderState
Concrete State	{StateName}State	PendingState, PaidState
Factory	{Name}StateFactory	OrderStateFactory
Exception	InvalidStateTransitionException	InvalidStateTransitionException
Test	{ClassName}Test	PendingStateTest

---

Quick Template Reference

State Interface

interface {Name}StateInterface
{
    public function getName(): string;
    public function {action1}({Context} $context): self;
    public function {action2}({Context} $context): self;
    public function canTransitionTo(self $state): bool;
    /** @return array<string> */
    public function allowedTransitions(): array;
}

Abstract State

abstract readonly class Abstract{Name}State implements {Name}StateInterface
{
    public function {action1}({Context} $context): {Name}StateInterface
    {
        throw InvalidStateTransitionException::actionNotAllowed('{action1}', $this->getName());
    }

    public function canTransitionTo({Name}StateInterface $state): bool
    {
        return in_array($state->getName(), $this->allowedTransitions(), true);
    }
}

Concrete State

final readonly class {StateName}State extends Abstract{Name}State
{
    public function getName(): string
    {
        return '{state_name}';
    }

    public function {action1}({Context} $context): {Name}StateInterface
    {
        $context->recordEvent(new {Event}($context->id()));
        return new {NextState}State();
    }

    public function allowedTransitions(): array
    {
        return ['{next_state_1}', '{next_state_2}'];
    }
}

State Factory

final class {Name}StateFactory
{
    public static function fromName(string $name): {Name}StateInterface
    {
        return match ($name) {
            'pending' => new PendingState(),
            'confirmed' => new ConfirmedState(),
            default => throw new \InvalidArgumentException("Unknown state: $name"),
        };
    }
}

---

Usage Example

// Entity with state
$order = new Order($id, $customerId, $items);
$order->confirm();  // Pending -> Confirmed
$order->pay();      // Confirmed -> Paid
$order->ship();     // Paid -> Shipped
$order->deliver();  // Shipped -> Delivered

// Check state
if ($order->isInState('delivered')) {
    // ...
}

// Reconstitute from storage
$state = OrderStateFactory::fromName($row['state']);
$order = new Order($id, $customerId, $items, $state);

---

State Diagram Template

┌──────────┐  action1   ┌──────────┐  action2   ┌──────────┐
│  State1  │───────────▶│  State2  │───────────▶│  State3  │
└────┬─────┘            └────┬─────┘            └──────────┘
     │                       │
     │ cancel                │ cancel
     │                       │
     ▼                       ▼
┌──────────┐            ┌──────────┐
│Cancelled │            │Cancelled │
└──────────┘            └──────────┘

---

Anti-patterns to Avoid

Anti-pattern	Problem	Solution
Mutable States	Shared state pollution	Make states readonly
God State	One state handles all	Split into specific states
Missing Transitions	Silent failures	Throw on invalid action
State in Entity	Mixed concerns	Extract to State classes
No Factory	Hard to reconstitute	Add StateFactory

---

References

For complete PHP templates and examples, see:

• references/templates.md — State interface, abstract, concrete templates
• references/examples.md — Order state machine example and tests