Repository files navigation

Maintenance for this project issupported via Tidelift.

First, and mainly,SplEnum is not integrated to PHP, you have to install the extension separately.

Using an enum instead of class constants provides the following advantages:

• You can use an enum as a parameter type:function setAction(Action $action) {
• You can use an enum as a return type:function getAction() : Action {
• You can enrich the enum with methods (e.g.format,parse, …)
• You can extend the enum to add new values (make your enumfinal to prevent it)
• You can get a list of all the possible values (see below)

This Enum class is not intended to replace class constants, but only to be used when it makes sense.

composer require myclabs/php-enum

useMyCLabs\Enum\Enum;/** * Action enum * * @extends Enum<Action::*> */finalclass Actionextends Enum{privateconstVIEW ='view';privateconstEDIT ='edit';}

$action = Action::VIEW();// or with a dynamic key:$action = Action::$key();// or with a dynamic value:$action = Action::from($value);// or$action =newAction($value);

As you can see, static methods are automatically implemented to provide quick access to an enum value.

One advantage over using class constants is to be able to use an enum as a parameter type:

functionsetAction(Action$action) {// ...}

• __construct() The constructor checks that the value exist in the enum
• __toString() You canecho $myValue, it will display the enum value (value of the constant)
• getValue() Returns the current value of the enum
• getKey() Returns the key of the current value on Enum
• equals() Tests whether enum instances are equal (returnstrue if enum values are equal,false otherwise)

Static methods:

• from() Creates an Enum instance, checking that the value exist in the enum
• toArray() method Returns all possible values as an array (constant name in key, constant value in value)
• keys() Returns the names (keys) of all constants in the Enum class
• values() Returns instances of the Enum class of all Enum constants (constant name in key, Enum instance in value)
• isValid() Check if tested value is valid on enum set
• isValidKey() Check if tested key is valid on enum set
• assertValidValue() Assert the value is valid on enum set, throwing exception otherwise
• search() Return key for searched value

finalclass Actionextends Enum{privateconstVIEW ='view';privateconstEDIT ='edit';}// Static method:$action = Action::VIEW();$action = Action::EDIT();

Static method helpers are implemented using__callStatic().

If you care about IDE autocompletion, you can either implement the static methods yourself:

finalclass Actionextends Enum{privateconstVIEW ='view';/**     * @return Action     */publicstaticfunctionVIEW() {returnnewAction(self::VIEW);    }}

or you can use phpdoc (this is supported in PhpStorm for example):

/** * @method static Action VIEW() * @method static Action EDIT() */finalclass Actionextends Enum{privateconstVIEW ='view';privateconstEDIT ='edit';}

Native enum arrived to PHP in version 8.1:https://www.php.net/enumerations
If your project is running PHP 8.1+ or your library has it as a minimum requirement you should use it instead of this library.

When migrating frommyclabs/php-enum, the effort should be small if the usage was in the recommended way:

• private constants
• final classes
• no method overridden

Changes for migration:

• Class definition should be changed from

/** * @method static Action VIEW() * @method static Action EDIT() */finalclass Actionextends Enum{privateconstVIEW ='view';privateconstEDIT ='edit';}

to

enum Action:string{caseVIEW ='view';caseEDIT ='edit';}

All places where the class was used as a type will continue to work.

Usages and the change needed:

• PHP 8.1+ native enum
• Doctrine enum mapping
• Symfony ParamConverter integration
• PHPStan integration