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.

A backed enum in PHP is an enumeration whose cases are explicitly backed by a scalar value, specifically either an int or a string. Introduced in PHP 8.1, backed enums allow enumeration cases to be serialized and deserialized by associating a unique, literal scalar value with each case.

​
Syntax and Declaration

To create a backed enum, you must declare the scalar type immediately following the enum name. Every case within the enum must be explicitly assigned a value matching that type. 
// String-backed enum
enum HttpMethod: string {
    case GET = 'GET';
    case POST = 'POST';
    case PUT = 'PUT';
    case DELETE = 'DELETE';
}

// Integer-backed enum
enum HttpStatusCode: int {
    case OK = 200;
    case CREATED = 201;
    case NOT_FOUND = 404;
}

​
Technical Constraints

  1. Strict Typing: The backing type must be exactly int or string. Union types (e.g., int|string) are strictly prohibited.
  2. Homogeneity: An enum cannot mix integer and string values. All cases must resolve to the declared backing type.
  3. Uniqueness: Every case value must be unique within the enumeration. Two cases cannot share the same scalar value.
  4. Literal Values: The assigned values must be literals or literal expressions. Variables, function calls, or dynamic expressions are not allowed.

​
Accessing the Backing Value

Backed enums expose their underlying scalar value via a read-only public property named value. 
$method = HttpMethod::POST;
echo $method->value; // Outputs: POST

$status = HttpStatusCode::NOT_FOUND;
echo $status->value; // Outputs: 404

​
Deserialization Methods

Backed enums implicitly implement the BackedEnum interface, which provides two static methods for converting a scalar value back into an enum instance.

​
from()

The from() method takes a scalar value and returns the corresponding enum case. If the value does not exist within the enum, it throws a ValueError. 
$method = HttpMethod::from('GET'); 
// Returns HttpMethod::GET

$invalid = HttpMethod::from('PATCH'); 
// Throws ValueError: "PATCH" is not a valid backing value for enum "HttpMethod"

​
tryFrom()

The tryFrom() method operates similarly to from(), but instead of throwing an exception on failure, it returns null. This is the preferred method when handling untrusted input. 
$status = HttpStatusCode::tryFrom(200); 
// Returns HttpStatusCode::OK

$invalidStatus = HttpStatusCode::tryFrom(500); 
// Returns null

​
The BackedEnum Interface

Under the hood, the PHP engine ensures that all backed enums implement the BackedEnum interface, which extends the base UnitEnum interface. The engine defines it as follows: 
interface BackedEnum extends UnitEnum {
    public static function from(int|string $value): static;
    public static function tryFrom(int|string $value): ?static;
}
The read-only $value property is not declared within the BackedEnum interface itself, as PHP interfaces traditionally cannot declare properties. Instead, the PHP engine automatically exposes the $value property directly on the instantiated backed enum objects. Because it extends UnitEnum, a backed enum also inherits the cases() method, which returns an array of all cases defined in the enumeration in their order of declaration.
Master PHP with Deep Grasping Methodology!Learn More