php-xenum/README.md

PHP eXtended Enums

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 \victorwesterlund\xEnum;

enum HelloWorld: string {
    use xEnum;

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

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

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::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("BAR"); // 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("BAR"); // 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::values(): array

Example:

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

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

How to use

Requires PHP 8.0 or newer

1. Install from composer

   composer require victorwesterlund/xenum
   

2. use in your project

   use \victorwesterlund\xEnum;
   

3. use with your Enums

   enum HelloWorld {
       use xEnum;
   }