PHP 8 Enums Deep Dive: Backed Enums, Methods, and State Machines

Have you ever found yourself using a bunch of constants or strings to represent a fixed set of states, like order statuses or user roles? You might have used class constants, but they lack type safety—any string can be passed, leading to bugs. PHP 8 introduced enums, a first-class language feature that solves this elegantly. Enums allow you to define a type with a finite set of possible values, each being a singleton object. This brings clarity, safety, and expressiveness to your code.

In this deep dive, we'll explore backed enums (with scalar values), adding methods to enums, and implementing state machines. You'll see how enums can replace boolean flags, magic strings, and complex if-else chains. We'll also cover real-world production incidents where enums prevented bugs, and a debugging guide for when things go wrong. By the end, you'll be ready to refactor your legacy code with enums and build robust applications.

What Are PHP Enums?

PHP 8.1 introduced enums as a built-in type. An enum is a special kind of class that can only have a fixed number of instances, called cases. Each case is a singleton object. Enums are perfect for representing a set of possible values that don't change, like days of the week, order statuses, or user roles.

Basic syntax:

``php enum Status { case Pending; case Approved; case Shipped; case Delivered; } ``

You can use an enum as a type hint:

``php function processOrder(Status $status): void { // $status is guaranteed to be one of the four cases } ``

This prevents passing invalid strings like 'pending' or 'shipped'. Enums also have built-in methods like name (returns the case name as a string) and cases() (returns an array of all cases).

<?php

enum Status
{
    case Pending;
    case Approved;
    case Shipped;
    case Delivered;
}

function processOrder(Status $status): void
{
    echo "Processing order with status: " . $status->name . "\n";
}

processOrder(Status::Pending);
// Output: Processing order with status: Pending

// List all cases
foreach (Status::cases() as $case) {
    echo $case->name . "\n";
}
// Output:
// Pending
// Approved
// Shipped
// Delivered

Backed Enums: Mapping to Scalars

Often you need to store enum values in a database or send them via API. Backed enums associate each case with a scalar value (int or string). This is done by adding a type to the enum declaration and assigning values to each case.

``php enum Status: string { case Pending = 'pending'; case Approved = 'approved'; case Shipped = 'shipped'; case Delivered = 'delivered'; } ``

Now each case has a value property. You can create an enum from a backed value using from() (throws ValueError if invalid) or tryFrom() (returns null if invalid).

``php $status = Status::from('pending'); // Returns Status::Pending $status = Status::tryFrom('unknown'); // Returns null ``

Backed enums are ideal for database columns. You can store the scalar value and convert to enum on read.

```php // Storing $stmt->bindValue(':status', $order->status->value);

// Reading $row = $stmt->fetch(); $status = Status::tryFrom($row['status']); ```

This ensures that only valid values are stored and retrieved.

<?php

enum Status: string
{
    case Pending = 'pending';
    case Approved = 'approved';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
}

// Create from value
$status = Status::from('pending');
echo $status->name; // Pending
echo $status->value; // pending

// Safe conversion
$input = 'shipped';
$status = Status::tryFrom($input);
if ($status === null) {
    throw new InvalidArgumentException("Invalid status: $input");
}

// Use in match
$label = match ($status) {
    Status::Pending => 'Order is pending',
    Status::Approved => 'Order approved',
    Status::Shipped => 'Order shipped',
    Status::Delivered => 'Order delivered',
};
echo $label;

Adding Methods to Enums

Enums can have methods, just like classes. This allows you to encapsulate behavior related to the enum. Methods can be instance methods (using $this) or static methods.

Instance methods can access the case's name and value. For example, you can add a label method:

```php enum Status: string { case Pending = 'pending'; case Approved = 'approved'; case Shipped = 'shipped'; case Delivered = 'delivered';

public function label(): string { return match ($this) { self::Pending => 'Pending', self::Approved => 'Approved', self::Shipped => 'Shipped', self::Delivered => 'Delivered', }; }

public function isActive(): bool { return $this === self::Approved || $this === self::Shipped; } }

$status = Status::Pending; echo $status->label(); // Pending echo $status->isActive() ? 'Active' : 'Inactive'; // Inactive ```

Static methods can be used for factory methods or utility functions:

``php echo Status::default(); // Returns Status::Pending ``

Methods make enums more powerful, allowing you to keep related logic together.

<?php

enum Status: string
{
    case Pending = 'pending';
    case Approved = 'approved';
    case Shipped = 'shipped';
    case Delivered = 'delivered';

    public function label(): string
    {
        return match ($this) {
            self::Pending => 'Pending',
            self::Approved => 'Approved',
            self::Shipped => 'Shipped',
            self::Delivered => 'Delivered',
        };
    }

    public function isActive(): bool
    {
        return $this === self::Approved || $this === self::Shipped;
    }

    public static function default(): self
    {
        return self::Pending;
    }
}

$status = Status::Approved;
echo $status->label() . "\n";
echo $status->isActive() ? 'Active' : 'Inactive' . "\n";
echo Status::default()->name;

Implementing a State Machine with Enums

State machines are a common pattern where an object transitions between a finite set of states. Enums are a natural fit. You can define allowed transitions directly in the enum.

Example: Order status state machine.

```php enum OrderStatus: string { case Pending = 'pending'; case Approved = 'approved'; case Shipped = 'shipped'; case Delivered = 'delivered'; case Cancelled = 'cancelled';

public function canTransitionTo(self $newStatus): bool { return match ($this) { self::Pending => in_array($newStatus, [self::Approved, self::Cancelled], true), self::Approved => in_array($newStatus, [self::Shipped, self::Cancelled], true), self::Shipped => $newStatus === self::Delivered, self::Delivered => false, // final state self::Cancelled => false, // final state }; }

public function transitionTo(self $newStatus): self { if (!$this->canTransitionTo($newStatus)) { throw new InvalidTransitionException("Cannot transition from {$this->value} to {$newStatus->value}"); } return $newStatus; } } ```

Now you can safely transition:

``php $status = OrderStatus::Pending; $status = $status->transitionTo(OrderStatus::Approved); // works $status = $status->transitionTo(OrderStatus::Delivered); // throws exception ``

This pattern ensures invalid transitions are caught early.

<?php

class InvalidTransitionException extends \RuntimeException {}

enum OrderStatus: string
{
    case Pending = 'pending';
    case Approved = 'approved';
    case Shipped = 'shipped';
    case Delivered = 'delivered';
    case Cancelled = 'cancelled';

    public function canTransitionTo(self $newStatus): bool
    {
        return match ($this) {
            self::Pending => in_array($newStatus, [self::Approved, self::Cancelled], true),
            self::Approved => in_array($newStatus, [self::Shipped, self::Cancelled], true),
            self::Shipped => $newStatus === self::Delivered,
            self::Delivered, self::Cancelled => false,
        };
    }

    public function transitionTo(self $newStatus): self
    {
        if (!$this->canTransitionTo($newStatus)) {
            throw new InvalidTransitionException("Cannot transition from {$this->value} to {$newStatus->value}");
        }
        return $newStatus;
    }
}

$status = OrderStatus::Pending;
try {
    $status = $status->transitionTo(OrderStatus::Approved);
    echo "Transitioned to: " . $status->value . "\n";
    $status = $status->transitionTo(OrderStatus::Delivered); // will throw
} catch (InvalidTransitionException $e) {
    echo $e->getMessage() . "\n";
}

Enums with Interfaces and Traits

Enums can implement interfaces and use traits, just like classes. This allows you to define common behavior across different enums.

Example: An interface for enums that have a label.

```php interface HasLabel { public function label(): string; }

enum Status: string implements HasLabel { case Pending = 'pending'; case Approved = 'approved';

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

function printLabel(HasLabel $enum): void { echo $enum->label(); } ```

Traits can be used to share method implementations:

```php trait LabelTrait { public function label(): string { return ucfirst($this->value); } }

enum Status: string { use LabelTrait;

case Pending = 'pending'; case Approved = 'approved'; } ```

This promotes code reuse and keeps your enums DRY.

<?php

interface HasLabel
{
    public function label(): string;
}

trait LabelTrait
{
    public function label(): string
    {
        return ucfirst($this->value);
    }
}

enum Status: string implements HasLabel
{
    use LabelTrait;

    case Pending = 'pending';
    case Approved = 'approved';
}

function printLabel(HasLabel $enum): void
{
    echo $enum->label() . "\n";
}

printLabel(Status::Pending);
printLabel(Status::Approved);

Serialization and Database Storage

When working with enums in production, you often need to serialize them (JSON, session) or store them in a database. Backed enums serialize to their scalar value by default when using json_encode:

``php echo json_encode(Status::Pending); // "pending" ``

For non-backed enums, you need to implement JsonSerializable:

```php enum Status implements \JsonSerializable { case Pending; case Approved;

public function jsonSerialize(): string { return $this->name; } } ```

For database storage, use the backed value. With PDO, you can bind the value:

``php $stmt = $pdo->prepare('INSERT INTO orders (status) VALUES (:status)'); $stmt->bindValue(':status', $order->status->value, PDO::PARAM_STR); $stmt->execute(); ``

When reading, convert back:

``php $row = $stmt->fetch(PDO::FETCH_ASSOC); $status = Status::tryFrom($row['status']); if ($status === null) { // handle invalid data } ``

Always validate data from the database, as it may have been corrupted or changed.

<?php

enum Status: string
{
    case Pending = 'pending';
    case Approved = 'approved';
}

// JSON serialization
echo json_encode(Status::Pending) . "\n"; // "pending"

// Database example with PDO
$pdo = new PDO('sqlite::memory:');
$pdo->exec('CREATE TABLE orders (status TEXT)');

$stmt = $pdo->prepare('INSERT INTO orders (status) VALUES (:status)');
$stmt->bindValue(':status', Status::Pending->value, PDO::PARAM_STR);
$stmt->execute();

$stmt = $pdo->query('SELECT status FROM orders');
$row = $stmt->fetch(PDO::FETCH_ASSOC);
$status = Status::tryFrom($row['status']);
echo $status?->name ?? 'Invalid';