feat(FieldValidator): add enum() for BackedEnum validation

- Add enum(string $enumClass, ?string $message = null) to FieldValidator
- Validate value against PHP BackedEnum cases via tryFrom (int or string)
- Throw InvalidArgumentException for non-BackedEnum class
- Add test fixtures StatusEnum, PriorityEnum; 8 tests
- Update ROADMAP, CHANGELOG, README, AGENTS.md, llms.txt, docs

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
--   **Logical combinators:** `Validator::allOf`, `anyOf`, `not`; instance `satisfiesAny`, `satisfiesAll`, `satisfiesNone`; `const()` for single allowed value
+-   **Logical combinators:** `Validator::allOf`, `anyOf`, `not`; instance `satisfiesAny`, `satisfiesAll`, `satisfiesNone`; `const()` for single allowed value; `enum()` for BackedEnum
 -   **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

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+-   `enum(class-string<\BackedEnum> $enumClass, ?string $message = null)` on `FieldValidator` for PHP BackedEnum validation; restricts the value to one of the enum's backed cases (int or string); available on all validator types; use `enum(StatusEnum::class)` instead of `in(array_map(fn($e) => $e->value, StatusEnum::cases()))`
 -   `const(mixed $value, ?string $message = null)` on `FieldValidator` for single-value validation; restricts the value to exactly one allowed constant using strict comparison (`===`); available on all validator types; use `const('active')` instead of `in(['active'])` for clearer intent
 -   `outputKey(string $key)` on `FieldValidator` for schema fields: output validated values under a different key than the input field (e.g. input `service_id` -> output `service` after transform); works with `Validator::isAssociative()` and `Validator::isObject()`
 -   GitHub Actions CI: lint, platform-check, static analysis, tests on PHP 8.3

README.md

@@ -45,6 +45,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)
 -   **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,8 +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) validation
+-   [x] Universal allowed-value validators: `const()` (single allowed value), `enum()` (PHP BackedEnum)
 -   [x] Schema output key remapping: `outputKey(string $key)`
 -   [ ] Structured error codes in validation errors (backward compatible)
 -   [ ] ArrayValidator `uniqueField(string $fieldName, ?string $message = null)`

TASKS.md

@@ -2,10 +2,6 @@
 
 Public repo; keep this list short (about 7) and up to date. Rules: no numbering (keeps churn low), prune completed items, and replace them with the next priority. Contributors: pick one task, keep PRs focused, and update the list as things land.
 
--   Universal enum/const validators
-
-    -   Add `enum()` method available on all validator types; handle mixed scalar inputs and document usage patterns. (`const()` done)
-
 -   Structured error codes
 
     -   Add programmatic error codes to validation errors (e.g., 'STRING_TOO_SHORT', 'INVALID_EMAIL') for better error handling and i18n support; keep backward compatibility.

docs/api-reference/validator-factory.md

@@ -695,6 +695,35 @@ $result = $schema->validate(['service_id' => '550e8400-e29b-41d4-a716-4466554400
 
 ---
 
+### `enum(string $enumClass, ?string $message = null): self`
+
+**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()))`.
+
+```php
+enum StatusEnum: string { case Active = 'active'; case Pending = 'pending'; }
+
+$validator = Validator::isString()->enum(StatusEnum::class);
+$validator->validate('active');   // Valid
+// $validator->validate('unknown'); // ❌ ValidationException
+
+// With coercion (form input)
+$priority = Validator::isInt()->coerce()->enum(PriorityEnum::class);
+$priority->validate('2'); // Valid (coerced to 2)
+```
+
+**Parameters:**
+
+-   `$enumClass`: Fully qualified BackedEnum class name (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.
+
+---
+
 ### `const(mixed $value, ?string $message = null): self`
 
 **Available on:** All validators (`FieldValidator` base)

docs/getting-started/basic-usage.md

@@ -205,6 +205,11 @@ $result = $restricted->validate('yellow'); // ❌ ValidationException
 $exact = Validator::isString()->const('active');
 $result = $exact->validate('active'); // Valid
 $result = $exact->validate('pending'); // ❌ ValidationException
+
+// PHP BackedEnum validation (StatusEnum: string with cases Active='active', Pending='pending')
+$status = Validator::isString()->enum(StatusEnum::class);
+$result = $status->validate('active'); // Valid
+$result = $status->validate('unknown'); // ❌ 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')`), 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 BackedEnums (e.g. `->enum(StatusEnum::class)`), or `in()` for multiple values on string, int, float, and bool validators.
 
 ## Basic Custom Validation
 

llms.txt

@@ -60,6 +60,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
 
 // Transformation
 transform(callable $fn, bool $skipNull = true): static (can change type, skips null by default)

src/Lemmon/Validator/FieldValidator.php

@@ -264,6 +264,39 @@ 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.
+     *
+     * @param string $enumClass Fully qualified BackedEnum 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),
+            );
+        }
+
+        $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,
+        );
+    }
+
     /**
      * Adds a transformation function to be applied after successful validation.
      * Can change the type - subsequent operations work with the new type.