Extra Validator Bundle Laravel Package

Getting Started

Minimal Steps for Laravel Integration

1. Skip Bundle Installation Since this is a Symfony bundle, install only the core validation logic via Composer:

   composer require devilcius/extra-validator-bundle --dev
   

   Note: Extract the validator classes (CccValidator, DniValidator) manually from the bundle’s src/Validator directory.

2. First Use Case: Laravel Form Request Create a custom validation rule for DNI/CCC in a FormRequest:

   use Illuminate\Validation\Rule;
   
   class StoreUserRequest extends FormRequest {
       public function rules() {
           return [
               'dni' => ['required', 'string', new DniRule], // Custom rule
               'ccc' => ['required', 'string', new CccRule], // Custom rule
           ];
       }
   }
   

3. Quick Test Register custom rules in AppServiceProvider@boot():

   Validator::extend('dni', function ($attribute, $value, $parameters, $validator) {
       return preg_match('/^[0-9]{8}[A-Za-z]$/', $value) && // Basic DNI format
              (strtoupper(substr($value, -1)) === self::calculateDniLetter($value));
   });
   
   Validator::extend('ccc', function ($attribute, $value, $parameters, $validator) {
       return preg_match('/^\d{20}$/', $value) && // Basic CCC format
              (self::validateCccChecksum($value));
   });
   

   Test with:

   $validator = Validator::make(['dni' => '12345678A'], ['dni' => 'required|dni']);
   if ($validator->fails()) { dd($validator->errors()); }
   

Implementation Patterns

Laravel-Specific Workflows

1. Custom Rule Objects (Recommended) Create reusable rule classes in app/Rules:

   namespace App\Rules;
   
   use Illuminate\Contracts\Validation\Rule;
   
   class DniRule implements Rule {
       public function passes($attribute, $value) {
           return preg_match('/^[0-9]{8}[A-Za-z]$/', $value) &&
                  (strtoupper(substr($value, -1)) === $this->calculateLetter($value));
       }
   
       public function message() {
           return 'El formato de DNI no es válido.';
       }
   
       private function calculateLetter($dni) { /* ... */ }
   }
   

   Use in requests:

   'dni' => ['required', new DniRule],
   

2. API Validation with JSON:API Validate nested payloads (e.g., data.attributes.dni):

   $validator = Validator::make($request->json()->all(), [
       'data.attributes.dni' => ['required', 'dni'],
   ]);
   

3. Dynamic Validation in Controllers Validate CCC during bank account creation:

   $validator = Validator::make($request->all(), [
       'account.ccc' => ['required', 'ccc'],
   ]);
   if ($validator->fails()) {
       return response()->json(['error' => $validator->errors()], 422);
   }
   

4. Localization Override error messages in resources/lang/es/validation.php:

   return [
       'dni' => [
           'required' => 'El DNI es obligatorio.',
           'dni'      => 'El DNI introducido no es válido.',
       ],
       'ccc' => [
           'required' => 'El CCC es obligatorio.',
           'ccc'      => 'El número de cuenta no es válido.',
       ],
   ];
   

Integration Tips

• Laravel 8+: Use Validator::extend() for dynamic rules or Rule objects for OOP.
• Testing: Mock the calculateLetter()/validateChecksum() methods in PHPUnit:

  $rule = new DniRule();
  $this->assertFalse($rule->passes('dni', '12345678X')); // Invalid letter
  

• Performance: Cache validation results if validating the same CCC/DNI repeatedly (e.g., in bulk imports).

Gotchas and Tips

Pitfalls

1. Symfony vs. Laravel API Mismatch

   • Issue: The bundle uses Symfony’s Constraint system, which doesn’t map 1:1 to Laravel.
   • Fix: Reimplement logic as Laravel Rule objects or Validator::extend() callbacks.
   • Example: The bundle’s Dni constraint may include Symfony-specific options (e.g., message in XML). Laravel uses message() in Rule classes or language files.

2. Undocumented Edge Cases

   • CCC Validation: The bundle may not handle all Spanish bank formats (e.g., old 14-digit CCCs vs. new 20-digit IBAN-based codes).
   • DNI/NIE: The validator might not account for foreign NIFs (e.g., X12345678Z for non-Spanish residents).
   • Fix: Test against real-world samples from Agencia Tributaria or Banco de España.

3. Error Message Localization

   • Issue: Default messages are in Spanish. Non-Spanish users may see gibberish.
   • Fix: Override messages in Laravel’s language files (see Implementation Patterns).

4. Bundle Abandonment Risk

   • Issue: 0 stars/dependents suggest low maintenance.
   • Fix:
     • Fork the repo and maintain it internally.
     • Extract the validation logic into a standalone Laravel package (e.g., laravel-spanish-validators).

5. Regex Overload

   • Issue: The bundle’s regex may be too strict/lenient for your use case.
   • Fix: Inspect the source (e.g., DniValidator::validate()) and adjust:

     // Example: Allow NIE formats (e.g., 'X1234567A')
     public function passes($attribute, $value) {
         return preg_match('/^[0-9]{8}[A-Za-z]$|^[XYZ]\d{7}[A-Za-z]$/', $value) &&
                $this->checkLetter($value);
     }
     

Debugging Tips

1. Validate Manually Test the regex logic in Tinker:

   php artisan tinker
   >>> preg_match('/^[0-9]{8}[A-Za-z]$/', '12345678A') // Should return 1
   

2. Log Validation Failures Add debug logs in custom rules:

   public function passes($attribute, $value) {
       $isValidFormat = preg_match('/.../', $value);
       $isValidLetter = $this->calculateLetter($value);
       \Log::debug("DNI $value - Format: $isValidFormat, Letter: $isValidLetter");
       return $isValidFormat && $isValidLetter;
   }
   

3. Checksum Calculation For CCC validation, verify the checksum algorithm matches Spanish bank standards:

   private function validateCccChecksum($ccc) {
       $digits = str_split($ccc);
       $weight = 1;
       $sum = 0;
       foreach (array_reverse($digits) as $digit) {
           $sum += $digit * $weight++;
           if ($weight > 10) $weight = 1;
       }
       return ($sum % 11) === 0;
   }
   

Extension Points

1. Add New Validators Extend the bundle’s logic for other Spanish identifiers (e.g., NIE for foreigners, CIF for companies):

   Validator::extend('nie', function ($attribute, $value) {
       return preg_match('/^[XYZ]\d{7}[A-Za-z]$/', $value) &&
              (strtoupper(substr($value, -1)) === $this->calculateNieLetter($value));
   });
   

2. Custom Constraints Create a CifRule for corporate tax IDs:

   namespace App\Rules;
   
   class CifRule implements Rule {
       public function passes($attribute, $value) {
           // Validate CIF format (e.g., 'A12345678', 'B98765432')
           return preg_match('/^[A-J]\d{7}[A-Z0-9]$|^[1-9]\d{7}[A-Z0-9]$/', $value);
       }
   }
   

3. Integration with Laravel Nova Add validation to Nova resources:

   use Laravel\Nova\Rules\Rule;
   
   class DniRule extends Rule {
       public function passes($attribute, $value) {
           // Reuse existing logic