Check Partita Iva Laravel Package

Getting Started

Minimal Steps

1. Installation Add the package via Composer:

   composer require sorciulus/check-partita-iva
   

   Require the autoloader in your project (Laravel handles this automatically via composer.json).

2. First Use Case Validate an Italian VAT number (Partita IVA) in a Laravel controller or form request:

   use Sorciulus\CheckPartitaIva\PartitaIva;
   
   $vatNumber = '12345678901'; // Example VAT number
   $validator = new PartitaIva($vatNumber);
   
   if ($validator->isValid()) {
       // VAT is valid
   } else {
       // VAT is invalid or requires further checks
   }
   

3. Where to Look First

   • Documentation: Check the GitHub repository (if available) for basic usage.
   • Source Code: The package is minimal; inspect src/PartitaIva.php for logic (e.g., Luhn algorithm checks, format validation).
   • Laravel Integration: Use Laravel’s validation system for seamless form handling:

     use Illuminate\Support\Facades\Validator;
     
     $validator = Validator::make(['vat' => $vatNumber], [
         'vat' => ['required', function ($attribute, $value, $fail) {
             $validator = new \Sorciulus\CheckPartitaIva\PartitaIva($value);
             if (!$validator->isValid()) {
                 $fail('The :attribute is invalid.');
             }
         }]
     ]);
     

Implementation Patterns

Usage Patterns

1. Basic Validation Validate a VAT number in isolation:

   $validator = new PartitaIva('01234567890');
   if ($validator->isValid()) {
       // Proceed
   }
   

2. Batch Validation Validate multiple VAT numbers (e.g., in a CSV import):

   $vatNumbers = ['12345678901', '09876543210', 'invalid'];
   $results = array_map(function ($vat) {
       return (new PartitaIva($vat))->isValid();
   }, $vatNumbers);
   

3. Laravel Form Requests Extend Laravel’s FormRequest for API/controller validation:

   use Illuminate\Foundation\Http\FormRequest;
   use Sorciulus\CheckPartitaIva\PartitaIva;
   
   class StoreCustomerRequest extends FormRequest
   {
       public function rules()
       {
           return [
               'vat_number' => 'required|vat_valid',
           ];
       }
   
       public function withValidator($validator)
       {
           $validator->after(function ($validator) {
               $vat = $this->input('vat_number');
               if (!$validator->passes(['vat_number' => 'required'])) {
                   return;
               }
               if (!(new PartitaIva($vat))->isValid()) {
                   $validator->errors()->add('vat_number', 'The VAT number is invalid.');
               }
           });
       }
   }
   

   Add 'vat_valid' => 'Sorciulus\CheckPartitaIva\Rules\VatValid' to your AppServiceProvider if the package provides a rule.

4. API Responses Return structured validation feedback:

   return response()->json([
       'valid' => (new PartitaIva($request->vat))->isValid(),
       'message' => (new PartitaIva($request->vat))->getMessage(),
   ]);
   

Workflows

1. User Registration Validate VAT during customer onboarding:

   $customer = new Customer();
   $customer->vat_number = $request->vat;
   if (!(new PartitaIva($request->vat))->isValid()) {
       return back()->withErrors(['vat' => 'Invalid VAT number.']);
   }
   $customer->save();
   

2. Supplier Management Validate supplier VAT numbers in a B2B context:

   $supplier = Supplier::find($id);
   if (!(new PartitaIva($supplier->vat))->isValid()) {
       $supplier->markAsInvalid();
       $supplier->save();
   }
   

3. Data Migration Cleanse existing VAT numbers in a database:

   $customers = Customer::all();
   foreach ($customers as $customer) {
       $validator = new PartitaIva($customer->vat_number);
       if (!$validator->isValid()) {
           $customer->vat_number = null; // or default value
           $customer->save();
       }
   }
   

Integration Tips

1. Localization Store validation messages in Laravel’s language files (resources/lang/it/validation.php):

   'vat_valid' => 'Il numero di partita IVA :attribute non è valido.',
   

2. Caching Cache validation results for frequently checked VAT numbers:

   $cacheKey = 'vat_'.$vatNumber;
   if (Cache::has($cacheKey)) {
       $isValid = Cache::get($cacheKey);
   } else {
       $isValid = (new PartitaIva($vatNumber))->isValid();
       Cache::put($cacheKey, $isValid, now()->addHours(1));
   }
   

3. Testing Mock the PartitaIva class in PHPUnit:

   $mock = $this->createMock(\Sorciulus\CheckPartitaIva\PartitaIva::class);
   $mock->method('isValid')->willReturn(true);
   $this->assertTrue($mock->isValid());
   

Gotchas and Tips

Pitfalls

1. False Positives/Negatives

   • The package uses basic format and Luhn checks but does not verify against the Italian tax authority’s database.
   • Workaround: Combine with an external API (e.g., Agenzia delle Entrate) for real-time validation.

2. Format Sensitivity

   • VAT numbers must be 11 digits (e.g., 12345678901). Leading zeros (e.g., 01234567890) are valid but may fail if stripped.
   • Tip: Normalize input:

     $vat = str_pad(trim($request->vat), 11, '0', STR_PAD_LEFT);
     

3. Deprecated Package

   • Last updated in 2017; may not support PHP 8+ or Laravel 9+.
   • Tip: Fork the repo and update dependencies if needed.

4. No Built-in Rule

   • The package lacks a Laravel validation rule by default.
   • Workaround: Create a custom rule:

     namespace App\Rules;
     use Sorciulus\CheckPartitaIva\PartitaIva;
     
     class VatValid implements \Illuminate\Contracts\Validation\Rule
     {
         public function passes($attribute, $value)
         {
             return (new PartitaIva($value))->isValid();
         }
     }
     

     Then use it in rules:

     'vat' => ['required', new \App\Rules\VatValid],
     

5. Edge Cases

   • VAT numbers for foreign companies operating in Italy (e.g., IT12345678901) are not handled.
   • Tip: Add a prefix check:

     if (str_starts_with($vat, 'IT')) {
         $vat = substr($vat, 2); // Remove 'IT' prefix
     }
     

Debugging

1. Validation Messages The package provides limited feedback. Extend it:

   $validator = new PartitaIva($vat);
   if (!$validator->isValid()) {
       $errors = [
           'format' => !$validator->isCorrectFormat(),
           'checksum' => !$validator->isCorrectChecksum(),
       ];
   }
   

2. Logging Log invalid VAT attempts for auditing:

   if (!(new PartitaIva($vat))->isValid()) {
       \Log::warning("Invalid VAT submitted: {$vat}", ['ip' => $request->ip()]);
   }
   

Config Quirks

• No Configuration File: The package is stateless; no config/check-partita-iva.php exists.
• Extension Points:
  • Override PartitaIva logic by extending the class:

    class CustomPartitaIva extends \Sorciulus\CheckPartitaIva\PartitaIva
    {
        public function isValid()
        {
            // Custom logic
            return parent::isValid() && $this->customCheck();
        }
    }
    

Performance

• Lightweight: The package is ~50 lines of code; validation is O(1).
• **Tip