PHP 状态模式讲解和代码示例

<?php

namespace RefactoringGuru\State\RealWorld;

/**
 * State Design Pattern
 *
 * Intent: lets an object alter its behavior when its internal state changes. It
 * appears as if the object changed its class.
 */

/**
 * Invoice State Interface
 *
 * This interface defines the contract that all invoice states must implement.
 * It represents the State interface in the State pattern, ensuring that all
 * concrete states provide implementations for all possible events/transitions.
 *
 * The interface defines all possible events that can occur in the invoice
 * lifecycle, regardless of whether a particular state can handle them. This
 * approach ensures consistency across all states and makes the system more
 * maintainable.
 */
interface InvoiceState
{
    public function finalize(): void;
    public function pay(): void;
    public function cancel(): void;
    public function void(): void;
    public function getName(): string;
}


/**
 * Abstract Base State class
 *
 * This abstract class implements the InvoiceState interface and provides
 * default implementations for all state transition methods. The default
 * behavior is to throw exceptions for invalid transitions, following the "fail-
 * fast" principle.
 *
 * This approach allows concrete states to only override the methods for
 * transitions they actually support, keeping the code clean and focused. Any
 * attempt to perform an invalid transition will result in a clear exception
 * rather than silent failure.
 *
 * The abstract class also maintains a reference to the context (Invoice)
 * object, which is needed for performing state transitions.
 */
abstract class BaseInvoiceState implements InvoiceState
{
     /**
      * Reference to the context object (Invoice)
      *
      * Each state needs access to the context to perform state transitions.
      * This creates a bidirectional relationship between the state and context.
      */
    protected $invoice;

    public function __construct(Invoice $invoice)
    {
        $this->invoice = $invoice;
    }


    /**
     * Default implementation for finalize event
     *
     * By default, finalize is not allowed in most states. Only states that
     * support this transition will override this method.
     *
     * @throws InvalidStateTransitionException
     */
    public function finalize(): void
    {
        throw new InvalidStateTransitionException("Cannot finalize invoice in " . $this->getName() . " state");
    }

    /**
     * Default implementation for pay event
     *
     * By default, payment is not allowed in most states. Only states that
     * support this transition will override this method.
     *
     * @throws InvalidStateTransitionException
     */
    public function pay(): void
    {
        throw new InvalidStateTransitionException("Cannot pay invoice in " . $this->getName() . " state");
    }

    /**
     * Default implementation for cancel event
     *
     * By default, cancellation is not allowed in most states. Only states that
     * support this transition will override this method.
     *
     * @throws InvalidStateTransitionException
     */
    public function cancel(): void
    {
        throw new InvalidStateTransitionException("Cannot cancel invoice in " . $this->getName() . " state");
    }


    /**
     * Default implementation for void event
     *
     * By default, voiding is not allowed in most states. Only states that
     * support this transition will override this method.
     *
     * @throws InvalidStateTransitionException
     */
    public function void(): void
    {
        throw new InvalidStateTransitionException("Cannot void invoice in " . $this->getName() . " state");
    }

    /**
     * Abstract method to get the state name
     *
     * Each concrete state must implement this method to return its name. This
     * is used for logging, debugging, and display purposes.
     *
     * @return string The name of the current state
     */
    abstract public function getName(): string;
}

/**
 * Each Concrete State corresponds to a specific state.
 *
 * This Concrete State Represents a draft invoice.
 *
 * This is the initial state of every invoice. In this state, the invoice is
 * still being prepared and can only be finalized to move to the Open state. No
 * other operations are allowed in this state.
 */
class DraftInvoiceState extends BaseInvoiceState
{
    /**
     * Handle finalize event
     *
     * This is the only valid transition from Draft state. When an invoice is
     * finalized, it transitions to the Open state where it can be paid, voided,
     * or cancelled.
     */
    public function finalize(): void
    {
        echo "Invoice #{$this->invoice->getId()} finalized - changing from Draft to Open\n";
        $this->invoice->setState(new OpenInvoiceState($this->invoice));
    }

    public function getName(): string
    {
        return 'draft';
    }
}


/**
 * This Concrete State Represents an open invoice.
 *
 * This state represents an invoice that has been finalized and is ready for
 * processing. From this state, the invoice can be:
 * - Paid (moves to Paid state)
 * - Voided (moves to Void state)
 * - Cancelled (moves to Uncollectable state)
 */
class OpenInvoiceState extends BaseInvoiceState
{
    /**
     * Handle pay event
     *
     * When payment is received, the invoice transitions to the Paid state. This
     * is a terminal state - no further operations are allowed.
     */
    public function pay(): void
    {
        echo "Invoice #{$this->invoice->getId()} paid - changing from Open to Paid\n";
        $this->invoice->setState(new PaidInvoiceState($this->invoice));
    }

    /**
     * Handle void event
     *
     * When an invoice is voided, it transitions to the Void state. This is a
     * terminal state - no further operations are allowed.
     */
    public function void(): void
    {
        echo "Invoice #{$this->invoice->getId()} voided - changing from Open to Void\n";
        $this->invoice->setState(new VoidInvoiceState($this->invoice));
    }

    /**
     * Handle cancel event
     *
     * When an invoice is cancelled, it transitions to the Uncollectable state.
     * From Uncollectable, the invoice can still be paid or voided.
     */
    public function cancel(): void
    {
        echo "Invoice #{$this->invoice->getId()} cancelled - changing from Open to Uncollectable\n";
        $this->invoice->setState(new UncollectableInvoiceState($this->invoice));
    }

    public function getName(): string
    {
        return 'open';
    }
}

/**
 * This Concrete State Represents a paid invoice.
 *
 * This is a terminal state representing a paid invoice. Once an invoice is
 * paid, no further state transitions are allowed. All event methods use the
 * default implementation which throws exceptions.
 */
class PaidInvoiceState extends BaseInvoiceState
{
    public function getName(): string
    {
        return 'paid';
    }
}

/**
 * This Concrete State Represents a void invoice.
 *
 * This is a terminal state representing a voided invoice. Once an invoice is
 * voided, no further state transitions are allowed. All event methods use the
 * default implementation which throws exceptions.
 */
class VoidInvoiceState extends BaseInvoiceState
{
    public function getName(): string
    {
        return 'void';
    }
}

/**
 * This Concrete State Represents a collectable invoice.
 *
 * This state represents an invoice that has been cancelled but can still be
 * recovered. From this state, the invoice can be:
 * - Paid (moves to Paid state)
 * - Voided (moves to Void state)
 *
 * This provides a way to handle invoices that were cancelled but later can be
 * collected or definitively written off.
 */
class UncollectableInvoiceState extends BaseInvoiceState
{
    /**
     * Handle pay event
     *
     * Even though the invoice was cancelled, payment can still be received.
     * This transitions the invoice to the Paid state.
     */
    public function pay(): void
    {
        echo "Invoice #{$this->invoice->getId()} paid - changing from Uncollectable to Paid\n";
        $this->invoice->setState(new PaidInvoiceState($this->invoice));
    }

    /**
     * Handle void event
     *
     * If the invoice is definitively uncollectable, it can be voided. This
     * transitions the invoice to the Void state.
     */
    public function void(): void
    {
        echo "Invoice #{$this->invoice->getId()} voided - changing from Uncollectable to Void\n";
        $this->invoice->setState(new VoidInvoiceState($this->invoice));
    }

    public function getName(): string
    {
        return 'uncollectable';
    }
}

/**
 * Context class - Invoice
 *
 * This is the context class in the State pattern. It maintains a reference to
 * the current state object and delegates all state-specific behavior to the
 * current state. The context is unaware of the specific state classes and
 * interacts with them through the abstract InvoiceState interface.
 *
 * The context also maintains the invoice's data (id, amount, etc.) that remains
 * constant regardless of the state.
 */
class Invoice
{
    private $id;
    private $amount;

    /**
     * Current state object
     *
     * This is the key component of the State pattern. The context maintains a
     * reference to the current state object and delegates all state-specific
     * operations to this object.
     *
     * @var InvoiceState
     */
    private $state;

    private $createdAt;

    /**
     * Constructor
     *
     * Creates a new invoice. The invoice always starts in the Draft state as
     * per business requirements.
     */
    public function __construct(int $id, float $amount)
    {
        $this->id = $id;
        $this->amount = $amount;
        $this->createdAt = new \DateTime();
        // Initial state is draft This is where the State pattern begins - we
        // set the initial state
        $this->state = new DraftInvoiceState($this);
    }

    public function getId(): int
    {
        return $this->id;
    }


    /**
     * Set the current state
     *
     * This method is called by state objects to transition to a new state. It's
     * the mechanism that allows the State pattern to work - states can change
     * the context's state by calling this method.
     *
     * @param InvoiceState $state The new state object
     */
    public function setState(InvoiceState $state)
    {
        $this->state = $state;
    }

    /**
     * Get the current state object
     *
     * @return InvoiceState
     */
    public function getState(): InvoiceState
    {
        return $this->state;
    }

    /**
     * Get the current state name
     *
     * This is a convenience method that delegates to the current state object.
     *
     * @return string
     */
    public function getStateName(): string
    {
        return $this->state->getName();
    }

    /**
     * Event method: finalize
     *
     * This method delegates the finalize operation to the current state. This
     * is the core of the State pattern - the context doesn't know how to handle
     * the operation, so it delegates to the current state.
     */
    public function finalize()
    {
        $this->state->finalize();
    }

    /**
     * Event method: pay
     *
     * This method delegates the pay operation to the current state. The
     * behavior will vary depending on the current state.
     */
    public function pay()
    {
        $this->state->pay();
    }

    /**
     * Event method: cancel
     *
     * This method delegates the cancel operation to the current state. The
     * behavior will vary depending on the current state.
     */
    public function cancel()
    {
        $this->state->cancel();
    }

    /**
     * Event method: void
     *
     * This method delegates the void operation to the current state. The
     * behavior will vary depending on the current state.
     */
    public function void()
    {
        $this->state->void();
    }

    /**
     * Get invoice information
     *
     * Returns an array with all invoice information including current state.
     * This is useful for debugging, logging, or API responses.
     *
     * @return array
     */
    public function getInfo(): array
    {
        return [
            'id' => $this->id,
            'amount' => $this->amount,
            'state' => $this->getStateName(),
            'created_at' => $this->createdAt->format('Y-m-d H:i:s')
        ];
    }
}


/**
 * Custom exception for invalid state transitions
 *
 * This exception is thrown when an invalid state transition is attempted. It
 * provides clear error messages about what transition was attempted and why it
 * failed.
 */
class InvalidStateTransitionException extends \Exception
{
    /**
     * Constructor
     *
     * @param string $message Error message
     * @param int $code Error code
     * @param \Exception|null $previous Previous exception
     */
    public function __construct($message = "", $code = 0, \Exception $previous = null)
    {
        parent::__construct($message, $code, $previous);
    }
}


/**
 * ============================================================================
 * USAGE EXAMPLE AND DEMONSTRATION
 * ============================================================================
 *
 * The following code demonstrates how to use the State pattern implementation
 * with various scenarios that show all possible state transitions.
 */

try {
    echo "=== Invoice State Pattern Demo ===\n\n";

    // Create a new invoice (starts in draft state)
    $invoice = new Invoice(1001, 1500.00);
    echo "Created invoice: " . json_encode($invoice->getInfo()) . "\n\n";

    // Scenario 1: Draft -> Open -> Paid
    echo "--- Scenario 1: Draft -> Open -> Paid ---\n";
    $invoice->finalize(); // Draft -> Open
    echo "Current state: " . $invoice->getStateName() . "\n";

    $invoice->pay(); // Open -> Paid
    echo "Current state: " . $invoice->getStateName() . "\n";

    // Try to pay again (should fail)
    try {
        $invoice->pay();
    } catch (InvalidStateTransitionException $e) {
        echo "Expected error: " . $e->getMessage() . "\n";
    }

    echo "\n--- Scenario 2: Draft -> Open -> Void ---\n";
    $invoice2 = new Invoice(1002, 750.00);
    $invoice2->finalize(); // Draft -> Open
    $invoice2->void(); // Open -> Void
    echo "Invoice 2 state: " . $invoice2->getStateName() . "\n";

    echo "\n--- Scenario 3: Draft -> Open -> Uncollectable -> Paid ---\n";
    $invoice3 = new Invoice(1003, 2000.00);
    $invoice3->finalize(); // Draft -> Open
    $invoice3->cancel(); // Open -> Uncollectable
    echo "Invoice 3 state: " . $invoice3->getStateName() . "\n";

    $invoice3->pay(); // Uncollectable -> Paid
    echo "Invoice 3 final state: " . $invoice3->getStateName() . "\n";

    echo "\n--- Scenario 4: Draft -> Open -> Uncollectable -> Void ---\n";
    $invoice4 = new Invoice(1004, 500.00);
    $invoice4->finalize(); // Draft -> Open
    $invoice4->cancel(); // Open -> Uncollectable
    $invoice4->void(); // Uncollectable -> Void
    echo "Invoice 4 final state: " . $invoice4->getStateName() . "\n";

    echo "\n--- Error Scenario: Invalid transition ---\n";
    $invoice5 = new Invoice(1005, 300.00);
    try {
        $invoice5->pay(); // Try to pay draft invoice (should fail)
    } catch (InvalidStateTransitionException $e) {
        echo "Expected error: " . $e->getMessage() . "\n";
    }

    echo "\n--- State Information ---\n";
    echo "Invoice 1: " . json_encode($invoice->getInfo()) . "\n";
    echo "Invoice 2: " . json_encode($invoice2->getInfo()) . "\n";
    echo "Invoice 3: " . json_encode($invoice3->getInfo()) . "\n";
    echo "Invoice 4: " . json_encode($invoice4->getInfo()) . "\n";
    echo "Invoice 5: " . json_encode($invoice5->getInfo()) . "\n";
} catch (InvalidStateTransitionException $e) {
    echo "Error: " . $e->getMessage() . "\n";
}

=== Invoice State Pattern Demo ===

Created invoice: {"id":1001,"amount":1500,"state":"draft","created_at":"2025-07-12 13:14:15"}

--- Scenario 1: Draft -> Open -> Paid ---
Invoice #1001 finalized - changing from Draft to Open
Current state: open
Invoice #1001 paid - changing from Open to Paid
Current state: paid
Expected error: Cannot pay invoice in paid state

--- Scenario 2: Draft -> Open -> Void ---
Invoice #1002 finalized - changing from Draft to Open
Invoice #1002 voided - changing from Open to Void
Invoice 2 state: void

--- Scenario 3: Draft -> Open -> Uncollectable -> Paid ---
Invoice #1003 finalized - changing from Draft to Open
Invoice #1003 cancelled - changing from Open to Uncollectable
Invoice 3 state: uncollectable
Invoice #1003 paid - changing from Uncollectable to Paid
Invoice 3 final state: paid

--- Scenario 4: Draft -> Open -> Uncollectable -> Void ---
Invoice #1004 finalized - changing from Draft to Open
Invoice #1004 cancelled - changing from Open to Uncollectable
Invoice #1004 voided - changing from Uncollectable to Void
Invoice 4 final state: void

--- Error Scenario: Invalid transition ---
Expected error: Cannot pay invoice in draft state

--- State Information ---
Invoice 1: {"id":1001,"amount":1500,"state":"paid","created_at":"2025-07-12 13:14:15"}
Invoice 2: {"id":1002,"amount":750,"state":"void","created_at":"2025-07-12 13:14:15"}
Invoice 3: {"id":1003,"amount":2000,"state":"paid","created_at":"2025-07-12 13:14:15"}
Invoice 4: {"id":1004,"amount":500,"state":"void","created_at":"2025-07-12 13:14:15"}
Invoice 5: {"id":1005,"amount":300,"state":"draft","created_at":"2025-07-12 13:14:15"}