> ## 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.
# PHP Enum
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.
```php theme={"dark"}
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.
```php theme={"dark"}
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.
```php theme={"dark"}
$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.
```php theme={"dark"}
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.
Tired of Poor PHP Skills? Fix That With Deep Grasping!
Learn More
