nelexa / enum
PHP Enum implementation
Installs: 178 022
Dependents: 4
Suggesters: 0
Security: 0
Stars: 1
Watchers: 2
Forks: 0
Open Issues: 0
Requires
- php: ^7.1|^8.0
- ext-json: *
Requires (Dev)
- phpunit/phpunit: >=5.0
This package is auto-updated.
Last update: 2024-10-26 04:07:38 UTC
README
Table of Contents
- nelexa/enum - Enum implementation for PHP
- Table of Contents
- Installation
- Enum declaration
- Usage
- Class Synopsis
- Usage tips
- Generate PHPDoc for enum class
- Changelog
- License
Installation
composer require nelexa/enum
Enum declaration
<?php use Nelexa\Enum; /** * @method static self PENDING() * @method static self ACTIVE() * @method static self INACTIVE() * @method static self DELETED() */ class UserStatus extends Enum { public const PENDING = 1, ACTIVE = 1 << 1, INACTIVE = 1 << 2, DELETED = 1 << 3; }
Usage
$enum = UserStatus::ACTIVE(); assert($enum instanceof UserStatus); assert($enum->name() === 'ACTIVE'); assert($enum->value() === 1 << 1); assert($enum->ordinal() === 1);
To loop a enum object
foreach (UserStatus::values() as $userStatus) { printf('User status: %s, status id: %d, ordinal: %d' . PHP_EOL, $userStatus->name(), $userStatus->value(), $userStatus->ordinal() ); }
Output:
User status: PENDING, status id: 1, ordinal: 0
User status: ACTIVE, status id: 2, ordinal: 1
User status: INACTIVE, status id: 4, ordinal: 2
User status: DELETED, status id: 8, ordinal: 3
To compare the enum values, use ===
operator
$userStatus = UserStatus::DELETED(); if ($userStatus === UserStatus::DELETED()) { echo 'User status: ' . $userStatus->name() . PHP_EOL; }
Convert a string to enum object
$enum = UserStatus::valueOf('ACTIVE'); assert(UserStatus::ACTIVE() === UserStatus::valueOf('ACTIVE'));
Convert a value to enum object
$enum = UserStatus::valueOf('ACTIVE'); $value = $enum->value(); assert(UserStatus::fromValue($value) === $enum); assert(UserStatus::fromValue($value) === UserStatus::valueOf('ACTIVE'));
Switch case
$enum = UserStatus::PENDING(); switch ($enum) { case UserStatus::ACTIVE(): echo 'Active status'; break; case UserStatus::PENDING(): echo 'Pending status'; break; case UserStatus::DELETED(): echo 'Delete status'; break; case UserStatus::INACTIVE(): echo 'Inactive status'; break; default: throw new \RuntimeException('Invalid value'); }
Output:
Pending status
Use enum in the type hint
/** * @var UserStatus */ private $status; public function setStatus(UserStatus $status): void { $this->status = $status; } public function getStatus(): UserStatus { return $this->status; } public function isActive(): bool { return $this->status === UserStatus::ACTIVE(); }
Example
$user->setStatus(UserStatus::INACTIVE()); echo sprintf('User status is %s.' . PHP_EOL, $user->getStatus()->name());
Output:
User status is INACTIVE
Add some logic to enum
<?php /** * @method static self PLUS() * @method static self MINUS() * @method static self TIMES() * @method static self DIVIDE() */ class Operation extends \Nelexa\Enum { private const PLUS = null, MINUS = null, TIMES = null, DIVIDE = null; /** * Do arithmetic op represented by this constant * * @param float $x * @param float $y * @return float */ public function calculate(float $x, float $y): float { switch ($this) { case self::PLUS(): return $x + $y; case self::MINUS(): return $x - $y; case self::TIMES(): return $x * $y; case self::DIVIDE(): return $x / $y; } throw new \AssertionError('Unknown op: ' . $this->name()); } }
Example
echo Operation::PLUS()->calculate(4, 2); // 6 echo Operation::TIMES()->calculate(4, 2); // 8 echo Operation::MINUS()->calculate(4, 2); // 2 echo Operation::DIVIDE()->calculate(4, 2); // 2
Initialization of values without constructor
For example consider the planets of the solar system. Each planet knows its mass and radius, and can calculate its surface gravity and the weight of an object on the planet.
Here is how it looks:
<?php declare(strict_types=1); use Nelexa\Enum; /** * Class Planet * * @method static self MERCURY() * @method static self VENUS() * @method static self EARTH() * @method static self MARS() * @method static self JUPITER() * @method static self SATURN() * @method static self URANUS() * @method static self NEPTUNE() * @method static self PLUTO() * * @see https://docs.oracle.com/javase/8/docs/technotes/guides/language/enums.html */ class Planet extends Enum { private const MERCURY = [3.303e+23, 2.4397e6], VENUS = [4.869e+24, 6.0518e6], EARTH = [5.976e+24, 6.37814e6], MARS = [6.421e+23, 3.3972e6], JUPITER = [1.9e+27, 7.1492e7], SATURN = [5.688e+26, 6.0268e7], URANUS = [8.686e+25, 2.5559e7], NEPTUNE = [1.024e+26, 2.4746e7], PLUTO = [1.27e+22, 1.137e6]; /** * @var double universal gravitational constant (m3 kg-1 s-2) */ private static $G = 6.67300E-11; /** * @var double in kilograms */ private $mass; /** * @var double in meters */ private $radius; /** * In this method, you can initialize additional variables based on the * value of the constant. The method is called after the constructor. * * @param string|int|float|bool|array|null $value the enum scalar value of the constant */ protected function initValue($value): void { [$this->mass, $this->radius] = $value; } public function mass(): float { return $this->mass; } public function radius(): float { return $this->radius; } public function surfaceGravity(): float { return self::$G * $this->mass / ($this->radius * $this->radius); } public function surfaceWeight(float $otherMass): float { return round($otherMass * $this->surfaceGravity(), 6); } }
The enum Planet class contains the initValue($value)
method, and each enum constant is declared with a value that to be passed to this method when it is created.
Here is a sample program that takes your weight on earth (in any unit) and calculates and prints your weight on all of the planets (in the same unit):
$earthWeight = 175; $mass = $earthWeight / Planet::EARTH()->surfaceGravity(); foreach (Planet::values() as $p) { printf("Your weight on %s is %f\n", $p->name(), $p->surfaceWeight($mass)); }
Output:
Your weight on MERCURY is 66.107583
Your weight on VENUS is 158.374842
Your weight on EARTH is 175.000000
Your weight on MARS is 66.279007
Your weight on JUPITER is 442.847567
Your weight on SATURN is 186.552719
Your weight on URANUS is 158.397260
Your weight on NEPTUNE is 199.207413
Your weight on PLUTO is 11.703031
Class Synopsis
abstract class Nelexa\Enum { /* Methods */ final public static valueOf ( string $name ) : static final public name ( void ) : string final public value ( void ) : string | int | float | bool | array | null final public static values ( void ) : static[] final public static containsKey ( string $name ) : bool final public static containsValue ( mixed $value [, bool $strict = true ] ) : bool final public static function fromValue( mixed $value ): static final public ordinal ( void ) : int public __toString ( void ) : string protected static function getEnumConstants(): array }
Usage tips
- Even though it is not mandatory to declare enum constants with UPPERCASE letters, it is in the best practice to do so.
- Enum classes can have fields and methods along with enum constants.
- Enum constructors are private. Only private constructors are allowed in enum classes. That’s why you can’t instantiate enum types using a new operator.
- Enum constants are created only once for the whole execution. All enum constants are created when you initially refer any enum constant in your code.
- Enum types can implement any number of interfaces.
- We can compare the enum constants using the
===
operator. - You can retrieve the enum constants of any enum type using the
values()
static method. Thevalues()
static method returns an array of enum constants. - The
ordinal()
static method is used to get the order of an enum constant in an enum type. - Enums are mostly used when you want to allow a limited set of options that remain constant for the whole execution and you know all possible options. For example, this could be choices on a menu or options of a combobox.
- Use private constants to exclude prompts from your IDE.
- Use PHPDoc to describe static enum initialization methods.
Generate PHPDoc for enum class
To use hints in the IDE, you need to declare special comments on the class with a list of static methods.
The \Nelexa\enum_docblock($enumOrEnumClass)
function should help with this.
echo \Nelexa\enum_docblock(Planet::class); // or echo \Nelexa\enum_docblock(Planet::MERCURY());
Output:
/**
* @method static self MERCURY()
* @method static self VENUS()
* @method static self EARTH()
* @method static self MARS()
* @method static self JUPITER()
* @method static self SATURN()
* @method static self URANUS()
* @method static self NEPTUNE()
* @method static self PLUTO()
*/
Changelog
Changes are documented in the releases page.
License
The files in this archive are released under the MIT License
.
You can find a copy of this license in LICENSE
file.