feat: Unify validator API and refine error reporting

This commit introduces several improvements to the validator library:

- **Unified API for FieldValidator**: The  now includes a  method, aligning its API with . The  method now calls  and throws an exception on failure, ensuring consistent behavior across all validators.

- **Refined Error Reporting**: Removed redundant field names from error messages. Error messages are now generic (e.g., "Value is required."), with the field context provided by the error object's key. This results in a cleaner, more structured, and easier-to-parse error output.

These changes enhance the library's consistency, predictability, and overall developer experience.

Author: lemmon

src/Lemmon/ArrayValidator.php

@@ -57,12 +57,12 @@ protected function coerceValue(mixed $value): mixed
     protected function validateType(mixed $value, string $key): mixed
     {
         if (!is_array($value)) {
-            throw new ValidationException([$key ? "Field '$key' must be an array." : 'Value must be an array.']);
+            throw new ValidationException(['Value must be an array.']);
         }
 
         // Check if it's a list (indexed array starting from 0)
         if (!array_is_list($value)) {
-            throw new ValidationException([$key ? "Field '$key' must be an indexed array (list)." : 'Value must be an indexed array (list).']);
+            throw new ValidationException(['Value must be an indexed array (list).']);
         }
 
         // If item validator is set, validate each item

src/Lemmon/BoolValidator.php

@@ -24,7 +24,7 @@ protected function coerceValue(mixed $value): mixed
     protected function validateType(mixed $value, string $key): mixed
     {
         if (!is_bool($value)) {
-            throw new ValidationException([$key ? "Field '$key' must be a boolean." : 'Value must be a boolean.']);
+            throw new ValidationException(['Value must be a boolean.']);
         }
         return $value;
     }

src/Lemmon/FieldValidator.php

@@ -70,24 +70,49 @@ public function oneOf(array $values): self
      * @throws ValidationException If validation fails.
      */
     public function validate(mixed $value, string $key = '', array $input = []): mixed
+    {
+        [$valid, $data, $errors] = $this->tryValidate($value, $key, $input);
+        if (!$valid) {
+            throw new ValidationException($errors);
+        }
+        return $data;
+    }
+
+    /**
+     * Tries to validate the given value and returns a result tuple.
+     *
+     * @param mixed $value The value to validate.
+     * @param string $key The key of the field being validated.
+     * @param array<string, mixed> $input The entire input array.
+     * @return array{bool, mixed, array<string>|null} A tuple containing:
+     *                                                 - bool: true if validation is successful, false otherwise.
+     *                                                 - mixed: The validated and potentially coerced value, or the original value on failure.
+     *                                                 - array|null: An array of error messages on failure, or null on success.
+     */
+    public function tryValidate(mixed $value, string $key = '', array $input = []): array
     {
         if (is_null($value)) {
             if ($this->hasDefault) {
-                return $this->default;
+                return [true, $this->default, null];
             }
             if ($this->required) {
-                throw new ValidationException([$key ? "Field '$key' is required." : 'Value is required.']);
+                return [false, $value, ['Value is required.']];
             }
-            return null;
+            return [true, null, null];
         }
 
         $value = $this->coerce ? $this->coerceValue($value) : $value;
 
         if ($this->oneOf && !in_array($value, $this->oneOf, true)) {
-            throw new ValidationException([$key ? "Field '$key' must be one of: " . json_encode($this->oneOf) : 'Value must be one of: ' . json_encode($this->oneOf)]);
+            return [false, $value, ['Value must be one of: ' . json_encode($this->oneOf)]];
         }
 
-        return $this->validateType($value, $key);
+        try {
+            $validatedValue = $this->validateType($value, $key);
+            return [true, $validatedValue, null];
+        } catch (ValidationException $e) {
+            return [false, $value, $e->getErrors()];
+        }
     }
 
     /**
@@ -107,4 +132,4 @@ abstract protected function coerceValue(mixed $value): mixed;
      * @throws ValidationException If the type validation fails.
      */
     abstract protected function validateType(mixed $value, string $key): mixed;
-}
+}

src/Lemmon/IntValidator.php

@@ -18,7 +18,7 @@ protected function coerceValue(mixed $value): mixed
     protected function validateType(mixed $value, string $key): mixed
     {
         if (!is_int($value)) {
-            throw new ValidationException([$key ? "Field '$key' must be an integer." : 'Value must be an integer.']);
+            throw new ValidationException(['Value must be an integer.']);
         }
         return $value;
     }

src/Lemmon/StringValidator.php

@@ -18,7 +18,7 @@ protected function coerceValue(mixed $value): mixed
     protected function validateType(mixed $value, string $key): mixed
     {
         if (!is_string($value)) {
-            throw new ValidationException([$key ? "Field '$key' must be a string." : 'Value must be a string.']);
+            throw new ValidationException(['Value must be a string.']);
         }
         return $value;
     }