Valitron Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require vlucas/valitron
   

   No dependencies, no configuration—just include the autoloader.

2. First Use Case: Validate a simple form submission (e.g., $_POST data):

   use Valitron\Validator;
   
   $v = new Validator($_POST);
   $v->rule('required', ['name', 'email']);
   $v->rule('email', 'email');
   
   if ($v->validate()) {
       // Process valid data
   } else {
       // Handle errors: $v->errors()
   }
   

3. Where to Look First:

   • Built-in Rules (e.g., required, email, date).
   • Dot Notation for nested arrays (e.g., user.address.city).
   • Error Handling ($v->errors() returns a structured array).

Implementation Patterns

1. Form Validation Workflow

• Request Handling: Use middleware or a service to validate incoming requests early (e.g., API payloads, form submissions).

  // In a Laravel controller
  public function store(Request $request) {
      $v = new Validator($request->all());
      $v->rules([
          'title'   => 'required|lengthBetween:5,100',
          'content' => 'required',
          'published_at' => 'date|dateAfter:today'
      ]);
      if (!$v->validate()) {
          return response()->json(['errors' => $v->errors()], 422);
      }
      // Proceed with logic
  }
  

• Reusable Validation Logic: Create a ValidatorService to encapsulate common rules:

  class UserValidator {
      public function validate(array $data): bool {
          $v = new Validator($data);
          $v->rules([
              'email'    => 'required|email|emailDNS',
              'password' => 'required|lengthMin:8',
              'role'     => 'in:admin,user,guest'
          ]);
          return $v->validate();
      }
  }
  

2. Conditional Rules

• Dynamic Validation: Use requiredWith, requiredWithout, or custom callbacks for conditional logic:

  $v->rules([
      'requiredWith'   => [['password', 'email']], // Password required if email exists
      'requiredWithout' => [['token', 'email']],   // Token required if no email
      'equals'         => [['password', 'confirm_password']]
  ]);
  

• Custom Callbacks: Extend Valitron with custom rules (e.g., for Laravel-specific logic):

  Validator::extend('activeUser', function($field, $value, array $params) {
      return User::where('email', $value)->where('active', true)->exists();
  });
  $v->rule('activeUser', 'email');
  

3. Nested Data Validation

• Arrays and Objects: Validate nested structures using dot notation:

  $data = ['user' => ['name' => 'John', 'address' => ['city' => 'NY']]];
  $v->rules([
      'required' => ['user.name', 'user.address.city'],
      'alpha'    => ['user.name'],
      'lengthMax' => ['user.address.city', 50]
  ]);
  

• Array Iteration: Validate all items in an array (e.g., tags, items):

  $data = ['tags' => ['laravel', 'php', 'validation']];
  $v->rule('lengthMax', 'tags.*', 20); // All tags must be ≤20 chars
  

4. Error Handling

• Structured Errors: Access errors by field or globally:

  $errors = $v->errors();
  // Example output:
  // [
  //     'email' => ['The email field is required.'],
  //     'password' => ['The password must be at least 8 characters.']
  // ]
  

• Custom Error Messages: Override default messages:

  $v->rule('required', 'email')->message('Please provide a valid email address.');
  

5. Integration with Laravel

• Form Requests: Combine with Laravel’s FormRequest for seamless validation:

  use Valitron\Validator;
  
  class StoreUserRequest extends FormRequest {
      public function validate() {
          $validator = new Validator($this->all());
          $validator->rules([
              'name' => 'required|alphaNum|lengthMax:50',
              'email' => 'required|email|unique:users'
          ]);
          if (!$validator->validate()) {
              throw new \Exception('Validation failed');
          }
          return true;
      }
  }
  

• API Responses: Format errors for API consumers:

  return response()->json([
      'success' => false,
      'errors'  => collect($v->errors())->flatten()->toArray()
  ], 422);
  

Gotchas and Tips

Pitfalls

1. Case Sensitivity in Dot Notation:

   • user.Name ≠ user.name. Valitron uses strict key matching.
   • Fix: Normalize keys (e.g., array_change_key_case($data, CASE_LOWER)).

2. Floating-Point Precision:

   • min/max rules may fail with floats due to PHP’s precision limits.
   • Fix: Use BCMath extension or round values:

     $v->rule('min', 'price', 0.00, true); // Third param enables BCMath
     

3. Empty Arrays vs. Missing Keys:

   • required skips missing keys but fails for empty arrays ([]).
   • Fix: Use optional or custom logic:

     $v->rule('optional', 'tags'); // Allows empty array
     

4. Strict Conditional Rules:

   • requiredWith/requiredWithout with true (strict) behave differently:
     • Non-strict: ANY of the fields must be present.
     • Strict: ALL of the fields must be present.
   • Example:

     // Non-strict: 'password' required if EITHER 'email' OR 'username' exists.
     $v->rule('requiredWith', 'password', ['email', 'username']);
     // Strict: 'password' required ONLY if BOTH 'email' AND 'username' exist.
     $v->rule('requiredWith', 'password', ['email', 'username'], true);
     

5. Custom Rules and Dependencies:

   • Custom rules cannot rely on Laravel’s Request or Validator classes (no dependencies).
   • Workaround: Pass dependencies via $params:

     Validator::extend('uniqueUser', function($field, $value, $params) {
         return User::where($field, $value)->where('id', '!=', $params[0])->doesntExist();
     });
     $v->rule('uniqueUser', 'email', [$user->id]);
     

Debugging Tips

1. Validate Without Throwing Errors:

   • Use $v->validate(true) to return false instead of throwing exceptions (useful for testing).

2. Inspect Rules:

   • Dump the validator’s rules for debugging:

     dd($v->getRules());
     

3. Test Edge Cases:

   • Validate with null, empty strings, and edge values (e.g., 0, false, []):

     $v = new Validator(['age' => null]);
     $v->rule('integer', 'age');
     

Performance Tips

1. Reuse Validators:

   • Instantiate validators once (e.g., in a service) and reuse them for multiple requests (if data is immutable).

2. Avoid Over-Validation:

   • Only validate fields you need. Use optional for non-critical fields:

     $v->rule('optional|email', 'secondary_email');
     

3. Cache Rules:

   • For complex validation logic, pre-define rules in a config file:

     // config/validation.php
     return [
         'user' => [
           'name' => 'required|alphaNum',
           'email' => 'required|email|emailDNS',
         ],
     ];
     

Extension Points

1. Custom Rules:
   • Extend Valitron with reusable rules:

     Validator::extend('strongPassword', function($field, $value) {
         return preg_match('/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).