vlw/xenum

PHP eXtended Enums. The missing quality-of-life features from PHP 8+ Enums

1.1.2 2024-12-02 10:36 UTC

GPL-3.0-only

• Victor Westerlund

README

The missing quality-of-life features from PHP 8+ Enums.

This library adds a few useful traits to your PHP Enums that compliment existing builtins.

For example,

use vlw\xEnum;

enum HelloWorld: string {
    use xEnum;

    case FOO = "BAR";
    case BAZ = "QUX";
}

// Like Enum::from() but for Enum names instead of values
HelloWorld::fromName("FOO"); // HelloWorld::FOO
// And of course the non-throwing version similar to Enum::tryFrom()
HelloWorld::tryFromName("MOM"); // null

How to use

Requires PHP 8.0 or newer

1. Install from composer

    composer require vlw/xenum
   

2. use in your project

    use vlw\xEnum;
   

3. use with your Enums

    enum HelloWorld {
        use xEnum;
    }
   

Methods

All methods implemented by this library

Method --| Enum::fromName(int|string|null): static Enum::tryFromName(int|string|null): static|null Enum::names(): array Enum::values(): array Enum::entries(): array

Enum::fromName()

Resolve an Enum case from case name or throw ValueError if case not found.

Similar to: Enum::from()

Enum::fromName(int|string|null): static

Example:

enum HelloWorld: string {
    use xEnum;
    
    case FOO = "BAR";
    case BAZ = "QUX";
}

HelloWorld::fromName("FOO"); // HelloWorld::FOO
HelloWorld::fromName("MOM") // ValueError: 'MOM' is not a valid case for HelloWorld

Enum::tryFromName()

Resolve an Enum case from case name or return null if no match found

Similar to: Enum::tryFrom()

Enum::tryFromName(int|string|null): static|null

Example:

enum HelloWorld: string {
    use xEnum;
    
    case FOO = "BAR";
    case BAZ = "QUX";
}

HelloWorld::tryFromName("FOO"); // HelloWorld::FOO
HelloWorld::tryFromName("MOM") // null

Enum::names()

Return sequential array of Enum case names

Enum::names(): array

Example:

enum HelloWorld: string {
    use xEnum;
    
    case FOO = "BAR";
    case BAZ = "QUX";
}

HelloWorld::names(); // ["FOO", "BAZ"]

Enum::values()

Return sequential array of Enum case values

Enum::entries(): array

Example:

enum HelloWorld: string {
    use xEnum;
    
    case FOO = "BAR";
    case BAZ = "QUX";
}

HelloWorld::values(); // ["BAR", "QUX"]

Enum::entries()

Return an associative array of Enum names and values. This method is similar to JavaScript's Object.entries()

Enum::entries(): array

Example:

enum HelloWorld: string {
    use xEnum;
    
    case FOO = "BAR";
    case BAZ = "QUX";
}

HelloWorld::entries(); // ["FOO" => "BAR", "BAZ" => "QUX"]