Skip to content

SPEC.md

Latest commit

 

History

History
111 lines (79 loc) · 3.37 KB

SPEC.md

File metadata and controls

111 lines (79 loc) · 3.37 KB

php-enum-utils — Project Specification

8. php-enum-utils

The missing toolkit for PHP 8.1+ native enums.

Language PHP 8.1+

Distribution Packagist (composer require yourvendor/enum-utils)

Build Time 5--7 days

License MIT

Category Language Utility / PHP

Problem

PHP 8.1 introduced native enums, but the ecosystem still relies on myclabs/php-enum (200M+ Packagist installs) which is a polyfill for the pre-8.1 world. Native enums lack convenience methods that developers expect: converting to select arrays for forms, looking up by label, random selection, JSON serialization helpers, database casting, and collection operations. Every project reinvents these utilities.

Solution

A zero-dependency PHP 8.1+ package providing a comprehensive trait and utility class for native enums. Drop-in enhancement that adds all the convenience methods developers are used to from myclabs/php-enum, adapted for the native enum syntax.

Core Features

  • EnumUtilsTrait: A trait that any BackedEnum can use: toSelectArray(), fromLabel(), tryFromLabel(), labels(), randomCase(), and toCollection().

  • JSON helpers: toJsonValue(), fromJsonValue(), and a JsonSerializable implementation that handles both string and int backed enums.

  • Form helpers: toSelectArray() returns [value => label] arrays suitable for HTML selects. toRadioOptions() includes metadata attributes.

  • Database casting: A generic Cast class for Laravel Eloquent and a Doctrine Type for Symfony, both auto-discovered from the enum's backing type.

  • Collection operations: filter(), map(), contains(), and diff() over enum case sets.

  • Validation rules: A standalone validation rule asserting a value is a valid case of a given enum, usable outside any framework.

Technical Architecture

Pure PHP, zero dependencies. The core is EnumUtilsTrait which uses reflection to discover case names and values. Label resolution follows a convention: if the enum implements a label() method, use it; otherwise, humanize the case name (DARK_MODE becomes "Dark Mode"). Framework integrations (Laravel cast, Doctrine type) are in separate namespaces with optional autoload. Full PHPStan level 9 and Pest test coverage.

CLI / API Surface

// Usage example

enum Status: string {

use EnumUtilsTrait;

case Active = 'active';

case Inactive = 'inactive';

}

Status::toSelectArray(); // ['active' => 'Active', 'inactive' => 'Inactive']

Status::fromLabel('Active'); // Status::Active

Status::randomCase(); // Status::Active or Status::Inactive

Key Dependencies

  • None (zero dependencies). Optional: illuminate/support, doctrine/dbal for framework integrations.

Scope Boundaries

In scope: Enum utility trait, JSON helpers, form helpers, Laravel and Doctrine integrations, validation rules, collection operations.

Out of scope: Enum polyfills for PHP < 8.1. Code generation. Enum migration tools. State machines.

Success Criteria

  • Packagist published with PHPStan level 9 passing

  • 100% test coverage with Pest

  • README includes migration guide from myclabs/php-enum

  • At least one Laravel and one Symfony usage example