⌂ Home ▲ Previous: Objects ▼ Next: Functions
PHP 8 >= 8.1.0
Enumerations are a restricting layer on top of classes and class constants, intended to provide a way to define a closed set of possible values for a type.
<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}
function do_stuff(Suit $s)
{
// ...
}
do_stuff(Suit::Spades);
?>
Enumerations, or enums, allow a developer to define a custom type that is limited to one of a discrete number of possible values. That can be especially helpful when defining a domain model, as it enables “making invalid states unrepresentable”.
Enums appear in many languages with a variety of different features. In PHP, enums are a special kind of object. The Enum itself is a class, and its possible cases are all single-instance objects of that class. That means enum cases are valid objects and may be used anywhere an object may be used, including type checks.
The most popular example of enumerations is the built-in boolean type, which is an enumerated type with legal values true and false. Enums allows developers to define their own arbitrarily robust enumerations.
Example: Enums
<?php
enum SomeEnum
{
case SomeCase;
case OtherCase;
case AnotherCase;
}
print("Information:\n");
var_dump(SomeEnum::SomeCase);
print('Type: ' . gettype(SomeEnum::SomeCase) . PHP_EOL . PHP_EOL);
enum OtherEnum: string
{
case SomeCase = 'some case';
case OtherCase = 'other case';
case AnotherCase = 'another case';
}
print("Information:\n");
var_dump(OtherEnum::OtherCase);
print('Type: ' . gettype(OtherEnum::OtherCase) . PHP_EOL . PHP_EOL);
Result (PHP 8.4):
Information:
enum(SomeEnum::SomeCase)
Type: object
Information:
enum(OtherEnum::OtherCase)
Type: object
Source code: Example
Example: Basic limited values
<?php
enum SortOrder
{
case Asc;
case Desc;
}
function query($fields, $filter, SortOrder $order = SortOrder::Asc)
{
/* ... */
}
?>
The query() function can now proceed safe in the knowledge that $order is guaranteed to be either SortOrder::Asc or SortOrder::Desc. Any other value would have resulted in a TypeError, so no further error checking or testing is needed.
Example: Constant set of states use case
<?php
enum Status
{
case Draft;
case Pending;
case Published;
case SoftDeleted;
case Restored;
case Deleted;
case Revising;
case Accepted;
}
$postStatus = Status::Published;
print("Post status: ");
print_r($postStatus);
$postStatus = Status::Revising;
print("Post status: ");
print_r($postStatus);
print(PHP_EOL);
Result (PHP 8.4):
Post status: Status Enum
(
[name] => Published
)
Post status: Status Enum
(
[name] => Revising
)
Source code: Example
Example: Advanced exclusive values
<?php
enum UserStatus: string
{
case Pending = 'P';
case Active = 'A';
case Suspended = 'S';
case CanceledByUser = 'C';
public function label(): string
{
return match($this) {
self::Pending => 'Pending',
self::Active => 'Active',
self::Suspended => 'Suspended',
self::CanceledByUser => 'Canceled by user',
};
}
}
?>
In this example, a user’s status may be one of, and exclusively, UserStatus::Pending, UserStatus::Active, UserStatus::Suspended, or UserStatus::CanceledByUser. A function can type a parameter against UserStatus and then only accept those four values, period.
All four values have a label() method, which returns a human-readable string. That string is independent of the “machine name” scalar equivalent string, which can be used in, for example, a database field or an HTML select box.
<?php
foreach (UserStatus::cases() as $case) {
printf('<option value="%s">%s</option>\n', $case->value, $case->label());
}
?>
Example: Set of options in the contract
<?php
enum Role: string
{
case BackendDeveloper = 'backend developer';
case FrontendDeveloper = 'frontend developer';
case AutomaticTester = 'automatic tester';
case DevOpsEngineer = 'devops engineer';
public function getLabel(): string
{
return $this->value;
}
}
class Employee
{
public function __construct(
private string $name,
private string $surname,
private Role $role,
) {
}
public function getDescription(): string
{
return "Name: {$this->name}\n"
. "Surname: {$this->surname}\n"
. 'Role: ' . $this->role->getLabel();
}
}
$employee = new Employee('Giuseppe', 'Gandolfini', Role::FrontendDeveloper);
print("Employee of the year:\n" . $employee->getDescription() . PHP_EOL);
Result (PHP 8.4):
Employee of the year:
Name: Giuseppe
Surname: Gandolfini
Role: frontend developer
Source code: Example
Enums are similar to classes, and share the same namespaces as classes, interfaces, and traits. They are also autoloadable the same way. An enum defines a new type, which has a fixed, limited number of possible legal values.
<?php
enum Suit
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
}
?>
This declaration creates a new enumerated type named Suit, which has four and only four legal values: Suit::Hearts, Suit::Diamonds, Suit::Clubs, and Suit::Spades. Variables may be assigned to one of those legal values. A function may be type checked against an enumerated type, in which case only values of that type may be passed.
<?php
function pick_a_card(Suit $suit)
{
/* ... */
}
$val = Suit::Diamonds;
// OK
pick_a_card($val);
// OK
pick_a_card(Suit::Clubs);
// TypeError: pick_a_card(): Argument #1 ($suit) must be of type Suit, string given
pick_a_card('Spades');
?>
An enumeration may have zero or more case definitions, with no maximum. A zero-case enum is syntactically valid, if rather useless.
For enumeration cases, the same syntax rules apply as to any label in PHP.
By default, cases are not intrinsically backed by a scalar value. That is, Suit::Hearts is not equal to "0". Instead, each case is backed by a singleton object of that name. That means that:
<?php
$a = Suit::Spades;
$b = Suit::Spades;
$a === $b; // true
$a instanceof Suit; // true
?>
It also means that enum values are never < or > each other, since those comparisons are not meaningful on objects. Those comparisons will always return false when working with enum values.
This type of case, with no related data, is called a pure case. An enum that contains only pure cases is called a pure enum.
All pure cases are implemented as instances of their enum type. The (enum type) is represented internally as a class.
All cases have a read-only property, name, that is the case-sensitive name of the case itself.
<?php
print Suit::Spades->name;
// prints "Spades"
?>
It is also possible to use the defined() and constant() functions to check for the existence of or read an enum case if the name is obtained dynamically. This is, however, discouraged as using backed enums should work for most use cases.
Example: Basic enums
<?php
enum SomeEnum
{
case SomeCase;
case OtherCase;
case AnotherCase;
}
print("Information:\n");
var_dump(SomeEnum::SomeCase);
print('Type: ' . gettype(SomeEnum::SomeCase) . PHP_EOL);
print('Class: ' . get_class(SomeEnum::SomeCase) . PHP_EOL . PHP_EOL);
print('Enum name property: ' . SomeEnum::SomeCase->name . PHP_EOL . PHP_EOL);
Result (PHP 8.4):
Information:
enum(SomeEnum::SomeCase)
Type: object
Class: SomeEnum
Enum name property: SomeCase
Source code: Example
By default, enumerated cases have no scalar equivalent. They are simply singleton objects. However, there are ample cases where an enumerated case needs to be able to round-trip to a database or similar datastore, so having a built-in scalar (and thus trivially serializable) equivalent defined intrinsically is useful.
To define a scalar equivalent for an enumeration, the syntax is as follows:
<?php
enum Suit: string
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
}
?>
A case that has a scalar equivalent is called a backed case, as it is “backed” by a simpler value. An enum that contains all backed cases is called a backed enum. A backed enum may contain only backed cases. A pure enum may contain only pure cases.
A backed enum may be backed by types of int or string, and a given enumeration supports only a single type at a time (that is, no union of int|string). If an enumeration is marked as having a scalar equivalent, then all cases must have a unique scalar equivalent defined explicitly. There are no auto-generated scalar equivalents (e.g., sequential integers). Backed cases must be unique; two backed enum cases may not have the same scalar equivalent. However, a constant may refer to a case, effectively creating an alias.
The equivalent values may be a constant scalar expression. Prior to PHP 8.2.0, the equivalent values had to be literals or literal expressions. This means that constants and constant expressions were not supported. That is, 1 + 1 was allowed, but 1 + SOME_CONST was not.
Backed cases have an additional read-only property, value, which is the value specified in the definition.
<?php
print Suit::Clubs->value;
// Prints "C"
?>
In order to enforce the value property as read-only, a variable cannot be assigned as a reference to it. That is, the following throws an error:
<?php
$suit = Suit::Clubs;
$ref = &$suit->value;
// Error: Cannot acquire reference to property Suit::$value
?>
Backed enums implement an internal BackedEnum interface, which exposes two additional methods:
from(int|string): self will take a scalar and return the corresponding enum case. If one is not found, it will throw a ValueError. This is mainly useful in cases where the input scalar is trusted and a missing enum value should be considered an application-stopping error.
tryFrom(int|string): ?self will take a scalar and return the corresponding enum case. If one is not found, it will return null. This is mainly useful in cases where the input scalar is untrusted and the caller wants to implement their own error handling or default-value logic.
The from() and tryFrom() methods follow standard weak/strong typing rules. In weak typing mode, passing an integer or string is acceptable and the system will coerce the value accordingly. Passing a float will also work and be coerced. In strict typing mode, passing an integer to from() on a string-backed enum (or vice versa) will result in a TypeError, as will a float in all circumstances. All other parameter types will throw a TypeError in both modes.
<?php
$record = get_stuff_from_database($id);
print $record['suit'];
$suit = Suit::from($record['suit']);
// Invalid data throws a ValueError: "X" is not a valid scalar value for enum "Suit"
print $suit->value;
$suit = Suit::tryFrom('A') ?? Suit::Spades;
// Invalid data returns null, so Suit::Spades is used instead.
print $suit->value;
?>
Manually defining a from() or tryFrom() method on a Backed Enum will result in a fatal error.
Example: Backed enums
<?php
enum SomeBackedEnum: string
{
case SomeCase = 'some case';
case OtherCase = 'other case';
case AnotherCase = 'another case';
}
print("Information:\n");
var_dump(SomeBackedEnum::SomeCase);
print('Type: ' . gettype(SomeBackedEnum::SomeCase) . PHP_EOL . PHP_EOL);
print('Enum case name property: ' . SomeBackedEnum::SomeCase->name . PHP_EOL);
print('Enum case value: ' . SomeBackedEnum::SomeCase->value . PHP_EOL);
print('Enum case from value: ');
var_export(SomeBackedEnum::SomeCase->from('some case'));
print(PHP_EOL);
print('Enum case from right value: ');
var_export(SomeBackedEnum::SomeCase->tryFrom('some case'));
print(PHP_EOL);
print('Enum case try from wrong value: ');
var_export(SomeBackedEnum::SomeCase->tryFrom('wrong case'));
print(PHP_EOL . PHP_EOL);
enum OtherBackedEnum: int
{
case SomeCase = 10;
case OtherCase = 20;
case AnotherCase = 30;
}
print("Information:\n");
var_dump(OtherBackedEnum::OtherCase);
print('Type: ' . gettype(OtherBackedEnum::OtherCase) . PHP_EOL . PHP_EOL);
print('Enum case name property: ' . OtherBackedEnum::OtherCase->name . PHP_EOL);
print('Enum case value: ' . OtherBackedEnum::OtherCase->value . PHP_EOL);
print('Enum case from value: ');
var_export(OtherBackedEnum::OtherCase->from(20));
print(PHP_EOL);
print('Enum case try right from right value: ');
var_export(OtherBackedEnum::OtherCase->tryFrom(20));
print(PHP_EOL);
print('Enum case try right wrong right value: ');
var_export(OtherBackedEnum::OtherCase->tryFrom(40));
print(PHP_EOL . PHP_EOL);
Result (PHP 8.4):
Information:
enum(SomeBackedEnum::SomeCase)
Type: object
Enum case name property: SomeCase
Enum case value: some case
Enum case from value: \SomeBackedEnum::SomeCase
Enum case from right value: \SomeBackedEnum::SomeCase
Enum case try from wrong value: NULL
Information:
enum(OtherBackedEnum::OtherCase)
Type: object
Enum case name property: OtherCase
Enum case value: 20
Enum case from value: \OtherBackedEnum::OtherCase
Enum case try right from right value: \OtherBackedEnum::OtherCase
Enum case try right wrong right value: NULL
Source code: Example
Both pure enums and backed enums implement an internal interface named UnitEnum. UnitEnum includes a static method cases(). cases() returns a packed array of all defined cases in the order of declaration.
<?php
Suit::cases();
// Produces: [Suit::Hearts, Suit::Diamonds, Suit::Clubs, Suit::Spades]
?>
Manually defining a cases() method on an enum will result in a fatal error.
Example: Enum case values listing
<?php
enum SomeEnum: string
{
case SomeCase = 'some case';
case OtherCase = 'other case';
case AnotherCase = 'another case';
}
foreach (SomeEnum::SomeCase->cases() as $case) {
var_dump($case);
print($case->value . PHP_EOL. PHP_EOL);
}
Result (PHP 8.4):
enum(SomeEnum::SomeCase)
some case
enum(SomeEnum::OtherCase)
other case
enum(SomeEnum::AnotherCase)
another case
Source code: Example
Enumerations may include constants, which may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.
An enum constant may refer to an enum case:
<?php
enum Size
{
case Small;
case Medium;
case Large;
public const Huge = self::Large;
}
?>
Example: Enum constants
<?php
enum SomeEnum
{
case SomeCase;
case OtherCase;
case AnotherCase;
const int CASES_NUMBER = 3;
}
var_dump(SomeEnum::SomeCase::CASES_NUMBER);
Result (PHP 8.4):
int(3)
Source code: Example
Enums (both pure enums and backed enums) may contain methods, and may implement interfaces. If an enum implements an interface, then any type check for that interface will also accept all cases of that enum.
Inside a method, the $this variable is defined and refers to the case instance.
Methods may be arbitrarily complex, but in practice will usually return a static value or match on $this to provide different results for different cases.
Methods may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.
Example: Enum methods
<?php
enum SomeEnum: string
{
case SomeCase = 'rabbit';
case OtherCase = 'fox';
case AnotherCase = 'owl';
public function someMethod()
{
return $this->otherMethod();
}
protected function otherMethod()
{
return $this->anotherMethod();
}
private function anotherMethod()
{
return self::SomeCase->value;
}
}
var_dump(SomeEnum::SomeCase);
$result = SomeEnum::SomeCase->someMethod();
var_dump($result);
Result (PHP 8.4):
enum(SomeEnum::SomeCase)
string(6) "rabbit"
Source code: Example
Enumerations may also have static methods. The use for static methods on the enumeration itself is primarily for alternative constructors. E.g.:
<?php
enum Size
{
case Small;
case Medium;
case Large;
public static function fromLength(int $cm): self
{
return match(true) {
$cm < 50 => self::Small,
$cm < 100 => self::Medium,
default => self::Large,
};
}
}
?>
Static methods may be public, private, or protected, although in practice private and protected are equivalent as inheritance is not allowed.
Example: Enum static methods
<?php
enum SomeEnum: string
{
case SomeCase = 'rabbit';
case OtherCase = 'fox';
case AnotherCase = 'owl';
public static function someMethod()
{
return self::otherMethod();
}
protected static function otherMethod()
{
return self::anotherMethod();
}
private static function anotherMethod()
{
return self::OtherCase->value;
}
}
var_dump(SomeEnum::SomeCase);
$result = SomeEnum::SomeCase::someMethod();
var_dump($result);
Result (PHP 8.4):
enum(SomeEnum::SomeCase)
string(3) "fox"
Source code: Example
Enums (both pure enums and backed enums) may contain methods, and may implement interfaces. If an enum implements an interface, then any type check for that interface will also accept all cases of that enum.
<?php
interface Colorful
{
public function color(): string;
}
enum Suit implements Colorful
{
case Hearts;
case Diamonds;
case Clubs;
case Spades;
// Fulfills the interface contract.
public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}
// Not part of an interface; that's fine.
public function shape(): string
{
return "Rectangle";
}
}
function paint(Colorful $c)
{
/* ... */
}
paint(Suit::Clubs); // Works
print Suit::Diamonds->shape(); // prints "Rectangle"
?>
In this example, all four instances of Suit have two methods, color() and shape(). As far as calling code and type checks are concerned, they behave exactly the same as any other object instance.
On a backed enum, the interface declaration goes after the backing type declaration.
<?php
interface Colorful
{
public function color(): string;
}
enum Suit: string implements Colorful
{
case Hearts = 'H';
case Diamonds = 'D';
case Clubs = 'C';
case Spades = 'S';
// Fulfills the interface contract.
public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}
}
?>
Note that in this case it would be a better data modeling practice to also define a SuitColor enum type with values Red and Black and return that instead. However, that would complicate this example.
The above hierarchy is logically similar to the following class structure (although this is not the actual code that runs):
<?php
interface Colorful
{
public function color(): string;
}
final class Suit implements UnitEnum, Colorful
{
public const Hearts = new self('Hearts');
public const Diamonds = new self('Diamonds');
public const Clubs = new self('Clubs');
public const Spades = new self('Spades');
private function __construct(public readonly string $name) {}
public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}
public function shape(): string
{
return "Rectangle";
}
public static function cases(): array
{
// Illegal method, because manually defining a cases() method on an Enum is disallowed.
// See also "Value listing" section.
}
}
?>
Example: Enum implementing interface
<?php
interface SomeInterface
{
public function someMethod(int $someArgument): string;
}
enum SomeEnum: string implements SomeInterface
{
case SomeCase = 'rabbit';
case OtherCase = 'fox';
case AnotherCase = 'owl';
public function someMethod(int $someArgument): string
{
switch ($someArgument) {
case 1:
return self::SomeCase->value;
break;
case 2:
return self::OtherCase->value;
break;
case 3:
return self::AnotherCase->value;
break;
default:
return 'none';
break;
}
}
}
print(SomeEnum::SomeCase->someMethod(0) . PHP_EOL);
print(SomeEnum::SomeCase->someMethod(1) . PHP_EOL);
print(SomeEnum::SomeCase->someMethod(2) . PHP_EOL);
print(SomeEnum::SomeCase->someMethod(3) . PHP_EOL);
Result (PHP 8.4):
none
rabbit
fox
owl
Source code: Example
Enumerations may leverage traits, which will behave the same as on classes. The caveat is that traits used in an enum must not contain properties. They may only include methods, static methods, and constants. A trait with properties will result in a fatal error.
<?php
interface Colorful
{
public function color(): string;
}
trait Rectangle
{
public function shape(): string {
return "Rectangle";
}
}
enum Suit implements Colorful
{
use Rectangle;
case Hearts;
case Diamonds;
case Clubs;
case Spades;
public function color(): string
{
return match($this) {
Suit::Hearts, Suit::Diamonds => 'Red',
Suit::Clubs, Suit::Spades => 'Black',
};
}
}
?>
Example: Enum using trait
<?php
trait SomeTrait
{
public static function someMethod()
{
return self::OtherCase->value;
}
}
enum SomeEnum: string
{
use SomeTrait;
case SomeCase = 'rabbit';
case OtherCase = 'fox';
case AnotherCase = 'owl';
}
$result = SomeEnum::SomeCase::someMethod();
var_dump($result);
Result (PHP 8.4):
string(3) "fox"
Source code: Example
Because cases are represented as constants on the enum itself, they may be used as static values in most constant expressions: property defaults, static variable defaults, parameter defaults, global and class constant values. They may not be used in other enum case values, but normal constants may refer to an enum case.
However, implicit magic method calls such as ArrayAccess on enums are not allowed in static or constant definitions as we cannot absolutely guarantee that the resulting value is deterministic or that the method invocation is free of side effects. Function calls, method calls, and property access continue to be invalid operations in constant expressions.
<?php
// This is an entirely legal Enum definition.
enum Direction implements ArrayAccess
{
case Up;
case Down;
public function offsetExists($offset): bool
{
return false;
}
public function offsetGet($offset): mixed
{
return null;
}
public function offsetSet($offset, $value): void
{
throw new Exception();
}
public function offsetUnset($offset): void
{
throw new Exception();
}
}
class Foo
{
// This is allowed.
const DOWN = Direction::Down;
// This is disallowed, as it may not be deterministic.
const UP = Direction::Up['short'];
// Fatal error: Cannot use [] on enums in constant expression
}
// This is entirely legal, because it's not a constant expression.
$x = Direction::Up['short'];
var_dump("\$x is " . var_export($x, true));
$foo = new Foo();
?>
Example: Enum case as constant value
<?php
enum SomeEnum: string
{
case SomeCase = 'rabbit';
case OtherCase = 'fox';
case AnotherCase = 'owl';
}
const SOME_CONSTANT = SomeEnum::SomeCase;
print(SOME_CONSTANT->value . PHP_EOL);
function someFunction(SomeEnum $someParameter)
{
print($someParameter->value . PHP_EOL);
}
someFunction(SomeEnum::OtherCase);
class SomeClass
{
const SomeEnum SOME_CONSTANT = SomeEnum::SomeCase;
public SomeEnum $someProperty = SomeEnum::OtherCase;
private SomeEnum $otherProperty;
public function someMethod(SomeEnum $someParameter)
{
$this->otherProperty = $someParameter;
print(self::SOME_CONSTANT->value . PHP_EOL
. $this->someProperty->value . PHP_EOL
. $this->otherProperty->value . PHP_EOL);
}
}
$someObject = new SomeClass();
$someObject->someProperty = SomeEnum::OtherCase;
$someObject->someMethod(SomeEnum::AnotherCase);
Result (PHP 8.4):
rabbit
fox
rabbit
fox
owl
Source code: Example
Example: Enum case in constant expression
<?php
enum SomeEnum: string
{
case SomeCase = 'rabbit';
case OtherCase = 'fox';
case AnotherCase = 'owl';
}
global $someVariable;
$someVariable = SomeEnum::SomeCase;
print($someVariable->value . PHP_EOL);
function someFunction(SomeEnum $someParameter = SomeEnum::OtherCase)
{
print($someParameter->value . PHP_EOL);
}
someFunction();
class SomeClass
{
const SomeEnum SOME_CONSTANT = SomeEnum::SomeCase;
public SomeEnum $someProperty = SomeEnum::OtherCase;
public static SomeEnum $otherProperty = SomeEnum::AnotherCase;
private SomeEnum $anotherProperty;
public function someMethod(SomeEnum $someParameter = SomeEnum::AnotherCase)
{
$this->anotherProperty = $someParameter;
print(self::SOME_CONSTANT->value . PHP_EOL
. $this->someProperty->value . PHP_EOL
. self::$otherProperty->value . PHP_EOL
. $this->anotherProperty->value . PHP_EOL);
}
}
$someObject = new SomeClass();
$someObject->someMethod();
Result (PHP 8.4):
rabbit
fox
rabbit
fox
owl
owl
Source code: Example
Enumerations are serialized differently from objects. Specifically, they have a new serialization code, "E", that specifies the name of the enum case. The deserialization routine is then able to use that to set a variable to the existing singleton value. That ensures that:
<?php
Suit::Hearts === unserialize(serialize(Suit::Hearts));
print serialize(Suit::Hearts);
// E:11:"Suit:Hearts";
?>
On deserialization, if an enum and case cannot be found to match a serialized value a warning will be issued and false returned.
If a pure enum is serialized to JSON, an error will be thrown. If a backed enum is serialized to JSON, it will be represented by its scalar value only, in the appropriate type. The behavior of both may be overridden by implementing JsonSerializable.
For print_r(), the output of an enum case is slightly different from objects to minimize confusion.
<?php
enum Foo {
case Bar;
}
enum Baz: int {
case Beep = 5;
}
print_r(Foo::Bar);
print_r(Baz::Beep);
/* Produces
Foo Enum (
[name] => Bar
)
Baz Enum:int {
[name] => Beep
[value] => 5
}
*/
?>
Although enums are built on classes and objects, they do not support all object-related functionality. In particular, enum cases are forbidden from having state.
The following object functionality is available, and behaves just as it does on any other object:
TARGET_CLASS target filter includes enums themselves. The TARGET_CLASS_CONST target filter includes enum cases.__call, __callStatic, and __invoke magic methods.__CLASS__ and __FUNCTION__ constants behave as normal.The ::class magic constant on an enum type evaluates to the type name including any namespace, exactly the same as an object. The ::class magic constant on a case instance also evaluates to the enum type, as it is an instance of that type.
Additionally, enum cases may not be instantiated directly with new, nor with ReflectionClass::newInstanceWithoutConstructor() in reflection. Both will result in an error.
<?php
$clovers = new Suit();
// Error: Cannot instantiate enum Suit
$horseshoes = (new ReflectionClass(Suit::class))->newInstanceWithoutConstructor()
// Error: Cannot instantiate enum Suit
?>
Classes have contracts on their methods:
<?php
class A {}
class B extends A {}
function foo(A $a) {}
function bar(B $b) {
foo($b);
}
?>
This code is type-safe, as B follows the contract of A, and through the magic of co/contra-variance, any expectation one may have of the methods will be preserved, exceptions excepted.
Enums have contracts on their cases, not methods:
<?php
enum ErrorCode {
case SOMETHING_BROKE;
}
function quux(ErrorCode $errorCode)
{
// When written, this code appears to cover all cases
match ($errorCode) {
ErrorCode::SOMETHING_BROKE => true,
};
}
?>
The match statement in the function quux can be static analyzed to cover all of the cases in ErrorCode.
But imagine it was allowed to extend enums:
<?php
// Thought experiment code where enums are not final.
// Note, this won't actually work in PHP.
enum MoreErrorCode extends ErrorCode {
case PEBKAC;
}
function fot(MoreErrorCode $errorCode) {
quux($errorCode);
}
fot(MoreErrorCode::PEBKAC);
?>
Under normal inheritance rules, a class that extends another will pass the type check.
The problem would be that the match statement in quux() no longer covers all the cases. Because it doesn’t know about MoreErrorCode::PEBKAC the match will throw an exception.
Because of this enums are final and can’t be extended.
enumIf an enum is converted to an object, it is not modified. If an enum is converted to an array, an array with a single name key (for pure enums) or an array with both name and value keys (for backed enums) is created. All other cast types will result in an error.
Example: Casting from enum case
<?php
enum SomeEnum
{
case SomeCase;
case OtherCase;
case AnotherCase;
}
enum SomeBackedEnum: string
{
case SomeCase = 'some case';
case OtherCase = 'other case';
case AnotherCase = 'another case';
}
$pureEnumCaseToArray = (array) SomeEnum::SomeCase;
print("Pure enum case to array: ");
var_dump($pureEnumCaseToArray);
$backedEnumCaseToArray = (array) SomeBackedEnum::OtherCase;
print("Backed enum case to array: ");
var_dump($backedEnumCaseToArray);
print(PHP_EOL);
$pureEnumCaseToObject = (object) SomeEnum::SomeCase;
print("Pure enum case to object: ");
var_dump($pureEnumCaseToObject);
$backedEnumCaseToObject = (object) SomeBackedEnum::OtherCase;
print("Backed enum case to object: ");
var_dump($backedEnumCaseToObject);
print(PHP_EOL);
Result (PHP 8.4):
Pure enum case to array: array(1) {
["name"]=>
string(8) "SomeCase"
}
Backed enum case to array: array(2) {
["name"]=>
string(9) "OtherCase"
["value"]=>
string(10) "other case"
}
Pure enum case to object: enum(SomeEnum::SomeCase)
Backed enum case to object: enum(SomeBackedEnum::OtherCase)
Source code: Example