Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

An enumeration (Enum) in PHP is a restricted, custom data type that encapsulates a fixed, limited set of possible values. Introduced in PHP 8.1, enums are built on top of the class and object engine. Each enum case is a singleton instance of the enum itself, meaning they are passed by value (where the value is an object identifier/handle) and pass strict identity checks (===).

​
Unit Enums

A Basic or “Unit” Enum contains cases that have no scalar equivalent. They are identified solely by their name. 
enum Status {
    case Draft;
    case Published;
    case Archived;
}

$status = Status::Draft;

​
Backed Enums

A Backed Enum assigns a scalar value (int or string) to each case. The backing type must be explicitly declared in the enum definition, and all cases must be of that specific type. 
enum HttpCode: int {
    case Ok = 200;
    case NotFound = 404;
    case InternalError = 500;
}

enum Direction: string {
    case North = 'N';
    case South = 'S';
    case East = 'E';
    case West = 'W';
}

​
Built-in Properties and Methods

Enums provide several native properties and methods for introspection and instantiation:
  • name: A read-only property available on all enums that returns the string name of the case.
  • value: A read-only property available only on Backed Enums that returns the assigned scalar value.
  • ::cases(): A static method that returns a packed array of all defined cases in declaration order (the exact order they are defined in the source code).
  • ::from(int|string $value): A static method (Backed Enums only) that returns the enum instance corresponding to the scalar value. Throws a ValueError if the value does not exist.
  • ::tryFrom(int|string $value): A static method (Backed Enums only) that returns the enum instance, or null if the scalar value is not found.
$code = HttpCode::from(404); // Returns HttpCode::NotFound
$name = $code->name;         // 'NotFound'
$value = $code->value;       // 404

$invalid = HttpCode::tryFrom(999); // Returns null

​
Constants, Methods, Interfaces, and Traits

Enums share a class-like architecture, allowing them to declare their own class constants, methods, implement interfaces, and use traits. When using traits, a critical restriction applies: traits used by enums must not declare any properties, because enums are strictly stateless. Attempting to use a trait with properties will result in a fatal error. Within an enum method, self and static refer to the enum type, while $this refers to the specific case instance. 
interface Formattable {
    public function format(): string;
}

trait Loggable {
    // Traits used in enums must not declare properties
    public function log(): void {
        echo "Logging case: " . $this->name;
    }
}

enum Role: string implements Formattable {
    use Loggable;

    case Admin = 'admin';
    case User = 'user';

    // Enums can declare class constants
    public const DEFAULT_ROLE = self::User;

    public function format(): string {
        return strtoupper($this->value);
    }

    public static function defaultRole(): self {
        return self::DEFAULT_ROLE;
    }
}

​
Technical Restrictions

Because enums are designed to represent immutable, stateless values, the PHP engine enforces several strict limitations:
  1. No Instantiation: Enums cannot be instantiated using the new keyword.
  2. No State: Enums cannot declare properties.
  3. No Inheritance: Enums cannot extend classes or other enums, and cannot be extended. They are implicitly final.
  4. Restricted Magic Methods: Magic methods related to state or instantiation (like __get, __set, __clone, __sleep, __wakeup) are forbidden. Furthermore, enums are strictly forbidden from implementing __toString() or the Stringable interface. They are permitted to implement __call, __callStatic, __invoke, and __debugInfo.
  5. Literal Expressions: Backed enum values must be strictly literal expressions (e.g., 200 or 'admin'). Variables, constants, and constant expressions (such as 1 + 1 or SOME_CONSTANT) are entirely unsupported for enum case values.
Master PHP with Deep Grasping Methodology!Learn More