Php Enum Laravel Package

Getting Started

Start by requiring the package via Composer: composer require marc-mabe/php-enum. Then define your own enum class by extending MabeEnum\Enum and declaring public constants — these become the enum values. Keep values scalar (string, int, bool, null, float) or array-like for flexibility.

First use case: Replace magic strings/ints in domain logic. For example, a UserStatus enum avoids ambiguity like 'active', 'a', or 1:

use MabeEnum\Enum;

class UserStatus extends Enum
{
    const INACTIVE = 'i';
    const ACTIVE   = 'a';
    const DELETED  = 'd';
}

Then enforce type safety: type-hint UserStatus $status in services or models, and instantiate via UserStatus::ACTIVE() or UserStatus::get('a').

Implementation Patterns

• Type-hinting with enum objects: Use UserStatus $status for strict typing; prefer immutable .() calls (e.g., UserStatus::ACTIVE()) when passing to constructors/setters — though get($value) handles raw scalars safely.
• Default fallbacks: Initialize default status in domain objects using UserStatus::INACTIVE() in the getter (lazy init) or constructor.
• EnumSet for multi-select: For permissions, roles, or statuses where users can have multiple values, use EnumSet for efficient set operations:

  $set = new EnumSet(UserStatus::class, [UserStatus::ACTIVE, UserStatus::INACTIVE]);
  $set->add(UserStatus::DELETED()); // mutable
  $set = $set->without(UserStatus::DELETED()); // immutable
  

• EnumMap for metadata: Map enums to labels, descriptions, or database codes:

  $map = new EnumMap(UserStatus::class);
  $map[UserStatus::ACTIVE] = 'Active';
  echo $map[UserStatus::ACTIVE]; // 'Active'
  

• Validation layer: In forms/DTOs, use UserStatus::byValue($input) or UserStatus::byName($input) for safe parsing — falls back to null if invalid, avoiding exceptions.

Gotchas and Tips

• Only public constants become enum values — protected/private are silently ignored; double-check constants are public.
• Enums are singletons per value: UserStatus::ACTIVE() === UserStatus::ACTIVE() is true, but UserStatus::get('a') === UserStatus::ACTIVE() also true — not true across different enum classes with same value.
• Type-hint trap: UserStatus $status accepts subclasses — to prevent this, final your enum class.
• Serialization: Avoid unless necessary — the provided EnumSerializableTrait helps but breaks singleton guarantees. Prefer storing raw values (e.g., 'a') and reconstructing on hydration.
• is() vs ===: Use $status->is(UserStatus::ACTIVE) — it handles both objects and raw values (UserStatus::ACTIVE constant or string 'a').
• PHP keywords work: Since PHP 7.0, TRUE, FUNCTION, etc., are safe as constant names — use them to map to reserved words (e.g., const FUNCTION = 'function').
• Performance: Enum operations are fast and memory-efficient; prefer getEnumerators() for bulk checks instead of looping byValue().
• Debugging tip: var_dump($status) shows internal singleton; use $status->getValue() for readable output.