feat(validator): support UnitEnum in enum()

- Accept UnitEnum case instances and string case names; keep BackedEnum tryFrom behavior
- Add ColorEnum fixture and tests; document API and update changelog/roadmap
- Trim ISSUES.md now that UnitEnum support is implemented

Author: lemmon

AGENTS.md

@@ -20,7 +20,7 @@ Core validation logic lives in `src/Lemmon/Validator/`. Tests in `tests/` follow
 - **Shared:** `NumericConstraintsTrait` (min, max, multipleOf, etc.); `PipelineType` enum; variant enums `IpVersion`, `Base64Variant`, `UuidVariant` for format methods
 - **String formats:** email, URL, UUID, IP, hostname, domain, time, base64, hex, regex, datetime, date
 - **Schema validation:** AssociativeValidator/ObjectValidator with nested error aggregation; shared `SchemaValidatorOptionsTrait` (`coerceAll`, `passthrough`, schema clone helper); `passthrough()` keeps undeclared keys/properties (unvalidated); default output is schema keys only
-- **Logical combinators:** `Validator::allOf`, `anyOf`, `not`; instance `satisfiesAny`, `satisfiesAll`, `satisfiesNone`; `const()` for single allowed value; `enum()` for BackedEnum
+- **Logical combinators:** `Validator::allOf`, `anyOf`, `not`; instance `satisfiesAny`, `satisfiesAll`, `satisfiesNone`; `const()` for single allowed value; `enum()` for `BackedEnum` and `UnitEnum`
 - **Behavior:** Optional by default (null allowed unless `required()`); form-safe coercion (empty string → null, not 0/false); pipeline order guaranteed; fail-fast per field; `satisfies()` accepts validators or callables with `(value, key, input)`; extend via `satisfies()`, not custom validators
 
 ## Build, Test, and Development Commands

CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- `enum()` on `FieldValidator` now accepts PHP `UnitEnum` (non-backed enums): the value must be an instance of the enum or a string equal to one of the case names; `BackedEnum` behavior is unchanged (int or string backed values via `tryFrom()`)
+
 ## [0.15.0] - 2026-04-15
 
 ### Fixed

ISSUES.md

@@ -2,31 +2,7 @@
 
 This document tracks identified bugs, architectural inconsistencies, and potential improvements for the Lemmon Validator library.
 
-## 1. Architectural Suggestions
-
-### IntValidator Coercion Precision
-
-`IntValidator` uses `is_numeric()` during coercion, which means a string like `"1.5"` is successfully coerced (truncated) to `1`. While "form-safe," this truncation can hide data precision issues. Consider providing a way to enforce strict integer strings or documenting this behavior clearly.
-
-### UnitEnum Support
-
-The `enum()` validator currently only supports `BackedEnum`. Adding support for basic `UnitEnum` (cases only) would increase utility for projects that do not use backed values for all enums.
-
-### Mixed Type Coercion in Combinators
-
-The static combinators `Validator::anyOf()`, `allOf()`, and `not()` return a "mixed" validator that does not support top-level coercion. Users expecting coercion must enable it on individual sub-validators.
-
----
-
-## 2. Feature Suggestions
-
-### Built-in String Sanitizers
-
-Common operations like `trim()`, `lowercase()`, and `uppercase()` are currently implemented via `pipe('trim')`. Adding them as first-class methods (e.g., `->trim()`) would improve discoverability and follow the fluent API pattern of other validators.
-
-### Explicit nullable() Method
-
-Although fields are optional (allow null) by default, adding an explicit `->nullable()` method (as an alias for default behavior) can improve code readability and intent, especially when contrasted with `->required()`.
+## 1. Feature Suggestions
 
 ### Instance Validation
 

README.md

@@ -46,7 +46,7 @@ Rather than reimplementing every possible transformation or validation rule, Lem
 - **API-friendly flattened errors** with field paths for easy frontend integration (`getFlattenedErrors()`, `ValidationException::flattenErrors()`)
 - **Intuitive custom validation** with `satisfies()` method and optional error messages
 - **Single-value validation** with `const()` for exact value matching (available on all validators)
-- **PHP BackedEnum validation** with `enum()` for type-safe enum case validation (available on all validators)
+- **PHP enum validation** with `enum()` for `BackedEnum` (backed values) and `UnitEnum` (case instances or string case names) (available on all validators)
 - **Logical combinators** (`Validator::allOf()`, `Validator::anyOf()`, `Validator::not()`) for complex validation logic
 - **Form-safe coercion** - empty strings become `null` (not dangerous `0`/`false`) for real-world safety
 - **Accurate schema validation** - results only include provided fields and fields with defaults (no unexpected properties)

ROADMAP.md

@@ -13,7 +13,7 @@ Focused on core validation primitives, consistent pipelines, and extensibility v
 
 ## Next Minor Release
 
-- [x] Universal allowed-value validators: `const()` (single allowed value), `enum()` (PHP BackedEnum)
+- [x] Universal allowed-value validators: `const()` (single allowed value), `enum()` (PHP `BackedEnum` and `UnitEnum`)
 - [x] Schema output key remapping: `outputKey(string $key)`
 - [ ] Structured error codes in validation errors (backward compatible)
 - [ ] Message placeholders for custom error messages (e.g., `{value}`, `{index}`) -- pair with error codes

docs/api-reference/validator-factory.md

@@ -762,9 +762,14 @@ $result = $schema->validate(['service_id' => '550e8400-e29b-41d4-a716-4466554400
 
 **Available on:** All validators (`FieldValidator` base)
 
-Validates that the value matches one of the backed values of a PHP BackedEnum. The value must be `int` or `string` (non-scalar values fail). Use `enum(StatusEnum::class)` instead of `in(array_map(fn($e) => $e->value, StatusEnum::cases()))`.
+Validates against a PHP `BackedEnum` or `UnitEnum`.
+
+**BackedEnum:** The value must be `int` or `string` and must match one of the enum’s backed values (`tryFrom()`). Non-scalar values fail. Use `enum(StatusEnum::class)` instead of `in(array_map(fn($e) => $e->value, StatusEnum::cases()))`.
+
+**UnitEnum** (non-backed): The value must be an instance of the enum, or a `string` equal to one of the case names (`$case->name`). Other types fail.
 
 ```php
+// BackedEnum
 enum StatusEnum: string { case Active = 'active'; case Pending = 'pending'; }
 
 $validator = Validator::isString()->enum(StatusEnum::class);
@@ -774,16 +779,25 @@ $validator->validate('active');   // Valid
 // With coercion (form input)
 $priority = Validator::isInt()->coerce()->enum(PriorityEnum::class);
 $priority->validate('2'); // Valid (coerced to 2)
+
+// UnitEnum (case name as string, or pass an enum instance from a mixed-typed validator)
+enum ColorEnum { case Red; case Green; case Blue; }
+
+$color = Validator::isString()->enum(ColorEnum::class);
+$color->validate('Red'); // Valid
+// $color->validate(ColorEnum::Blue); // invalid: isString() runs before enum()
 ```
 
+For an enum **case instance**, chain `enum()` on a validator whose type step accepts objects (for example a custom `FieldValidator` with a permissive `validateType`, or logical combinators that accept mixed input).
+
 **Parameters:**
 
-- `$enumClass`: Fully qualified BackedEnum class name (e.g. `StatusEnum::class`)
+- `$enumClass`: Fully qualified enum class name (`BackedEnum` or `UnitEnum`, e.g. `StatusEnum::class`)
 - `$message` (optional): Custom error message for invalid values
 
 **Returns:** Same validator instance for method chaining.
 
-**Throws:** `InvalidArgumentException` if `$enumClass` is not a BackedEnum.
+**Throws:** `InvalidArgumentException` if `$enumClass` is not a `BackedEnum` or `UnitEnum`.
 
 ---
 

docs/getting-started/basic-usage.md

@@ -210,6 +210,11 @@ $result = $exact->validate('pending'); // ❌ ValidationException
 $status = Validator::isString()->enum(StatusEnum::class);
 $result = $status->validate('active'); // Valid
 $result = $status->validate('unknown'); // ❌ ValidationException
+
+// PHP UnitEnum (non-backed): match by case name string, or use a mixed validator for enum instances
+$color = Validator::isString()->enum(ColorEnum::class);
+$result = $color->validate('Red'); // Valid (case name)
+$result = $color->validate('Magenta'); // ❌ ValidationException
 ```
 
 ## Schema Validation

docs/guides/custom-validation.md

@@ -2,7 +2,7 @@
 
 The Lemmon Validator allows you to add custom validation logic using the `satisfies()` method. This is perfect for business rules, complex validation logic, and context-aware validation that built-in validators can't handle.
 
-For simple allowed-value validation, consider built-in methods first: `const()` for a single allowed value (e.g. `->const('active')`), `enum()` for PHP BackedEnums (e.g. `->enum(StatusEnum::class)`), or `in()` for multiple values on string, int, float, and bool validators.
+For simple allowed-value validation, consider built-in methods first: `const()` for a single allowed value (e.g. `->const('active')`), `enum()` for PHP enums (e.g. `->enum(StatusEnum::class)` for a backed enum or `->enum(ColorEnum::class)` for a unit enum by case name or instance), or `in()` for multiple values on string, int, float, and bool validators.
 
 ## Basic Custom Validation
 

llms.txt

@@ -67,7 +67,7 @@ satisfiesAny(array<callable|FieldValidator> $rules, ?string $message = null): st
 satisfiesAll(array<callable|FieldValidator> $rules, ?string $message = null): static
 satisfiesNone(array<callable|FieldValidator> $rules, ?string $message = null): static
 const(mixed $value, ?string $message = null): static // Restrict to exactly one value (strict ===)
-enum(string $enumClass, ?string $message = null): static // Validate against PHP BackedEnum cases; $enumClass e.g. StatusEnum::class; value must be int|string
+enum(string $enumClass, ?string $message = null): static // BackedEnum: int|string backed values; UnitEnum: enum instance or string case name
 
 // Transformation
 transform(callable $fn, bool $skipNull = true): static (can change type, skips null by default)

src/Lemmon/Validator/FieldValidator.php

@@ -448,35 +448,66 @@ public function const(mixed $value, ?string $message = null): self
     }
 
     /**
-     * Restricts the value to a PHP BackedEnum case.
-     * Value must be int or string matching one of the enum's backed values.
+     * Restricts the value to a PHP enum case.
      *
-     * @param string $enumClass Fully qualified BackedEnum class name (e.g. StatusEnum::class).
+     * For BackedEnum, the value must be int or string matching one of the backed values.
+     * For UnitEnum (non-backed), the value must be an instance of the enum or a string
+     * equal to one of the case names.
+     *
+     * @param string $enumClass Fully qualified enum class name (e.g. StatusEnum::class).
      * @param ?string $message Optional custom error message.
      * @return $this
      */
     public function enum(string $enumClass, ?string $message = null): self
     {
-        if (!is_subclass_of($enumClass, \BackedEnum::class, true)) {
-            throw new \InvalidArgumentException(
-                sprintf('Class must be a BackedEnum, got: %s', $enumClass),
+        if (is_subclass_of($enumClass, \BackedEnum::class, true)) {
+            $allowed = implode(', ', array_map(
+                static fn(\BackedEnum $c) => var_export($c->value, true),
+                $enumClass::cases(),
+            ));
+
+            return $this->satisfies(
+                static function ($v) use ($enumClass): bool {
+                    if (!is_int($v) && !is_string($v)) {
+                        return false;
+                    }
+
+                    return $enumClass::tryFrom($v) !== null;
+                },
+                $message ?? 'Value must be one of: ' . $allowed,
             );
         }
 
-        $allowed = implode(', ', array_map(
-            static fn(\BackedEnum $c) => var_export($c->value, true),
-            $enumClass::cases(),
-        ));
+        if (is_subclass_of($enumClass, \UnitEnum::class, true)) {
+            $allowed = implode(', ', array_map(
+                static fn(\UnitEnum $c) => var_export($c->name, true),
+                $enumClass::cases(),
+            ));
+
+            return $this->satisfies(
+                static function ($v) use ($enumClass): bool {
+                    if ($v instanceof $enumClass) {
+                        return true;
+                    }
+
+                    if (!is_string($v)) {
+                        return false;
+                    }
+
+                    foreach ($enumClass::cases() as $case) {
+                        if ($case->name === $v) {
+                            return true;
+                        }
+                    }
 
-        return $this->satisfies(
-            static function ($v) use ($enumClass): bool {
-                if (!is_int($v) && !is_string($v)) {
                     return false;
-                }
+                },
+                $message ?? 'Value must be one of: ' . $allowed,
+            );
+        }
 
-                return $enumClass::tryFrom($v) !== null;
-            },
-            $message ?? 'Value must be one of: ' . $allowed,
+        throw new \InvalidArgumentException(
+            sprintf('Class must be a BackedEnum or UnitEnum, got: %s', $enumClass),
         );
     }