.PHP File Format – Enums

Declaration

enum Name [: int | : string] [implements Interface {, Interface}]
{
    {case Name [= value]; | constant | method | use Trait;}
}

Pure enums

enum Suit
{
    case Hearts;
    case Diamonds;
    case Clubs;
    case Spades;
}

function pick(Suit $s): void { /* ... */ }

pick(Suit::Clubs);    // OK
pick('Clubs');        // TypeError

echo Suit::Clubs->name;  // Clubs

• Cases are written as Name::Case. They are class constants and case names are case-sensitive.
• Each case has a read-only name property holding the case name.
• A case is a singleton, so Suit::Clubs === Suit::Clubs is true. Suit::Clubs instanceof Suit is true.
• Comparing enum values with < or > is always false.
• An enum may have no cases at all. It is valid but not useful.

Backed enums

A backed enum gives each case a scalar value of one type, for storing in a database or sending over a network.

enum Status: string
{
    case Active = 'active';
    case Hidden = 'hidden';
}

Status::Active->value;           // 'active'
Status::from('hidden');          // Status::Hidden
Status::from('x');               // ValueError
Status::tryFrom('x');            // null
Status::tryFrom('x') ?? Status::Active;

• The backing type follows the name with a colon. Only int and string are allowed, and a union is not.
• Every case of a backed enum must have a value, and no two cases may share one. Pure and backed cases cannot be mixed. There is no auto-numbering.
• The value must be a constant expression. Before PHP 8.2 it had to be a literal or literal expression.
• value is read-only, and a reference to it cannot be taken.

Methods and members

interface Colourful
{
    public function colour(): string;
}

enum Suit implements Colourful
{
    use Rectangle;

    case Hearts;
    case Spades;

    const Wild = self::Spades;

    public function colour(): string
    {
        return match ($this) {
            self::Hearts => 'Red',
            self::Spades => 'Black',
        };
    }

    public static function fromChar(string $c): self
    {
        return match ($c) {
            'H' => self::Hearts,
            'S' => self::Spades,
        };
    }
}

Every enum also has a static method cases(), from the UnitEnum interface. It returns all the cases in declaration order, and is empty for an enum with no cases.

Differences from classes

Enum cases hold no state. The following are not allowed:

• Constructors and destructors.
• Inheritance. An enum cannot extend or be extended.
• Static or object properties, other than the implicit name and value.
• Cloning a case.
• Magic methods other than __call, __callStatic and __invoke. Before PHP 8.6 that excludes __debugInfo.
• Creating a case with new or through Reflection.

An enum must be declared before it is used, or be autoloaded. A case is an object, so it cannot be an array key, though it can be a WeakMap or SplObjectStorage key.

Enums in constant expressions

A case can be used as a value wherever a constant expression is allowed: property, static variable and parameter defaults, and global and class constants.

class Connection
{
    public function __construct(public Status $status = Status::Active) {}
}

Reading a property of a case in a constant expression was added in PHP 8.2: const VALUE = Status::Active->value;. Using [] on a case is not allowed in a constant expression, because it would run ArrayAccess code.

Serialisation

• serialize() uses its own format, E:11:"Suit:Hearts";, and unserialize() returns the same singleton object.
• A backed enum encodes to JSON as its value. A pure enum cannot be encoded, and json_encode() fails, unless it implements JsonSerializable.
• var_export() writes the case by name, as \Suit::Hearts.