fix(validator): normalize malformed UTF-8 param keys during JSON serialization

- Apply utf8Safe() to param keys in ValidationError::jsonSerialize()
- Document key normalization in CHANGELOG, error-handling guide, and llms.txt
- Add test for invalid UTF-8 in a satisfies() param key

Author: lemmon

CHANGELOG.md

@@ -6,7 +6,7 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
-- Structured error model. Validation errors are now a flat list of new `ValidationError` value objects, each with `getPath()` (dotted, `''` at root), `getCode()` (a stable code from the new `ValidationCode` catalog, e.g. `STRING_TOO_SHORT`, `INVALID_TYPE`, `REQUIRED`), `getMessage()`, and `getParams()` (e.g. `['min' => 5]`). `ValidationError` is `JsonSerializable` (`{path, code, message, params}`), so `json_encode($e->getErrors())` is API-ready — a param value that cannot be encoded (a resource, `NAN`/`INF`, or an object whose `jsonSerialize()` throws) renders as `(complex value)` rather than failing serialization. All built-in validators now emit codes and params; messages support `{name}` placeholder substitution from params
+- Structured error model. Validation errors are now a flat list of new `ValidationError` value objects, each with `getPath()` (dotted, `''` at root), `getCode()` (a stable code from the new `ValidationCode` catalog, e.g. `STRING_TOO_SHORT`, `INVALID_TYPE`, `REQUIRED`), `getMessage()`, and `getParams()` (e.g. `['min' => 5]`). `ValidationError` is `JsonSerializable` (`{path, code, message, params}`), so `json_encode($e->getErrors())` is API-ready — malformed UTF-8 param keys are normalized, and a param value that cannot be encoded (a resource, `NAN`/`INF`, or an object whose `jsonSerialize()` throws) renders as `(complex value)` rather than failing serialization. All built-in validators now emit codes and params; messages support `{name}` placeholder substitution from params
 - `ValidationException::getErrors(?string $path = null)` filters to a single field: with no argument it returns every error; with a path it returns errors at that path and everything nested beneath it (`getErrors('')` returns only root-level errors; the segment-aware match means `getErrors('name')` won't catch `name_full`)
 - `satisfies()` accepts two optional trailing arguments: `?string $code` (defaults to `CUSTOM`) and `array $params` for structured error codes and message placeholders on custom rules
 - `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()`)

docs/guides/error-handling.md

@@ -280,9 +280,9 @@ JSON output example:
 The same works from a `tryValidate()` tuple — its third element is the same `ValidationError[]`, so
 `json_encode($errors)` produces identical output.
 
-Serialization is safe by construction: if a param value cannot be JSON-encoded (a resource,
-`NAN`/`INF`, or an object whose `jsonSerialize()` throws), it renders as `"(complex value)"` rather
-than making the response fail.
+Serialization is safe by construction: malformed UTF-8 param keys are normalized, and if a param
+value cannot be JSON-encoded (a resource, `NAN`/`INF`, or an object whose `jsonSerialize()` throws),
+it renders as `"(complex value)"` rather than making the response fail.
 
 ## Fail-Fast Per Field
 

llms.txt

@@ -25,7 +25,7 @@
   - `validate(mixed $value, string $key = '', mixed $input = null)` throws `ValidationException`.
   - `tryValidate(mixed $value, string $key = '', mixed $input = null)` returns tuple `[bool $valid, mixed $data, ?array $errors]`, where `$errors` is a flat list of `ValidationError` objects (or `null` on success).
 - **Fail-Fast:** Each validator chain stops at the first failing rule; schema validators aggregate errors across fields.
-- **Error Structure:** Validation errors are a flat list of `ValidationError` value objects, each with `getPath()` (dotted, `''` at root), `getCode()` (stable code, see `ValidationCode`), `getMessage()`, and `getParams()`. Access via `ValidationException::getErrors(?string $path = null)` or the `tryValidate` tuple. `getErrors()` (no arg) returns every error; `getErrors($path)` filters to a field and everything nested beneath it (`getErrors('')` returns only root-level errors; the trailing-dot match means `getErrors('name')` won't catch `name_full`). Match on codes, not message text. `satisfies()` accepts optional `(?string $code, array $params)`; params double as `{name}` message placeholders. `ValidationError` is `JsonSerializable` (`{path, code, message, params}`), so `json_encode($e->getErrors())` is API-ready.
+- **Error Structure:** Validation errors are a flat list of `ValidationError` value objects, each with `getPath()` (dotted, `''` at root), `getCode()` (stable code, see `ValidationCode`), `getMessage()`, and `getParams()`. Access via `ValidationException::getErrors(?string $path = null)` or the `tryValidate` tuple. `getErrors()` (no arg) returns every error; `getErrors($path)` filters to a field and everything nested beneath it (`getErrors('')` returns only root-level errors; the trailing-dot match means `getErrors('name')` won't catch `name_full`). Match on codes, not message text. `satisfies()` accepts optional `(?string $code, array $params)`; params double as `{name}` message placeholders. `ValidationError` is `JsonSerializable` (`{path, code, message, params}`), so `json_encode($e->getErrors())` is API-ready; malformed UTF-8 param keys are normalized during serialization, and unencodable param values render as `"(complex value)"`.
 - **Null Handling:** Validators skip `null` values unless `required()` is called. `default()` fills in null as a last-resort fallback after the pipeline; `required()` enforces presence at the very end.
 - **Pipeline:** Supports both validation (`satisfies`) and transformation (`transform`, `pipe`). Flow: coerce -> type check -> pipeline -> default -> required.
 - **Coercion:** `coerce()` enables smart type conversion (e.g., "true" -> `true`). Non-coercible values pass through unchanged.

src/Lemmon/Validator/ValidationError.php

@@ -99,9 +99,11 @@ public static function interpolate(string $template, array $params): string
 
     /**
      * Serializes to the public error shape. The string fields are already valid UTF-8 (normalised
-     * in the constructor) and each param value is passed through {@see jsonSafe()}, so json_encode()
-     * on a ValidationError -- the advertised API payload -- can never throw or return false, whatever
-     * value a rule put in the error.
+     * in the constructor); each param value is passed through {@see jsonSafe()} and each param key
+     * through {@see utf8Safe()} (a custom satisfies() call can supply a key with malformed UTF-8,
+     * which the surrounding object cast would otherwise carry through and make json_encode() fail).
+     * So json_encode() on a ValidationError -- the advertised API payload -- can never throw or
+     * return false, whatever key or value a rule put in the error.
      *
      * Params are an object (cast from the string-keyed array) so the JSON shape stays
      * predictable -- an empty params map is `{}`, never `[]`.
@@ -110,11 +112,16 @@ public static function interpolate(string $template, array $params): string
      */
     public function jsonSerialize(): array
     {
+        $params = [];
+        foreach ($this->params as $name => $value) {
+            $params[self::utf8Safe((string) $name)] = self::jsonSafe($value);
+        }
+
         return [
             'path' => $this->path,
             'code' => $this->code,
             'message' => $this->message,
-            'params' => (object) array_map(self::jsonSafe(...), $this->params),
+            'params' => (object) $params,
         ];
     }
 

tests/StructuredErrorsTest.php

@@ -361,6 +361,13 @@ public function jsonSerialize(): mixed
                 ->tryValidate('whatever')[2] ?? []
         ),
     ],
+    'invalid UTF-8 in a satisfies() param key' => [
+        fn() => (
+            Validator::isString()
+                ->satisfies(static fn() => false, 'nope', 'X', ["bad \xC3\x28 key" => 5])
+                ->tryValidate('whatever')[2] ?? []
+        ),
+    ],
     'invalid UTF-8 in a custom message' => [
         fn() => (
             Validator::isString()