php-enum

The enum PHP is missing, inspired from SplEnum

2,720

132

2,720

View on GitHub

Top Related Projects

laravel-enum

1,991

Simple, extensible and powerful enumeration implementation for Laravel.

Quick Overview

myclabs/php-enum is a PHP library that provides a base class for creating enumeration types in PHP. It offers a simple and type-safe way to define and use enums, which are not natively supported in PHP versions prior to 8.1.

Pros

Provides a clean and type-safe way to implement enums in PHP
Offers compatibility with older PHP versions that don't have native enum support
Includes useful methods for enum comparison and value retrieval
Integrates well with popular frameworks and libraries

Cons

Requires additional setup compared to native PHP 8.1+ enums
May have a slight performance overhead compared to native enums
Requires extending a base class, which might conflict with other inheritance needs
Less intuitive for developers accustomed to native enum syntax in other languages

Code Examples

Defining an enum:

use MyCLabs\Enum\Enum;

/**
 * @method static self APPLE()
 * @method static self BANANA()
 * @method static self CHERRY()
 */
class Fruit extends Enum
{
    private const APPLE = 'apple';
    private const BANANA = 'banana';
    private const CHERRY = 'cherry';
}

Using an enum:

$fruit = Fruit::APPLE();
echo $fruit; // Outputs: apple

if ($fruit->equals(Fruit::BANANA())) {
    echo "It's a banana!";
} else {
    echo "It's not a banana.";
}

Working with enum values:

$allFruits = Fruit::values();
foreach ($allFruits as $fruit) {
    echo $fruit->getKey() . ': ' . $fruit->getValue() . "\n";
}

$randomFruit = Fruit::randomValue();
echo "Random fruit: " . $randomFruit;

Getting Started

Install the library using Composer:

composer require myclabs/php-enum

Create your enum class:

use MyCLabs\Enum\Enum;

/**
 * @method static self DRAFT()
 * @method static self PUBLISHED()
 * @method static self ARCHIVED()
 */
class ArticleStatus extends Enum
{
    private const DRAFT = 'draft';
    private const PUBLISHED = 'published';
    private const ARCHIVED = 'archived';
}

Use your enum in your code:

$status = ArticleStatus::PUBLISHED();
if ($status->equals(ArticleStatus::DRAFT())) {
    echo "The article is still a draft.";
} else {
    echo "The article status is: " . $status->getValue();
}

Competitor Comparisons

laravel-enum

1,991

Simple, extensible and powerful enumeration implementation for Laravel.

Pros of laravel-enum

Seamless integration with Laravel's validation and form requests
Built-in casting support for Eloquent models
Provides additional utility methods specific to Laravel applications

Cons of laravel-enum

Limited to Laravel framework, not suitable for standalone PHP projects
Slightly more complex implementation compared to php-enum
May have a steeper learning curve for developers new to Laravel

Code Comparison

php-enum:

class UserType extends Enum
{
    const ADMIN = 'admin';
    const MODERATOR = 'moderator';
    const USER = 'user';
}

$userType = UserType::ADMIN();

laravel-enum:

class UserType extends Enum
{
    const ADMIN = 'admin';
    const MODERATOR = 'moderator';
    const USER = 'user';
}

$userType = UserType::ADMIN();
// Additional Laravel-specific features:
UserType::toArray();
UserType::toSelectArray();

Both libraries provide similar basic enum functionality, but laravel-enum offers additional Laravel-specific features and integrations. php-enum is more lightweight and framework-agnostic, making it suitable for a wider range of PHP projects. The choice between the two depends on whether you're working within a Laravel ecosystem and need the extra Laravel-specific functionality.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

PHP Enum implementation inspired from SplEnum

Maintenance for this project is supported via Tidelift.

Why?

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 enum final 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.

Installation

composer require myclabs/php-enum

Declaration

use MyCLabs\Enum\Enum;

/**
 * Action enum
 *
 * @extends Enum<Action::*>
 */
final class Action extends Enum
{
    private const VIEW = 'view';
    private const EDIT = 'edit';
}

Usage

$action = Action::VIEW();

// or with a dynamic key:
$action = Action::$key();
// or with a dynamic value:
$action = Action::from($value);
// or
$action = new Action($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:

function setAction(Action $action) {
    // ...
}

Documentation

__construct() The constructor checks that the value exist in the enum
__toString() You can echo $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 (returns true 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

Static methods

final class Action extends Enum
{
    private const VIEW = 'view';
    private const EDIT = '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:

final class Action extends Enum
{
    private const VIEW = 'view';

    /**
     * @return Action
     */
    public static function VIEW() {
        return new Action(self::VIEW);
    }
}

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

/**
 * @method static Action VIEW()
 * @method static Action EDIT()
 */
final class Action extends Enum
{
    private const VIEW = 'view';
    private const EDIT = 'edit';
}

Native enums and migration

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 from myclabs/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()
 */
final class Action extends Enum
{
    private const VIEW = 'view';
    private const EDIT = 'edit';
}

enum Action: string
{
    case VIEW = 'view';
    case EDIT = 'edit';
}

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

Usages and the change needed:

Operation	myclabs/php-enum	native enum
Obtain an instance will change from	`$enumCase = Action::VIEW()`	`$enumCase = Action::VIEW`
Create an enum from a backed value	`$enumCase = new Action('view')`	`$enumCase = Action::from('view')`
Get the backed value of the enum instance	`$enumCase->getValue()`	`$enumCase->value`
Compare two enum instances	`$enumCase1 == $enumCase2` or `$enumCase1->equals($enumCase2)`	`$enumCase1 === $enumCase2`
Get the key/name of the enum instance	`$enumCase->getKey()`	`$enumCase->name`
Get a list of all the possible instances of the enum	`Action::values()`	`Action::cases()`
Get a map of possible instances of the enum mapped by name	`Action::values()`	`array_combine(array_map(fn($case) => $case->name, Action::cases()), Action::cases())` or `(new ReflectionEnum(Action::class))->getConstants()`
Get a list of all possible names of the enum	`Action::keys()`	`array_map(fn($case) => $case->name, Action::cases())`
Get a list of all possible backed values of the enum	`Action::toArray()`	`array_map(fn($case) => $case->value, Action::cases())`
Get a map of possible backed values of the enum mapped by name	`Action::toArray()`	`array_combine(array_map(fn($case) => $case->name, Action::cases()), array_map(fn($case) => $case->value, Action::cases()))` or `array_map(fn($case) => $case->value, (new ReflectionEnum(Action::class))->getConstants()))`

Related projects

Top Related Projects

laravel-enum

1,991

Simple, extensible and powerful enumeration implementation for Laravel.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot