Getting Started

Minimal Steps

Installation:
```
composer require antalaron/vat-number-validator
```
No additional configuration is required beyond this.

First Use Case: Validate a VAT number in a Laravel controller or form request:

use Antalaron\Component\VatNumberValidator\VatNumber;
use Illuminate\Support\Facades\Validator;

$validator = Validator::make(['vat' => 'ATU37675002'], [
    'vat' => ['required', new VatNumber()]
]);

if ($validator->fails()) {
    return response()->json(['errors' => $validator->errors()], 422);
}

Where to Look First:
- README.md: For basic usage and configuration options.
- Tests: Located in tests/ directory, showcasing edge cases and valid/invalid VAT examples.
- Source Code: src/VatNumber.php for understanding the validation logic and extension points.

Implementation Patterns

Usage Patterns

Form Request Validation: Extend Laravel's FormRequest to validate VAT numbers during user input:

use Antalaron\Component\VatNumberValidator\VatNumber;
use Illuminate\Foundation\Http\FormRequest;

class StoreCustomerRequest extends FormRequest
{
    public function rules()
    {
        return [
            'vat_number' => ['required', 'string', new VatNumber()],
        ];
    }
}

API Request Validation: Validate VAT numbers in API payloads using Laravel's Validator facade:

use Antalaron\Component\VatNumberValidator\VatNumber;
use Illuminate\Support\Facades\Validator;

$validator = Validator::make($request->all(), [
    'vat_number' => ['required', new VatNumber()],
]);

if ($validator->fails()) {
    return response()->json(['errors' => $validator->errors()], 422);
}

Custom Validation Rules: Create reusable validation rules for VAT numbers:

use Antalaron\Component\VatNumberValidator\VatNumber;
use Illuminate\Validation\Rule;

class VatNumberRule extends Rule
{
    public function validate($attribute, $value, $fail)
    {
        $validator = \Symfony\Component\Validator\Validation::createValidator();
        $violations = $validator->validate($value, new VatNumber());

        if (!empty($violations)) {
            $fail($violations->first()->getMessage());
        }
    }
}

Use it in your validation rules:

'vat_number' => ['required', new \App\Rules\VatNumberRule],

Custom VAT Logic: Extend the validator with additional rules using the extraVat option:

$validator = Validator::make(['vat' => '11'], [
    'vat' => [new VatNumber([
        'extraVat' => function ($number) {
            return preg_match('/^(\d{2})$/', $number);
        }
    ])],
]);

Workflows

User Onboarding: Validate VAT numbers during customer registration to ensure compliance before account creation.
Invoice Processing: Validate VAT numbers in invoicing systems to ensure accurate tax calculations and compliance with EU directives.
B2B Transactions: Validate VAT numbers for business-to-business transactions to avoid penalties and ensure smooth cross-border operations.
Data Migration: Validate VAT numbers in existing databases during data migration to ensure data integrity.

Integration Tips

Laravel Service Providers: Bind the validator to the Laravel container for easier dependency injection:

use Antalaron\Component\VatNumberValidator\VatNumber;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->bind(VatNumber::class, function () {
            return new VatNumber();
        });
    }
}

Localization: Customize error messages for different locales:

$validator = Validator::make(['vat' => 'INVALID'], [
    'vat' => [new VatNumber()],
], [
    'vat.required' => 'The VAT number field is required.',
    'vat.vat_number' => 'The provided VAT number is invalid.',
]);

Testing: Write unit tests to ensure VAT validation works as expected:

use Antalaron\Component\VatNumberValidator\VatNumber;
use Symfony\Component\Validator\Validation;
use Symfony\Component\Validator\Validator\ValidatorInterface;

public function testValidVatNumber()
{
    $validator = Validation::createValidator();
    $violations = $validator->validate('ATU37675002', new VatNumber());

    $this->assertEmpty($violations);
}

public function testInvalidVatNumber()
{
    $validator = Validation::createValidator();
    $violations = $validator->validate('INVALID', new VatNumber());

    $this->assertNotEmpty($violations);
}

Logging: Log validation failures for auditing and debugging:

$validator = Validator::make(['vat' => 'INVALID'], [
    'vat' => [new VatNumber()],
]);

if ($validator->fails()) {
    \Log::error('VAT validation failed', [
        'errors' => $validator->errors()->toArray(),
        'input' => $request->all(),
    ]);
}

Gotchas and Tips

Pitfalls

Symfony Version Compatibility:
- The package requires Symfony Validator 2.8–5.0. Laravel 10+ uses Symfony 6+, which may cause compatibility issues.
- Solution: Monitor future releases for Symfony 6+ support or fork the package if needed.
False Positives/Negatives:
- The validator relies on Braemoor’s rules, which may not cover all edge cases (e.g., temporary VAT numbers, non-EU formats).
- Solution: Test with a diverse dataset of valid and invalid VAT numbers, including edge cases like Dutch sole proprietors and Czech birth IDs.
Performance:
- No benchmarks are provided, but regex-based validation may not scale for high-throughput applications (>10K operations/sec).
- Solution: Cache validated VAT numbers in Redis or implement batch validation for high-volume scenarios.
Custom Logic Maintenance:
- Custom extraVat logic requires PHP knowledge and may need updates if business rules change.
- Solution: Document custom rules thoroughly and assign ownership to a team member.
Error Messages:
- Default error messages may not be user-friendly. Customize them for better UX.
- Solution: Override error messages in the validator configuration.

Debugging

Validation Failures:
- If a valid VAT number fails validation, check the country-specific rules in the source code (src/VatNumber.php).
- Debugging Tip: Use dd($violations) to inspect the validation errors and identify the specific rule that failed.
Custom Rules:
- If extraVat logic fails, ensure the callback returns true for valid VAT numbers and false for invalid ones.
- Debugging Tip: Log the input and output of the extraVat callback to verify its behavior.
Symfony Dependency Issues:
- If you encounter Symfony-related errors, ensure your Laravel application’s Symfony components are up-to-date.
- Debugging Tip: Run composer why-not symfony/validator:^5.0 to check for version conflicts.

Configuration Quirks

ExtraVat Option:
- The extraVat option allows adding custom validation logic but must return a boolean value. Ensure your callback adheres to this requirement.
- Example of incorrect usage:
```
'extraVat' => function ($number) {
    return 'invalid'; // Wrong: must return boolean
}
```
Country-Specific Rules:
- Some countries have unique VAT formats (e.g., Czech birth IDs, Dutch sole proprietors). Ensure these are covered in your tests.
- Tip: Refer to the release notes for updates on supported countries and formats.

Extension Points

Custom Validators:

Extend the VatNumber class to add support for non-EU VAT formats or business-specific rules.

Example:

use Antalaron\Component\VatNumberValidator\VatNumber as BaseVatNumber;

class CustomVatNumber extends BaseVatNumber
{
    public function configureOptions(OptionsResolver $resolver)
    {
        parent::configureOptions($resolver);
        $resolver->setDefaults([
            'extraVat' => function ($number) {
                // Add custom logic here
                return true;
            },
        ]);
    }
}

Integration with Laravel Rules:
- Create a Laravel-specific rule class to simplify usage in validation arrays:
```
use Antalaron\Component\VatNumberValidator\VatNumber;
use
```

Vat Number Validator Laravel Package