PHP8.1 new features explained Enums enumeration

This article is a translation, original address: https://stitcher.io/blog/php-enums

PHP 8.1: Enumerations

They're finally here - built-in support for enums will be added in PHP 8.1! Some may think they should have done this a long time ago, but you didn't hear my complaint; I'm glad they did! This article is dedicated to a deep dive into the newly added features.

As usual in my PHP feature posts, we start with a high-level overview of what enumerations look like:

enum Status
{
    case DRAFT;
    case PUBLISHED;
    case ARCHIVED;
}

The benefit of enumerations is that they represent a set of constant values, but The most important thing is that these values ​​can be typed like this:

class BlogPost
{
    public function __construct(
        public Status $status, 
    ) {}
}

In this example, creating an enum and passing it to aBlogPost looks like this:

$post = new BlogPost(Status::DRAFT);

That's it The basics, as you can see, they are not complicated at all. While there are a lot of side notes to make, let’s take a deeper look at enumerations!

#Enumeration methods

Enumerations can define methods, just like classes. This is a very powerful feature, especially when combined with the match operator:

enum Status
{
    case DRAFT;
    case PUBLISHED;
    case ARCHIVED;
    
    public function color(): string
    {
        return match($this) 
        {
            Status::DRAFT => 'grey',   
            Status::PUBLISHED => 'green',   
            Status::ARCHIVED => 'red',   
        };
    }
}

Methods can be used like this:

$status = Status::ARCHIVED;
$status->color(); // 'red'

Static methods are also allowed:

enum Status
{
    // …
    
    public static function make(): Status
    {
        // …
    }
}

You can also use self in an enumeration:

enum Status
{
    // …
    
    public function color(): string
    {
        return match($this) 
        {
            self::DRAFT => 'grey',   
            self::PUBLISHED => 'green',   
            self::ARCHIVED => 'red',   
        };
    }
}

#Enumeration interface

Enumerations can implement interfaces, just like ordinary classes:

interface HasColor
{
    public function color(): string;
}
enum Status implements HasColor
{
    case DRAFT;
    case PUBLISHED;
    case ARCHIVED;
    
    public function color(): string { /* … */ }
}

# Enumeration values ​​- aka "backed enums"

Enumeration values ​​are represented internally by objects, but you can assign values ​​to them as needed; this is useful for e.g. it works. Serialize them into the database.

enum Status: string
{
    case DRAFT = 'draft';
    case PUBLISHED = 'published';
    case ARCHIVED = 'archived';
}

Pay attention to the type declaration in the enumeration definition. It indicates that all enumeration values ​​belong to the given type. You can also make it an int. Note that onlyint and string are allowed as enumeration values.

enum Status: int
{
    case DRAFT = 1;
    case PUBLISHED = 2;
    case ARCHIVED = 3;
}

The technical term for type enums is called "backed enumerations" because they are "backed" by simpler values. If you decide to assign an enumeration value, all cases should have a value. You can't mix and match them. Enumerations without "backing" are called "pure enumerations".

#Supported enumerations with interfaces

If you use a supported enumeration with an interface, the enumeration type must come directly after the enumeration name, implements before the keyword.

enum Status: string implements HasColor
{
    case DRAFT = 'draft';
    case PUBLISHED = 'published';
    case ARCHIVED = 'archived';
    
    // …
}

#Serialization supported enums

If you are assigning values ​​to enum cases, you may need a way to serialize and deserialize them . Serializing them means you need a way to access the enum values. This is done via a read-only public property:

$value = Status::PUBLISHED->value; // 2

The enumeration can be restored from the value using: Enum::from

$status = Status::from(2); // Status::PUBLISHED

If an unknown value is passed tryFrom, there is also a return null. There is an exception if you use from.

$status = Status::from('unknown'); // ValueError
$status = Status::tryFrom('unknown'); // null

Please note that you can also use the built-in serialize and unserialize functions on enumerations. Additionally, you can use json_encode with a supported enumeration and the result will be an enumeration value. This behavior can be overridden by implementing JsonSerializable.

#Listing enumeration values

You can get a list of all available cases in an enumeration using the static method: Enum::cases()

Status::cases();
/* [
    Status::DRAFT, 
    Status::PUBLISHED, 
    Status::ARCHIVED
] */

Please note that this array contains the actual enumeration objects:

array_map(
    fn(Status $status) => $status->color(), 
    Status::cases()
);

#Enumerations are objects

I already mentioned that enumeration values ​​are represented as objects, actual Above they are singleton objects. This means you can compare to them like this:

$statusA = Status::PENDING;
$statusB = Status::PENDING;
$statusC = Status::ARCHIVED;
$statusA === $statusB; // true
$statusA === $statusC; // false
$statusC instanceof Status; // true

# Enums as Array Keys

Since enum values ​​are actually objects, there is currently no way to They are used as array keys. The following will result in an error:

$list = [
    Status::DRAFT => 'draft',
    // …
];

There is an RFC to change this behavior, but it has not been voted on yet.

This means you can only use enums as keys in SplObjectStorage and WeakMaps.

#Traits

Enumerations can use traits just like classes, but with more restrictions. Overriding built-in enumeration methods is not allowed, and they cannot contain class attributes - their use in enumerations is prohibited.

#Reflection and Properties

As expected, a few reflection classes have been added to handle enumerations: ReflectionEnum, ReflectionEnumUnitCase and ReflectionEnumBackedCase. There is also a new enum_exists function, which does exactly what its name suggests.

Just like ordinary classes and attributes, enumerations and their cases can be annotated using attributes. Note that the TARGET_CLASS filter will also include enumerations.

One last thing: the enumeration also has a read-only attribute, which the RFC mentions is an implementation detail and should only be used for debugging purposes. But it's still worth mentioning. $enum->name

The above is the detailed content of PHP8.1 new features explained Enums enumeration. For more information, please follow other related articles on the PHP Chinese website!