k2gl/enum

PHP BackedEnum spiced with syntactic sugar

2.3.0 2026-06-13 16:32 UTC

Requires

• php: >=8.1

Requires (Dev)

• k2gl/phpunit-fluent-assertions: ^12
• laravel/pint: ~1.20.0
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^10.5|^11.0|^12.0

MIT

• Nickolay Harin

• php
• enum
• backedEnum

README

Installation

You can add this library as a local, per-project dependency to your project using Composer:

composer require k2gl/enum

Usage

use K2gl\Enum\ExtendedBackedEnum;
use K2gl\Enum\ExtendedBackedEnumInterface;

enum CardSuit: string implements ExtendedBackedEnumInterface
{
    use ExtendedBackedEnum;

    case HEARTS = 'hearts';
    case DIAMONDS = 'diamonds';
    case CLUBS = 'clubs';
    case SPADES = 'spades';
}

enum ResponseCode: int implements ExtendedBackedEnumInterface
{
    use ExtendedBackedEnum;

    case HTTP_OK = 200;
    case HTTP_I_AM_A_TEAPOT = 418;
}

$suit = CardSuit::any(); // random CardSuit 
$suit = CardSuit::anyoneExcept(CardSuit::CLUBS); // random CardSuit except 'clubs'
$suit = CardSuit::anyoneExcept([CardSuit::HEARTS, CardSuit::DIAMONDS]); // random CardSuit except 'hearts' and 'diamonds'

$suit = CardSuit::SPADES;
$suit->is(CardSuit::SPADES); // true
$suit->is('spades'); // true
$suit->is(CardSuit::HEARTS); // false

$suit = ResponseCode::HTTP_I_AM_A_TEAPOT;
$suit->isNot(200); // true
$suit->isNot(ResponseCode::HTTP_OK); // true
$suit->isNot(418); // false
$suit->isNot(ResponseCode::HTTP_I_AM_A_TEAPOT); // false

// Set membership — is()/isNot() for a list of cases or raw values.
$suit = CardSuit::SPADES;
$suit->in(CardSuit::HEARTS, CardSuit::SPADES); // true
$suit->in('hearts', 'clubs');                  // false
$suit->in(...[CardSuit::HEARTS, CardSuit::SPADES]); // true (spread an array)
$suit->notIn(CardSuit::HEARTS, CardSuit::CLUBS);    // true

CardSuit::names(); // ['HEARTS', 'DIAMONDS', 'CLUBS', 'SPADES'] 
CardSuit::values(); // ['hearts', 'diamonds', 'clubs', 'spades']

// Resolve a case by its name — the counterpart of the native from()/tryFrom(),
// which only resolve by backing value.
CardSuit::fromName('SPADES');    // CardSuit::SPADES
CardSuit::tryFromName('SPADES'); // CardSuit::SPADES
CardSuit::tryFromName('joker');  // null
CardSuit::fromName('joker');     // throws \ValueError

Labels and form options

Attach a human-readable label to a case with #[Label]. label() returns it, falling back to the raw case name when the attribute is absent; options() builds a value => label map ready for a dropdown.

use K2gl\Enum\ExtendedBackedEnum;
use K2gl\Enum\ExtendedBackedEnumInterface;
use K2gl\Enum\Label;

enum OrderStatus: string implements ExtendedBackedEnumInterface
{
    use ExtendedBackedEnum;

    #[Label('Awaiting payment')]
    case PENDING = 'pending';

    #[Label('Paid')]
    case PAID = 'paid';

    case SHIPPED = 'shipped'; // no #[Label] — label() falls back to the name
}

OrderStatus::PENDING->label(); // 'Awaiting payment'
OrderStatus::SHIPPED->label(); // 'SHIPPED'

OrderStatus::options();
// ['pending' => 'Awaiting payment', 'paid' => 'Paid', 'shipped' => 'SHIPPED']

// Render an HTML <select>:
foreach (OrderStatus::options() as $value => $label) {
    echo "<option value=\"{$value}\">{$label}</option>";
}

// Symfony ChoiceType expects label => value, so flip it:
// 'choices' => array_flip(OrderStatus::options())

Pull requests are always welcome

Collaborate with pull requests