DASPRiD Enum

https://github.com/dasprid/enum
Admin
A PHP 7.1+ enum implementation providing type-safe enumeration support with advanced features like...
Tokens:26,179
Snippets:170
Trust Score:9.6
License:BSD-2-Clause
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Direct sentinel access example

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Shows how to obtain the NullValue singleton and verify its identity. For advanced or internal use.

```php
use DASPRiD\Enum\NullValue;

$nullValue = NullValue::instance();

// The singleton identity is guaranteed:
assert(NullValue::instance() === $nullValue);
```

--------------------------------

### Use the WeekDay enum in a switch statement

Source: https://github.com/dasprid/enum/blob/master/README.md

Shows how to use the WeekDay enum instances in a switch statement. The magic methods return singleton instances, and the example calls them directly to demonstrate the output for each day.

```php
function tellItLikeItIs(WeekDay $weekDay)
{
    switch ($weekDay) {
        case WeekDay::MONDAY():
            echo 'Mondays are bad.';
            break;

        case WeekDay::FRIDAY():
            echo 'Fridays are better.';
            break;

        case WeekDay::SATURDAY():
        case WeekDay::SUNDAY():
            echo 'Weekends are best.';
            break;

        default:
            echo 'Midweek days are so-so.';
    }
}

tellItLikeItIs(WeekDay::MONDAY());
tellItLikeItIs(WeekDay::WEDNESDAY());
tellItLikeItIs(WeekDay::FRIDAY());
tellItLikeItIs(WeekDay::SATURDAY());
tellItLikeItIs(WeekDay::SUNDAY());
```

--------------------------------

### Basic EnumMap usage with WeekDay keys

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Creates an EnumMap mapping WeekDay enum keys to string values. Demonstrates put, get, size, containsKey, containsValue, values, iteration, and replacing an existing mapping. Values are returned in key declaration order, not insertion order.

```php
use DASPRiD\Enum\EnumMap;

// Map each weekday to an opening-hours label:
$hours = new EnumMap(WeekDay::class, 'string', false);
$hours->put(WeekDay::MONDAY(), '09:00-17:00');
$hours->put(WeekDay::TUESDAY(), '09:00-17:00');
$hours->put(WeekDay::SATURDAY(), '10:00-14:00');

echo $hours->size();                      // 3
echo $hours->get(WeekDay::MONDAY());      // "09:00-17:00"
var_dump($hours->containsKey(WeekDay::WEDNESDAY())); // bool(false)
var_dump($hours->containsValue('09:00-17:00'));      // bool(true)

// Values in key (declaration) order, not insertion order:
print_r($hours->values());                // ["09:00-17:00","09:00-17:00","10:00-14:00"]

// Iteration yields enum key => value:
foreach ($hours as $day => $label) {
    printf("%s: %s\n", $day->name(), $label);
}

// Replace an existing mapping:
$old = $hours->put(WeekDay::MONDAY(), '08:00-16:00');  // "09:00-17:00"
echo $old;
```

--------------------------------

### Basic enum definition and access with AbstractEnum

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Defines a WeekDay enum with protected constants and demonstrates magic static access, valueOf(), values(), and compareTo(). The magic static method returns a singleton instance; ordinal() starts at 0 for the first constant.

```php
use DASPRiD\Enum\AbstractEnum;

/**
 * @method static self MONDAY()
 * @method static self TUESDAY()
 * @method static self WEDNESDAY()
 * @method static self THURSDAY()
 * @method static self FRIDAY()
 * @method static self SATURDAY()
 * @method static self SUNDAY()
 */
final class WeekDay extends AbstractEnum
{
    protected const MONDAY    = null;
    protected const TUESDAY   = null;
    protected const WEDNESDAY = null;
    protected const THURSDAY  = null;
    protected const FRIDAY    = null;
    protected const SATURDAY  = null;
    protected const SUNDAY    = null;
}

// Call-site usage — the magic static method returns the singleton instance:
$day = WeekDay::FRIDAY();

echo $day->name();                 // "FRIDAY"
echo $day->ordinal();              // 4
echo (string) $day;                // "FRIDAY"

// valueOf() is the non-magic equivalent:
$wednesday = WeekDay::valueOf('WEDNESDAY');
assert($wednesday === WeekDay::WEDNESDAY());   // same instance

// values() returns every constant, in declaration order:
foreach (WeekDay::values() as $weekDay) {
    printf("%d => %s\n", $weekDay->ordinal(), $weekDay);
}

// Natural ordering via compareTo():
if (WeekDay::WEDNESDAY()->compareTo(WeekDay::SUNDAY()) < 0) {
    // Wednesday comes before Sunday
}
```

--------------------------------

### get(AbstractEnum $key)

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key. A return value of `null` does not necessarily indicate that the map contains no mapping for the key — it is also possible that the map explicitly maps the key to `null`.

```APIDOC
## get(AbstractEnum $key)

### Description
Returns the value to which the specified key is mapped, or `null` if this map contains no mapping for the key. A return value of `null` does not necessarily indicate that the map contains no mapping for the key — it is also possible that the map explicitly maps the key to `null`. Use `containsKey()` to distinguish these two cases.

### Method
get

### Parameters
- **$key** (AbstractEnum) - Required - The enum key; must be an instance of exactly the map's `keyType`.

### Returns
mixed - the mapped value, or `null` when unmapped or explicitly mapped to `null`.

### Throws
- `DASPRiD\Enum\Exception\IllegalArgumentException` - when the key is not an instance of the map's `keyType` (see `put`).
```

--------------------------------

### ordinal()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Returns the ordinal of this enumeration constant, which is its position in the enum declaration starting from zero. Useful for ordering or indexing.

```APIDOC
## ordinal()

### Description
Returns the ordinal of this enumeration constant (its position in the enum declaration, where the initial constant is assigned ordinal zero).

### Method
`final public function ordinal() : int`

### Returns
`int` — e.g. `2` for the third declared constant.

```

--------------------------------

### AbstractEnum::ordinal()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Returns the ordinal (position) of the enum instance, starting from 0 for the first declared constant. Useful for ordering or indexing.

```APIDOC
## [INSTANCE] AbstractEnum::ordinal()

### Description
Returns the ordinal (position) of the enum instance, starting from 0 for the first declared constant. Useful for ordering or indexing.

### Method
Instance method

### Endpoint
`$enum->ordinal()`

### Parameters
None

### Response
#### Success Response
- Returns the ordinal as an integer.

### Example
```php
echo $day->ordinal(); // 4
```
```

--------------------------------

### Iterate over Planet enum values and compute surface weight

Source: https://github.com/dasprid/enum/blob/master/README.md

Uses Planet::values() to iterate over all enum instances and prints the surface weight for a given mass. The printf format uses the enum instance's string representation and the surfaceWeight method.

```php
$myMass = 80;

foreach (Planet::values() as $planet) {
    printf("Your weight on %s is %f\n", $planet, $planet->surfaceWeight($myMass));
}
```

--------------------------------

### Magic static methods (e.g., WeekDay::FRIDAY())

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Each protected constant can be accessed as a static method that returns the singleton instance. The method name is the constant name in uppercase.

```APIDOC
## [STATIC] Magic static methods (e.g., WeekDay::FRIDAY())

### Description
Each protected constant can be accessed as a static method that returns the singleton instance. The method name is the constant name in uppercase.

### Method
Static method (magic)

### Endpoint
`EnumClass::CONSTANT_NAME()`

### Parameters
None

### Response
#### Success Response
- Returns the singleton enum instance for that constant.

### Example
```php
$day = WeekDay::FRIDAY();
```
```

--------------------------------

### Define a complex enum with data and methods (Planet)

Source: https://github.com/dasprid/enum/blob/master/README.md

Defines a more complex enum where each constant holds an array of mass and radius values. The constructor is protected and takes those values, and the enum provides methods to compute surface gravity and weight. Enums are singletons and cannot be cloned or serialized.

```php
use DASPRiD\Enum\AbstractEnum;

/**
 * @method static self MERCURY()
 * @method static self VENUS()
 * @method static self EARTH()
 * @method static self MARS()
 * @method static self JUPITER()
 * @method static self SATURN()
 * @method static self URANUS()
 * @method static self NEPTUNE()
 */
final class Planet extends AbstractEnum
{
    protected const MERCURY = [3.303e+23, 2.4397e6];
    protected const VENUS = [4.869e+24, 6.0518e6];
    protected const EARTH = [5.976e+24, 6.37814e6];
    protected const MARS = [6.421e+23, 3.3972e6];
    protected const JUPITER = [1.9e+27, 7.1492e7];
    protected const SATURN = [5.688e+26, 6.0268e7];
    protected const URANUS = [8.686e+25, 2.5559e7];
    protected const NEPTUNE = [1.024e+26, 2.4746e7];

    /**
     * Universal gravitational constant.
     *
     * @var float
     */
    private const G = 6.67300E-11;

    /**
     * Mass in kilograms.
     *
     * @var float
     */
    private $mass;

    /**
     * Radius in meters.
     *
     * @var float
     */
    private $radius;

    protected function __construct(float $mass, float $radius)
    {
        $this->mass = $mass;
        $this->radius = $radius;
    }

    public function mass() : float
    {
        return $this->mass;
    }

    public function radius() : float
    {
        return $this->radius;
    }

    public function surfaceGravity() : float
    {
        return self::G * $this->mass / ($this->radius * $this->radius);
    }

    public function surfaceWeight(float $otherMass) : float
    {
        return $otherMass * $this->surfaceGravity();
    }
}
```

--------------------------------

### Nullable values, contract checking, and error handling with EnumMap

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Shows how to allow null values, verify a map's contract with expect(), and handle IllegalArgumentException for invalid null, wrong key type, and invalid key class. Also demonstrates serialization round-trip.

```php
use DASPRiD\Enum\EnumMap;
use DASPRiD\Enum\Exception\ExpectationException;
use DASPRiD\Enum\Exception\IllegalArgumentException;

// allowNullValues = true lets you explicitly map a key to null:
$preferences = new EnumMap(WeekDay::class, 'bool', true);
$preferences->put(WeekDay::MONDAY(), true);
$preferences->put(WeekDay::TUESDAY(), null);   // present, but null

var_dump($preferences->containsKey(WeekDay::TUESDAY())); // bool(true)
var_dump($preferences->get(WeekDay::TUESDAY()));         // null
var_dump($preferences->containsValue(null));             // bool(true)

// Verifying the contract of a map received from elsewhere:
function render(EnumMap $map) : void
{
    try {
        $map->expect(WeekDay::class, 'bool', true);
    } catch (ExpectationException $e) {
        // map does not match the expected (key, value, nullable) contract
        return;
    }
    foreach ($map as $day => $flag) {
        printf("%s => %s\n", $day->name(), $flag === null ? 'unset' : ($flag ? 'yes' : 'no'));
    }
}

// Error handling:
try {
    $lonely = new EnumMap(WeekDay::class, 'string', false);
    $lonely->put(WeekDay::MONDAY(), null);          // null not allowed here
} catch (IllegalArgumentException $e) {
    echo $e->getMessage();                          // "Value is not of type string"
}

try {
    $map = new EnumMap(WeekDay::class, 'string', false);
    $map->put(Planet::EARTH(), 'nope');             // key of wrong enum type
} catch (IllegalArgumentException $e) {
    echo $e->getMessage();                          // "Object of type ... is not the same type as ..."
}

try {
    new EnumMap(\stdClass::class, 'string', false); // key type must extend AbstractEnum
} catch (IllegalArgumentException $e) {
    echo $e->getMessage();                          // "Class stdClass does not extend DASPRiD\Enum\AbstractEnum"
}

// Maps round-trip through serialize()/unserialize():
$copy = unserialize(serialize($preferences));
var_dump($copy->equals($preferences));              // bool(true)
```

--------------------------------

### __serialize

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Magic-method serialization; returns the same data array used by `serialize()`.

```APIDOC
## __serialize

### Description
Magic-method serialization; returns the same data array used by `serialize()`.

### Method
`__serialize`

### Signature
```php
public function __serialize(): array
```

### Returns
- **array** - Keys `keyType`, `valueType`, `allowNullValues`, `values` (mapping ordinal → unmasked value for mapped slots only).
```

--------------------------------

### Constructor: __construct

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Creates a new EnumMap instance with the specified key enum type, value type, and null value allowance. The key type must be a subclass of AbstractEnum, and the value type must be a valid type identifier or class name.

```APIDOC
## Constructor: __construct

### Description
Creates a new EnumMap instance with the specified key enum type, value type, and null value allowance. The key type must be a subclass of AbstractEnum, and the value type must be a valid type identifier or class name.

### Method
Constructor

### Signature
```php
public function __construct(string $keyType, string $valueType, bool $allowNullValues)
```

### Parameters
- **$keyType** (string) - Required - The class name (FQCN) of the key enum; must be a subclass of `DASPRiD\Enum\AbstractEnum`.
- **$valueType** (string) - Required - The type of the values; one of the value-type identifiers (`mixed`, `bool`/`boolean`, `int`/`integer`, `float`/`double`, `string`, `object`, `array`) or any class name.
- **$allowNullValues** (bool) - Required - Whether values may be `null`.

### Throws
- `DASPRiD\Enum\Exception\IllegalArgumentException` - If `$keyType` is not a subclass of `AbstractEnum` (`! is_subclass_of($keyType, AbstractEnum::class)`). Message: `Class <KeyType> does not extend DASPRiD\Enum\AbstractEnum`.

### Example
```php
$map = new EnumMap(MyEnum::class, 'string', true);
```
```

--------------------------------

### Parameterized enum and error handling with AbstractEnum

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Shows a Planet enum with constructor arguments and demonstrates exceptions for unknown constants, cloning, serialization, and cross-type comparison. The constructor must be protected; cloning and serialization are always rejected.

```php
use DASPRiD\Enum\AbstractEnum;
use DASPRiD\Enum\Exception\CloneNotSupportedException;
use DASPRiD\Enum\Exception\IllegalArgumentException;
use DASPRiD\Enum\Exception\MismatchException;

// Parameterized enum: the protected-constant value is an array of
// constructor arguments; the class constructor must be protected.
/**
 * @method static self MERCURY()
 * @method static self VENUS()
 * @method static self EARTH()
 */
final class Planet extends AbstractEnum
{
    protected const MERCURY = [3.303e+23, 2.4397e6];
    protected const VENUS   = [4.869e+24, 6.0518e6];
    protected const EARTH   = [5.976e+24, 6.37814e6];

    private const G = 6.67300E-11;

    /** @var float */
    private $mass;

    /** @var float */
    private $radius;

    protected function __construct(float $mass, float $radius)
    {
        $this->mass = $mass;
        $this->radius = $radius;
    }

    public function surfaceGravity() : float
    {
        return self::G * $this->mass / ($this->radius * $this->radius);
    }
}

// 1. Unknown constant name:
try {
    WeekDay::valueOf('CATURDAY');
} catch (IllegalArgumentException $e) {
    echo $e->getMessage(); // "No enum constant DASPRiD\EnumTest\WeekDay::CATURDAY"
}

// 2. Cloning or serializing is always rejected:
try {
    clone WeekDay::MONDAY();
} catch (CloneNotSupportedException $e) {
    // enum instances cannot be cloned
}

try {
    serialize(WeekDay::MONDAY());
} catch (\DASPRiD\Enum\Exception\SerializeNotSupportedException $e) {
    // enum instances cannot be serialized
}

// 3. Comparing across enum types:
try {
    WeekDay::MONDAY()->compareTo(Planet::EARTH());
} catch (MismatchException $e) {
    // "The passed enum ... is not of the same type as ..."
}

// 4. Parameterized value access:
printf("Earth surface gravity: %f\n", Planet::EARTH()->surfaceGravity());
```

--------------------------------

### __callStatic

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Magic static method that forwards calls to valueOf(). Enables syntax like WeekDay::MONDAY().

```APIDOC
## __callStatic

### Description
Magic getter which forwards all calls to `valueOf()`. This is what powers the `WeekDay::MONDAY()` syntax.

### Method
`final public static function __callStatic(string $name, array $arguments) : self`

### Parameters
- `$name` (string) - Required - The name of the enum constant, e.g. `'MONDAY'`.
- `$arguments` (array) - Required - Ignored; any arguments passed to a magic static call are discarded and the call becomes `valueOf($name)`.

### Returns
`self` (static) — the enum instance for the given constant name.

### Throws
`DASPRiD\Enum\Exception\IllegalArgumentException` when no constant with the given name exists (delegated to `valueOf()`).
```

--------------------------------

### Error handling for clone, serialize, unserialize

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Shows that cloning, serializing, and unserializing NullValue always throw the corresponding exceptions.

```php
use DASPRiD\Enum\NullValue;
use DASPRiD\Enum\Exception\CloneNotSupportedException;
use DASPRiD\Enum\Exception\SerializeNotSupportedException;
use DASPRiD\Enum\Exception\UnserializeNotSupportedException;

try {
    clone NullValue::instance();
} catch (CloneNotSupportedException $e) {
    // singleton cannot be cloned
}

try {
    serialize(NullValue::instance());
} catch (SerializeNotSupportedException $e) {
    // singleton cannot be serialized
}

try {
    unserialize('O:22:"DASPRiD\\Enum\\NullValue":0:{}');
} catch (UnserializeNotSupportedException $e) {
    // singleton cannot be unserialized
}
```

--------------------------------

### __unserialize

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Magic-method unserialization. The source implementation routes through the legacy path: `$this->unserialize(serialize($data));`.

```APIDOC
## __unserialize

### Description
Magic-method unserialization. The source implementation routes through the legacy path: `$this->unserialize(serialize($data));`.

### Method
`__unserialize`

### Signature
```php
public function __unserialize(array $data): void
```

### Parameters
- **$data** (array) - Required - Payload produced by `__serialize()`.
```

--------------------------------

### EnumMap constructor signature

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Declares the constructor for DASPRiD\Enum\EnumMap. Requires the key enum FQCN, a value type identifier or class name, and whether null values are allowed. Throws IllegalArgumentException if the key type is not a subclass of AbstractEnum.

```php
public function __construct(string $keyType, string $valueType, bool $allowNullValues)
```

--------------------------------

### Define a simple enum with AbstractEnum (WeekDay)

Source: https://github.com/dasprid/enum/blob/master/README.md

Defines a basic enum by extending DASPRiD\Enum\AbstractEnum with protected constants set to null. The class-level docblock generates magic static methods for IDE autocompletion. Only protected constants are considered valid enum values; private and public constants are ignored.

```php
use DASPRiD\Enum\AbstractEnum;

/**
 * @method static self MONDAY()
 * @method static self TUESDAY()
 * @method static self WEDNESDAY()
 * @method static self THURSDAY()
 * @method static self FRIDAY()
 * @method static self SATURDAY()
 * @method static self SUNDAY()
 */
final class WeekDay extends AbstractEnum
{
    protected const MONDAY = null;
    protected const TUESDAY = null;
    protected const WEDNESDAY = null;
    protected const THURSDAY = null;
    protected const FRIDAY = null;
    protected const SATURDAY = null;
    protected const SUNDAY = null;
}
```

--------------------------------

### NullValue::instance() static method

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Returns the single shared NullValue instance, creating it lazily on first call. Always returns the identical object; NullValue::instance() === NullValue::instance() is true.

```php
public static function instance() : self
```

--------------------------------

### NullValue::__clone() magic method

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Final method that always throws CloneNotSupportedException to preserve the singleton guarantee.

```php
final public function __clone()
```

--------------------------------

### NullValue::__wakeup() magic method

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Final method that always throws UnserializeNotSupportedException to prevent unserialization.

```php
final public function __wakeup() : void
```

--------------------------------

### ExceptionInterface marker interface

Source: https://github.com/dasprid/enum/blob/master/_autodocs/types.md

Root marker interface for the library's exception hierarchy. Every library exception implements it, allowing consumers to catch any library-originated failure via ExceptionInterface. The interface extends Throwable, so implementing objects are catchable via Throwable and expose the full Throwable contract.

```php
interface ExceptionInterface extends Throwable
{
}
```

--------------------------------

### __toString()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Converts the enum to a string representation. The base implementation returns the exact constant name; subclasses may override to provide a more user-friendly version.

```APIDOC
## __toString()

### Description
Turns the enum into a string representation. The base implementation returns `$this->name`; subclasses may override this method to give a more user-friendly version.

### Method
`public function __toString() : string`

### Returns
`string` — the exact constant name by default.

```

--------------------------------

### size() : int

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Returns the number of key-value mappings in this map.

```APIDOC
## size() : int

### Description
Returns the number of key-value mappings in this map.

### Method
size

### Returns
int.
```

--------------------------------

### EnumMap::__construct(string $keyType, string $valueType, bool $allowNullValues)

Source: https://github.com/dasprid/enum/blob/master/_autodocs/types.md

Creates a new EnumMap instance with the specified key and value types. Optionally allows null values.

```APIDOC
## EnumMap::__construct(string $keyType, string $valueType, bool $allowNullValues)

### Description
Creates a new EnumMap instance with the specified key and value types. Optionally allows null values.

### Method
__construct

### Signature
`public function __construct(string $keyType, string $valueType, bool $allowNullValues)`

### Parameters
- **$keyType** (string) - Required - The class name of the enum used as keys.
- **$valueType** (string) - Required - The class name of the enum used as values.
- **$allowNullValues** (bool) - Required - Whether null values are allowed.

### Return Value
- **EnumMap** - The new instance.

```

--------------------------------

### NullValue::__serialize() magic method

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Final method that always throws SerializeNotSupportedException to prevent serialization.

```php
final public function __serialize() : array
```

--------------------------------

### compareTo()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Compares this enum with another enum of the same type for order. Returns a negative, zero, or positive integer based on declaration order (ordinal difference). Throws an exception if the other enum is not of the same type.

```APIDOC
## compareTo()

### Description
Compares this enum with the specified object for order. Returns a negative integer, zero, or a positive integer as this object is less than, equal to, or greater than the specified object. The natural order is the declaration order (ordinal difference).

### Method
`final public function compareTo(self $other) : int`

### Parameters
- `$other` (self) - Required - The enum to compare against.

### Returns
`int` — `$this->ordinal - $other->ordinal` (only reached when `$other instanceof static`).

### Throws
- `DASPRiD\Enum\Exception\MismatchException` - The passed enum is not `instanceof static` (i.e. a different enum type). Message: `The passed enum <OtherClass> is not of the same type as <ThisClass>`.

```

--------------------------------

### expect()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Checks whether the map's types match the supplied ones. Call this method when an EnumMap is passed to you (e.g. as a method parameter) and you want to ensure it is made up of the correct types.

```APIDOC
## expect()

### Description
Checks whether the map's types match the supplied ones. Call this method when an EnumMap is passed to you (e.g. as a method parameter) and you want to ensure it is made up of the correct types.

### Method
expect

### Signature
```php
public function expect(string $keyType, string $valueType, bool $allowNullValues) : void
```

### Parameters
- **$keyType** (string) - Required - Expected key type (FQCN of the enum class).
- **$valueType** (string) - Required - Expected value type identifier or class name.
- **$allowNullValues** (bool) - Required - Expected nullability flag.

### Returns
- **void** - nothing when all three match.

### Throws
- **DASPRiD\Enum\Exception\ExpectationException** - in exactly these cases (each with a distinct message):
  - If $keyType !== $this->keyType: `Callee expected an EnumMap with key type <expected>, but got <actual>`
  - If $valueType !== $this->valueType: `Callee expected an EnumMap with value type ...` — note: the message interpolates the **key** types ($keyType / $this->keyType), matching the source verbatim at src/EnumMap.php:138-145; the actual value types are not printed.
  - If $allowNullValues !== $this->allowNullValues: `Callee expected an EnumMap with nullable flag <expected>, but got <actual>`
```

--------------------------------

### Catch marker interface ExceptionInterface for uniform library error handling

Source: https://github.com/dasprid/enum/blob/master/_autodocs/errors.md

Handles any library-originated exception uniformly by catching the marker interface ExceptionInterface. Catches IllegalArgumentException, ExpectationException, MismatchException, and others from EnumMap operations.

```php
use DASPRiD\Enum\Exception\ExceptionInterface;

try {
    $value = $map->put($key, $invalidValue);   // EnumMap operations
} catch (ExceptionInterface $e) {
    // any library-originated exception (IllegalArgumentException,
    // ExpectationException, MismatchException, ...) lands here
    error_log($e->getMessage());
}
```

--------------------------------

### values

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Obtains all possible enum instances defined by this enum type. The result is cached per class and sorted by declaration order.

```APIDOC
## values

### Description
Obtains all possible enum instances defined by this enum type.

### Method
`final public static function values() : array`

### Parameters
No parameters.

### Returns
`array` — a list of `static[]` instances covering every protected constant of the enum, sorted by ordinal (declaration order). The result is cached per class in the static `self::$allValuesLoaded` flag; repeated calls return the identical array. Initialization order does not affect the result: `values()` runs `uasort()` over `ordinal()` so the result is always declaration order even if some instances were created out of order beforehand.
```

--------------------------------

### NullValue::__unserialize() magic method

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Final method that always throws UnserializeNotSupportedException. The $arg parameter is never consumed.

```php
final public function __unserialize($arg) : void
```

--------------------------------

### EnumMap usage with null value

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Demonstrates that a key explicitly mapped to null is stored via NullValue but callers only see null. containsKey() returns true for such keys.

```php
use DASPRiD\Enum\EnumMap;

$prefs = new EnumMap(WeekDay::class, 'string', true);
$prefs->put(WeekDay::WEDNESDAY(), null);

// The null was stored via NullValue, but callers only ever see null:
var_dump($prefs->get(WeekDay::WEDNESDAY()));          // null
var_dump($prefs->containsKey(WeekDay::WEDNESDAY()));  // true
```

--------------------------------

### NullValue private constructor

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Private constructor prevents direct instantiation. The class is a singleton, not cloneable, and not serializable.

```php
private function __construct()
```

--------------------------------

### EnumMap::expect(string $keyType, string $valueType, bool $allowNullValues) : void

Source: https://github.com/dasprid/enum/blob/master/_autodocs/types.md

Validates that the map's key and value types match the given types. Throws an exception if they do not.

```APIDOC
## EnumMap::expect(string $keyType, string $valueType, bool $allowNullValues) : void

### Description
Validates that the map's key and value types match the given types. Throws an exception if they do not.

### Method
expect

### Signature
`public function expect(string $keyType, string $valueType, bool $allowNullValues) : void`

### Parameters
- **$keyType** (string) - Required - Expected key type.
- **$valueType** (string) - Required - Expected value type.
- **$allowNullValues** (bool) - Required - Expected null value allowance.

### Return Value
- **void**

```

--------------------------------

### unserialize

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Restores the map, re-running the `__construct()` logic from the stored type configuration and re-inserting stored values via `put()`.

```APIDOC
## unserialize

### Description
Restores the map, re-running the `__construct()` logic from the stored type configuration and re-inserting stored values via `put()`.

### Method
`unserialize`

### Signature
```php
public function unserialize($serialized) : void
```

### Parameters
- **$serialized** (mixed) - Required - The serialized payload produced by `serialize()`.
```

--------------------------------

### name()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Returns the exact name of this enum constant as declared. Primarily for specialized situations where correctness depends on the exact name; prefer __toString() for user-friendly names.

```APIDOC
## name()

### Description
Returns the name of this enum constant, exactly as declared in its enum declaration. Most programmers should prefer `__toString()`, which may return a more user-friendly name; `name()` is designed primarily for specialized situations where correctness depends on the exact name.

### Method
`final public function name() : string`

### Returns
`string` — e.g. `'WEDNESDAY'`.

```

--------------------------------

### serialize

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Serializes the map into a string representation. Returns a serialized representation containing keyType, valueType, allowNullValues, and the masked values indexed by ordinal (unmapped slots omitted).

```APIDOC
## serialize

### Description
Serializes the map into a string representation. Returns a serialized representation containing `keyType`, `valueType`, `allowNullValues`, and the masked values indexed by ordinal (unmapped slots omitted).

### Method
`serialize`

### Signature
```php
public function serialize() : string
```

### Returns
- **string** - A serialized representation containing `keyType`, `valueType`, `allowNullValues`, and the masked values indexed by ordinal (unmapped slots omitted).
```

--------------------------------

### AbstractEnum::__toString() : string

Source: https://github.com/dasprid/enum/blob/master/_autodocs/types.md

Returns a string representation of the enum instance, typically the constant name.

```APIDOC
## AbstractEnum::__toString() : string

### Description
Returns a string representation of the enum instance, typically the constant name.

### Method
__toString

### Signature
`public function __toString() : string`

### Return Value
- **string** - String representation.

```

--------------------------------

### AbstractEnum::values()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Returns an array of all enum instances in declaration order. Useful for iterating over all possible values.

```APIDOC
## [STATIC] AbstractEnum::values()

### Description
Returns an array of all enum instances in declaration order. Useful for iterating over all possible values.

### Method
Static method

### Endpoint
`AbstractEnum::values()`

### Parameters
None

### Response
#### Success Response
- Returns an array of enum instances, one for each defined constant, in declaration order.

### Example
```php
foreach (WeekDay::values() as $weekDay) {
    printf("%d => %s\n", $weekDay->ordinal(), $weekDay);
}
```
```

--------------------------------

### AbstractEnum::compareTo()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Compares this enum with another enum of the same type. Returns a negative integer, zero, or a positive integer if this enum is less than, equal to, or greater than the specified enum. Throws MismatchException if the other enum is not of the same type.

```APIDOC
## [INSTANCE] AbstractEnum::compareTo()

### Description
Compares this enum with another enum of the same type. Returns a negative integer, zero, or a positive integer if this enum is less than, equal to, or greater than the specified enum. Throws MismatchException if the other enum is not of the same type.

### Method
Instance method

### Endpoint
`$enum->compareTo(AbstractEnum $other)`

### Parameters
- **$other** (AbstractEnum) - Required - The enum to compare against.

### Response
#### Success Response
- Returns an integer less than 0 if this enum is before the other, 0 if equal, or greater than 0 if after.

#### Error Response
- **MismatchException** - If the other enum is not of the same type.

### Example
```php
if (WeekDay::WEDNESDAY()->compareTo(WeekDay::SUNDAY()) < 0) {
    // Wednesday comes before Sunday
}
```
```

--------------------------------

### NullValue::instance() : self

Source: https://github.com/dasprid/enum/blob/master/_autodocs/types.md

Returns the singleton instance of the NullValue sentinel class.

```APIDOC
## NullValue::instance() : self

### Description
Returns the singleton instance of the NullValue sentinel class.

### Method
instance

### Signature
`public static function instance() : self`

### Return Value
- **self** - The singleton instance.

```

--------------------------------

### clear() : void

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Removes all mappings from this map. Resets the internal value array (one `null` slot per key constant) and sets `size` to `0`.

```APIDOC
## clear() : void

### Description
Removes all mappings from this map. Resets the internal value array (one `null` slot per key constant) and sets `size` to `0`.

### Method
clear

### Returns
void - nothing.
```

--------------------------------

### getIterator()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Returns an iterator over the map. Each yielded entry is key => value where key is the enum instance and value the mapped value (with NullValue unmasked to null). Unmapped slots are skipped. Implemented as a generator.

```APIDOC
## getIterator()

### Description
Returns an iterator over the map. Each yielded entry is key => value where key is the enum instance and value the mapped value (with NullValue unmasked to null). Unmapped slots are skipped. Implemented as a generator.

### Method
getIterator

### Signature
```php
public function getIterator() : Traversable
```

### Returns
- **Traversable** - usable directly in foreach ($map as $key => $value).
```

--------------------------------

### values()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Returns the values contained in this map. The array contains the values in the order their corresponding keys appear in the map, which is their natural order (declaration order of the enum constants). Unmapped slots are filtered out; null values (explicit mappings) are preserved.

```APIDOC
## values()

### Description
Returns the values contained in this map. The array contains the values in the order their corresponding keys appear in the map, which is their natural order (declaration order of the enum constants). Unmapped slots are filtered out; null values (explicit mappings) are preserved.

### Method
values

### Signature
```php
public function values() : array
```

### Returns
- **array** - a list of the mapped values, in key order.
```

--------------------------------

### Catch native Exception and Throwable for broad error handling

Source: https://github.com/dasprid/enum/blob/master/_autodocs/errors.md

Catches library errors via ExceptionInterface and everything else via \Throwable. Since every library exception extends Exception, this strategy covers all failure modes including type errors.

```php
try {
    foreach ($map as $key => $value) { /* ... */ }
} catch (ExceptionInterface $e) {
    // library errors
} catch (\Throwable $e) {
    // everything else (type errors, etc.)
}
```

--------------------------------

### EnumMap null masking in put()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Shows how EnumMap wraps a null value with NullValue before storing it in the internal array.

```php
$this->values[$index] = $this->maskNull($value);
```

--------------------------------

### NullValue::__sleep() magic method

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/NullValue.md

Final method that always throws SerializeNotSupportedException to prevent serialization.

```php
final public function __sleep() : array
```

--------------------------------

### put(AbstractEnum $key, $value)

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced.

```APIDOC
## put(AbstractEnum $key, $value)

### Description
Associates the specified value with the specified key in this map. If the map previously contained a mapping for the key, the old value is replaced.

### Method
put

### Parameters
- **$key** (AbstractEnum) - Required - The enum key; must be an instance of exactly the map's `keyType`.
- **$value** (mixed) - Required - Value to store; must satisfy `isValidValue()` against `valueType` and the null policy.

### Returns
mixed - the previous value associated with the specified key, or `null` if there was no mapping for the key. (A `null` return can also indicate that the map previously associated `null` with the specified key.) Only increments `size` when the previous slot was unmapped.

### Throws
- `DASPRiD\Enum\Exception\IllegalArgumentException` - The key is not an instance of the map's `keyType` (`get_class($key) !== $this->keyType`). Message: `Object of type <KeyClass> is not the same type as <KeyType>`.
- `DASPRiD\Enum\Exception\IllegalArgumentException` - The value is invalid for `valueType` (including `null` when `allowNullValues` is `false`). Message: `Value is not of type <ValueType>`.
```

--------------------------------

### AbstractEnum::valueOf()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Returns the singleton enum instance for the given constant name. Throws IllegalArgumentException if the name does not match any defined constant.

```APIDOC
## [STATIC] AbstractEnum::valueOf()

### Description
Returns the singleton enum instance for the given constant name. Throws IllegalArgumentException if the name does not match any defined constant.

### Method
Static method

### Endpoint
`AbstractEnum::valueOf(string $name)`

### Parameters
- **$name** (string) - Required - The name of the enum constant.

### Response
#### Success Response
- Returns the enum instance corresponding to the given name.

#### Error Response
- **IllegalArgumentException** - If no enum constant with the given name exists.

### Example
```php
$wednesday = WeekDay::valueOf('WEDNESDAY');
```
```

--------------------------------

### equals

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/EnumMap.md

Compares the specified map with this map for equality. Returns true if the two maps represent the same mappings (same type configuration and identical masked value arrays).

```APIDOC
## equals

### Description
Compares the specified map with this map for equality. Returns `true` if the two maps represent the same mappings (same type configuration and identical masked value arrays).

### Method
`equals`

### Signature
```php
public function equals(self $other) : bool
```

### Parameters
- **$other** (`self`) - Required - Another `EnumMap`.

### Returns
- **bool** - `true` for the same instance, or when sizes match and the internal `values` arrays are identical.
```

--------------------------------

### valueOf

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Returns an enum instance for the specified constant name. The name must match exactly an identifier used to declare an enum constant in this type.

```APIDOC
## valueOf

### Description
Returns an enum with the specified name. The name must match exactly an identifier used to declare an enum constant in this type (extraneous whitespace characters are not permitted).

### Method
`final public static function valueOf(string $name) : self`

### Parameters
- `$name` (string) - Required - Exact constant name, as declared in the enum class.

### Returns
`self` (static) — the singleton instance for that constant.

### Throws
- `DASPRiD\Enum\Exception\IllegalArgumentException` - No constant with the specified name exists in this enum type. Message: `No enum constant <Class>::<name>` (e.g. `No enum constant DASPRiD\EnumTest\WeekDay::CATURDAY`).
```

--------------------------------

### AbstractEnum::__construct()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Private constructor for the AbstractEnum base class. It is private by default to prevent arbitrary enum creation; subclasses may override it with a protected constructor to support parameterized enums.

```APIDOC
## [CONSTRUCTOR] AbstractEnum::__construct()

### Description
Private constructor for the AbstractEnum base class. It is private by default to prevent arbitrary enum creation; subclasses may override it with a protected constructor to support parameterized enums.

### Method
Constructor

### Signature
`private function __construct()`

### Parameters
None

### Notes
- The constructor is private by default to avoid arbitrary enum creation.
- When creating your own constructor for a parameterized enum, make sure to declare it as protected, so that the static methods are able to construct it.
- Avoid making it public, as that would allow creation of non-singleton enum instances.

### Throws
Not applicable (constructor is never invoked directly; internal instantiation happens in `private static createValue()`).
```

--------------------------------

### Exception hierarchy diagram

Source: https://github.com/dasprid/enum/blob/master/_autodocs/errors.md

Shows the class hierarchy of exceptions in the DASPRiD Enum library, all extending PHP's native Exception and implementing ExceptionInterface.

```text
Throwable
└── Exception
    ├── CloneNotSupportedException        (DASPRiD\Enum\Exception)
    ├── ExpectationException              (DASPRiD\Enum\Exception)
    ├── IllegalArgumentException          (DASPRiD\Enum\Exception)
    ├── MismatchException                 (DASPRiD\Enum\Exception)
    ├── SerializeNotSupportedException    (DASPRiD\Enum\Exception)
    └── UnserializeNotSupportedException  (DASPRiD\Enum\Exception)

DASPRiD\Enum\Exception\ExceptionInterface extends Throwable
└── implemented by all six classes above
```

--------------------------------

### AbstractEnum::name()

Source: https://github.com/dasprid/enum/blob/master/_autodocs/api-reference/AbstractEnum.md

Returns the name of the enum instance as a string. This is the constant name used to define the enum value.

```APIDOC
## [INSTANCE] AbstractEnum::name()

### Description
Returns the name of the enum instance as a string. This is the constant name used to define the enum value.

### Method
Instance method

### Endpoint
`$enum->name()`

### Parameters
None

### Response
#### Success Response
- Returns the name of the enum instance (e.g., "FRIDAY").

### Example
```php
echo $day->name(); // "FRIDAY"
```
```

--------------------------------

### EnumMap::getIterator() : Traversable

Source: https://github.com/dasprid/enum/blob/master/_autodocs/types.md

Returns an iterator for the map's entries.

```APIDOC
## EnumMap::getIterator() : Traversable

### Description
Returns an iterator for the map's entries.

### Method
getIterator

### Signature
`public function getIterator() : Traversable`

### Return Value
- **Traversable** - An iterator.

```
Tokens:
Raw