Enums in PHP 8.1

Since PHP 8.1, we can use enumerations also called enums. Enum defines a custom type that contains a fixed set of related values.

Enum is declared using enum keyword followed by the name. Each value is declared with the case keyword.

UserStatus.php

<?php

enum UserStatus
{
    case ACTIVE;
    case NOT_ACTIVE;
    case PENDING;
    case DELETED;
}

Enums can be used anywhere where types are accepted: parameters, return values, and properties.

User.php

<?php

class User
{
    private UserStatus $status;

    public function getStatus(): UserStatus
    {
        return $this->status;
    }

    public function setStatus(UserStatus $status): void
    {
        $this->status = $status;
    }
}

Only allowable values of enum type can be passed to function or class method that accepts parameter with enum type.

<?php

require_once 'UserStatus.php';
require_once 'User.php';

$user = new User();
$user->setStatus(UserStatus::ACTIVE);

Zero or more cases

Enum may have any number of case definitions, from zero to unlimited. Enum without any case is valid but not very usefull.

<?php

enum UserStatus
{
}

Case-sensitive name of the case

Name of the case is case-sensitive. The following example is valid but not recommended:

<?php

enum UserStatus
{
    case ACTIVE;
    case active;
}

Backed enums

Each case in enum may have a scalar value. Enum that contains case definitions with values is called backed enum.

<?php

enum UserStatus: string
{
    case ACTIVE = 'A';
    case NOT_ACTIVE = 'N';
    case PENDING = 'P';
    case DELETED = 'D';
}

There are some important notes for backed enums:

  • Type must be specified in enum declaration. Only string or int types are allowed. For example, the following example is wrong because float cannot be used as a type for enum values:
enum UserStatus: float // Error
{
}
  • All cases must have values. For example, the following example is wrong because NOT_ACTIVE doesn't have value:
<?php

enum UserStatus: string
{
    case ACTIVE = 'A';
    case NOT_ACTIVE; // Error
}
  • Values must be of the same type. For example, the following example is wrong because NOT_ACTIVE must have int value instead of string:
<?php

enum UserStatus: int
{
    case ACTIVE = 1;
    case NOT_ACTIVE = '2'; // Error
}
  • Values must be unique. For example, the following example is wrong because NOT_ACTIVE has value 1 which already used:
<?php

enum UserStatus: int
{
    case ACTIVE = 1;
    case NOT_ACTIVE = 1; // Error
}

Enum methods

Enum may have methods, just like class. It supports visibility modifiers such as public, protected or private.

UserStatus.php

<?php

enum UserStatus
{
    case ACTIVE;
    case NOT_ACTIVE;

    public function getLabel(): string
    {
        return match ($this) {
            self::ACTIVE => 'Active',
            self::NOT_ACTIVE => 'Not active',
        };
    }
}
<?php

require_once 'UserStatus.php';

echo UserStatus::ACTIVE->getLabel(); // Active

Static methods supported as well.

UserStatus.php

<?php

enum UserStatus
{
    case ACTIVE;
    case NOT_ACTIVE;

    public static function getLabel(self $value): string
    {
        return match ($value) {
            self::ACTIVE => 'Active',
            self::NOT_ACTIVE => 'Not active',
        };
    }
}
<?php

require_once 'UserStatus.php';

echo UserStatus::getLabel(UserStatus::ACTIVE); // Active

Enum constants

Enum may have constants, just like class. Enum constant may refer to an enum case as well.

<?php

enum UserStatus
{
    case ACTIVE;
    case NOT_ACTIVE;

    public const DEFAULT = self::ACTIVE;
    public const TOTAL_STATUSES = 2;
}

Enum properties is not allowed

Enum cannot contain properties. It is important difference between enum and class.

<?php

enum UserStatus
{
    private string $status; // Error
}

Enum and interfaces

Just like class, enum can implement interfaces.

HasLabelInterface.php

<?php

interface HasLabelInterface
{
    public function getLabel(): string;
}

UserStatus.php

<?php

enum UserStatus implements HasLabelInterface
{
    case ACTIVE;
    case NOT_ACTIVE;

    public function getLabel(): string { return '...'; }
}

If you want to implement interface in backed enum, after the enum name must come a type and after it implements keyword.

UserStatus.php

<?php

enum UserStatus : string implements HasLabelInterface
{
    case ACTIVE = 'A';
    case NOT_ACTIVE = 'N';

    public function getLabel(): string { return '...'; }
}

Enum name and value

Each case in enum has property name which contains name of the case. The name property is read-only.

UserStatus.php

<?php

enum UserStatus
{
    case ACTIVE;
    case NOT_ACTIVE;
}
<?php

require_once 'UserStatus.php';

echo UserStatus::ACTIVE->name; // ACTIVE

In backed enum, each case also has property value which is read-only as well.

UserStatus.php

<?php

enum UserStatus : string
{
    case ACTIVE = 'A';
    case NOT_ACTIVE = 'N';
}
<?php

require_once 'UserStatus.php';

echo UserStatus::ACTIVE->value; // A

Enum has cases static method which allows to retrieve all available cases of the enum.

<?php

require_once 'UserStatus.php';

foreach (UserStatus::cases() as $status) {
    // ACTIVE A
    // NOT_ACTIVE N
    echo $status->name.' '.$status->value.PHP_EOL;
}

Enum as array keys is not allowed

It is not possible to use enum as array keys.

UserStatus.php

<?php

enum UserStatus : string
{
    case ACTIVE = 'A';
    case NOT_ACTIVE = 'N';
}
<?php

require_once 'UserStatus.php';

$statuses = [
    UserStatus::ACTIVE => 'Active', // Error
    UserStatus::NOT_ACTIVE => 'Not active', // Error
];

Leave a Comment

Your email address will not be published.