philiprehberger/php-enum-utils

Utility trait and helpers for PHP 8.1+ native enums

v1.0.3 2026-03-17 20:06 UTC

Requires

• php: ^8.2

Requires (Dev)

• laravel/pint: ^1.0
• phpstan/phpstan: ^1.12|^2.0
• phpunit/phpunit: ^11.0

MIT

• Philip Rehberger

• helpers
• attributes
• enum
• utilities
• php-enum

README

Utility trait and helpers for PHP 8.1+ native enums.

Requirements

Dependency	Version
PHP	^8.2

Installation

composer require philiprehberger/php-enum-utils

Usage

Adding the trait to your enum

use PhilipRehberger\EnumUtils\EnumUtils;
use PhilipRehberger\EnumUtils\Attributes\Label;
use PhilipRehberger\EnumUtils\Attributes\Description;

enum Status: string
{
    use EnumUtils;

    #[Label('Pending Review')]
    #[Description('The item is waiting for review')]
    case Pending = 'pending';

    #[Label('In Progress')]
    case InProgress = 'in_progress';

    case Completed = 'completed';
}

Lookup by name

$case = Status::fromName('pending');      // Status::Pending (case-insensitive)
$case = Status::tryFromName('unknown');   // null

Listing cases

Status::names();   // ['Pending', 'InProgress', 'Completed']
Status::values();  // ['pending', 'in_progress', 'completed']
Status::count();   // 3

Arrays for forms and selects

Status::toSelectArray();
// ['pending' => 'Pending Review', 'in_progress' => 'In Progress', 'completed' => 'Completed']

Status::toArray();
// ['Pending' => 'pending', 'InProgress' => 'in_progress', 'Completed' => 'completed']

Random case and comparison

$case = Status::random();                        // A random Status case
Status::Pending->equals(Status::Pending);        // true
Status::Pending->equals(Status::Completed);      // false

Reading attributes with EnumMeta

use PhilipRehberger\EnumUtils\EnumMeta;

EnumMeta::label(Status::Pending);         // 'Pending Review'
EnumMeta::label(Status::Completed);       // 'Completed' (fallback: humanized name)
EnumMeta::description(Status::Pending);   // 'The item is waiting for review'
EnumMeta::description(Status::Completed); // null
EnumMeta::labels(Status::class);          // ['pending' => 'Pending Review', ...]

API

EnumUtils Trait

Method	Description
::fromName(string $name): static	Case-insensitive lookup by name; throws ValueError on miss
::tryFromName(string $name): ?static	Case-insensitive lookup by name; returns null on miss
::names(): array	All case names as a flat array
::values(): array	All case values as a flat array
::random(): static	A random case
::toSelectArray(): array	[value => label] for form selects
::toArray(): array	[name => value] for serialization
::count(): int	Total number of cases
->equals(self $other): bool	Strict identity comparison

EnumMeta Helper

Method	Description
EnumMeta::label(BackedEnum $case): string	Label from attribute or humanized name
EnumMeta::description(BackedEnum $case): ?string	Description from attribute or null
EnumMeta::labels(string $enumClass): array	[value => label] for all cases

Attributes

Attribute	Target	Purpose
#[Label('...')]	Enum case	Human-readable label
#[Description('...')]	Enum case	Longer description text

Development

composer install
vendor/bin/phpunit
vendor/bin/pint --test
vendor/bin/phpstan analyse

License

MIT