feat(validators): introduce in() method as an alias for oneOf()

Added a new `in()` method to StringValidator, IntValidator, FloatValidator, and BoolValidator for clearer allowed-value validation. The `oneOf()` method is now deprecated in favor of `in()`, which enhances the API's intuitiveness. Updated documentation and tests to reflect these changes, ensuring backward compatibility with the retained `oneOf()` alias.

Author: lemmon

CHANGELOG.md

@@ -7,6 +7,10 @@ All notable changes to this project will be documented in this file.
 ### Added
 - `notEmpty()` convenience method for `StringValidator` and `ArrayValidator` to reject empty strings/arrays
 - `between()` shorthand for string length and numeric range constraints
+- `in()` alias for `oneOf()` on primitive validators for clearer allowed-value validation
+
+### Deprecated
+- `oneOf()` in favor of `in()` (alias retained for backward compatibility)
 
 ### Documentation
 - Clarified fail-fast behavior per field and schema-level error aggregation in guides and examples

ROADMAP.md

@@ -308,7 +308,7 @@ $stringValidator = Validator::isString()
 
 ### Real-World Validation Gaps (For Consideration)
 - [x] **`notEmpty()` method** - Explicit validation that value is not empty string/array (clearer than custom validation)
-- [ ] **`in()` alias for `oneOf()`** - More intuitive method name (`->in(['active', 'inactive'])`)
+- [x] **`in()` alias for `oneOf()`** - More intuitive method name (`->in(['active', 'inactive'])`)
 - [x] **`between(min, max)` for strings** - Length validation shorthand (`->between(3, 50)` instead of `->minLength(3)->maxLength(50)`)
 - [x] **`between(min, max)` for numerics** - Range validation shorthand (`->between(1, 100)` instead of `->min(1)->max(100)`)
 - [ ] **`filled()` method** - Requires non-null AND non-empty (stricter than required())

TASKS.md

@@ -8,8 +8,8 @@ Public repo; keep this list short (about 7) and up to date. Rules: no numbering
 - 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.
 
-- `in()` alias for `oneOf()`
-  - Add `in()` method as an alias for `oneOf()` for more intuitive API (`->in(['active', 'inactive'])` reads better than `->oneOf()`).
+- `filled()` method
+  - Require non-null AND non-empty values; document how it interacts with `required()`, `nullifyEmpty()`, and `coerce()`.
 
 - Mutation testing pilot
   - Wire Infection (or similar) to the test suite, add baseline config, and document how to run it locally for enhanced test quality verification.

docs/api-reference/validator-factory.md

@@ -373,7 +373,7 @@ class UserSchemas
     private static function preferences(): AssociativeValidator
     {
         return Validator::isAssociative([
-            'theme' => Validator::isString()->oneOf(['light', 'dark'])->default('light'),
+            'theme' => Validator::isString()->in(['light', 'dark'])->default('light'),
             'notifications' => Validator::isBool()->default(true)
         ]);
     }
@@ -468,7 +468,7 @@ $result2 = $notEmail->validate(123); // Valid (not an email)
 
 // User status that cannot be banned or suspended
 $validStatus = Validator::not(
-    Validator::isString()->oneOf(['banned', 'suspended']),
+    Validator::isString()->in(['banned', 'suspended']),
     'User cannot have banned or suspended status'
 );
 
@@ -663,27 +663,29 @@ $result = $validator->validate(''); // Returns: 'N/A'
 
 ---
 
-### `oneOf(array $values, ?string $message = null): self`
+### `in(array $values, ?string $message = null): self`
 
 **Available on:** `StringValidator`, `IntValidator`, `FloatValidator`, `BoolValidator` only
 
 Restricts the value to one of the specified allowed values. This method is implemented as a transformation and respects the fluent API execution order.
 
+**Deprecated alias:** `oneOf()` (use `in()` instead)
+
 ```php
 // String with allowed values
 $status = Validator::isString()
-    ->oneOf(['active', 'inactive', 'pending'], 'Invalid status')
+    ->in(['active', 'inactive', 'pending'], 'Invalid status')
     ->validate('active'); // Valid
 
 // Integer with allowed values
 $priority = Validator::isInt()
-    ->oneOf([1, 2, 3, 4, 5], 'Priority must be 1-5')
+    ->in([1, 2, 3, 4, 5], 'Priority must be 1-5')
     ->validate(3); // Valid
 
 // Execution order matters
 $validator = Validator::isString()
     ->pipe('trim', 'strtolower')  // Transform first
-    ->oneOf(['yes', 'no'])        // Then validate allowed values
+    ->in(['yes', 'no'])        // Then validate allowed values
     ->validate('  YES  '); // Valid (becomes 'yes' after transformation)
 ```
 

docs/examples/form-validation.md

@@ -187,7 +187,7 @@ class ProductFormValidator
 
             'category' => Validator::isString()
                 ->required('Category is required')
-                ->oneOf(['electronics', 'clothing', 'books', 'home'], 'Invalid category'),
+                ->in(['electronics', 'clothing', 'books', 'home'], 'Invalid category'),
 
             // Optional fields with form-safe handling
             'description' => Validator::isString()
@@ -336,7 +336,7 @@ class UserRegistrationValidator
                 ),
 
             'gender' => Validator::isString()
-                ->oneOf(['male', 'female', 'other', 'prefer_not_to_say'], 'Please select a valid gender option')
+                ->in(['male', 'female', 'other', 'prefer_not_to_say'], 'Please select a valid gender option')
                 ->default('prefer_not_to_say'),
 
             // Address (optional)
@@ -591,7 +591,7 @@ class ProductFormValidator
 
             // Status and Visibility
             'status' => Validator::isString()
-                ->oneOf(['draft', 'active', 'archived'], 'Invalid product status')
+                ->in(['draft', 'active', 'archived'], 'Invalid product status')
                 ->default('draft'),
 
             'published_at' => Validator::isString()
@@ -878,7 +878,7 @@ class FileUploadValidator
 
             'type' => Validator::isString()
                 ->required()
-                ->oneOf(['image/jpeg', 'image/png', 'image/gif'], 'Invalid file type')
+                ->in(['image/jpeg', 'image/png', 'image/gif'], 'Invalid file type')
         ]);
 
         return $validator->tryValidate($file);

docs/getting-started/basic-usage.md

@@ -194,7 +194,7 @@ $formValidator = Validator::isAssociative([
 ### Allowed Values
 
 ```php
-$restricted = Validator::isString()->oneOf(['red', 'green', 'blue']);
+$restricted = Validator::isString()->in(['red', 'green', 'blue']);
 
 $result = $restricted->validate('red'); // Valid
 $result = $restricted->validate('yellow'); // ❌ ValidationException

docs/getting-started/core-concepts.md

@@ -45,7 +45,7 @@ All validators extend `FieldValidator`, which provides:
 - `required(): static` - Makes the field mandatory
 - `default(mixed $value): static` - Sets default value for null inputs
 - `coerce(): static` - Enables automatic type conversion
-- `oneOf(array $values): static` - Restricts to specific values (primitive validators only)
+- `in(array $values): static` - Restricts to specific values (primitive validators only)
 
 ### Custom Validation
 - `satisfies(callable|FieldValidator $rule, ?string $message = null): static` - Enhanced custom validation accepting validators or callables
@@ -436,7 +436,7 @@ $schema = Validator::isAssociative([
         'name' => Validator::isString()->required(),
         'contacts' => Validator::isArray()->items(
             Validator::isAssociative([
-                'type' => Validator::isString()->oneOf(['email', 'phone']),
+                'type' => Validator::isString()->in(['email', 'phone']),
                 'value' => Validator::isString()->required()
             ])
         )

docs/guides/array-validation.md

@@ -331,7 +331,7 @@ $validator = Validator::isArray()->satisfies(
 $result = $validator->validate([1, 2]); // Valid
 $validator->validate([1, 2, 3]); // Throws ValidationException
 
-// Note: oneOf() is not available on ArrayValidator as it doesn't make semantic sense for complex types
+// Note: in() is not available on ArrayValidator as it doesn't make semantic sense for complex types
 ```
 
 ### Empty Array Handling
@@ -582,7 +582,7 @@ $fileValidator = Validator::isArray()->items(
     Validator::isAssociative([
         'name' => Validator::isString()->required(),
         'size' => Validator::isInt()->min(1)->max(10485760), // Max 10MB
-        'type' => Validator::isString()->oneOf([
+        'type' => Validator::isString()->in([
             'image/jpeg', 'image/png', 'image/gif'
         ])
     ])

docs/guides/custom-validation.md

@@ -106,7 +106,7 @@ $conditionalValidator = Validator::isString()->satisfies(
 $accountSchema = Validator::isAssociative([
     'account_type' => Validator::isString()
         ->required()
-        ->oneOf(['personal', 'business']),
+        ->in(['personal', 'business']),
     'company_name' => $conditionalValidator
 ]);
 ```
@@ -215,7 +215,7 @@ $discountValidator = Validator::isFloat()->satisfies(
 );
 
 $orderSchema = Validator::isAssociative([
-    'customer_tier' => Validator::isString()->oneOf(['bronze', 'silver', 'gold', 'platinum']),
+    'customer_tier' => Validator::isString()->in(['bronze', 'silver', 'gold', 'platinum']),
     'order_total' => Validator::isFloat()->positive()->required(),
     'discount_amount' => $discountValidator
 ]);

docs/guides/error-handling.md

@@ -416,7 +416,7 @@ class ApiValidator
         $schema = Validator::isAssociative([
             'status' => Validator::isString()
                 ->required('Status is required')
-                ->oneOf(['success', 'error'], 'Status must be success or error'),
+                ->in(['success', 'error'], 'Status must be success or error'),
 
             'data' => Validator::isAssociative()
                 ->required('Data is required'),
@@ -460,7 +460,7 @@ class ConfigValidator
             ])->required('Database configuration is required'),
 
             'cache' => Validator::isAssociative([
-                'driver' => Validator::isString()->oneOf(['redis', 'memcached', 'file'])->default('file'),
+                'driver' => Validator::isString()->in(['redis', 'memcached', 'file'])->default('file'),
                 'ttl' => Validator::isInt()->positive()->default(3600)
             ])->default([]),