README

laravel-vat-eu-validator is a package inspired from vat.php to validate a VAT number for businesses based in Europe.

For Laravel 10, 11, 12, 13 use tag 3.x

For Laravel 10, 11, 12 use tag 2.x (legacy SOAP-only)

For Laravel 8, 9 use tag 1.20

For Laravel 5, 6, 7 use tag 0.5.4

What's new in v3.0

• REST Client support: an alternative to the traditional SOAP client, using the official European Commission REST APIs
• Strategy Pattern architecture: ViesClientInterface interface with ViesSoapClient and ViesRestClient implementations
• Publishable configuration file: choose which client to use and configure its parameters
• Restructured test suite: separation between unit and functional tests
• PHP 8.4 e 8.5 support

Installation

You can install the package via composer:

composer require danielebarbaro/laravel-vat-eu-validator

The package will automatically register itself.

Configuration

VIES Client Configuration

The package supports multiple VIES clients for VAT validation:

• SOAP Client (default): Uses the traditional SOAP API
• REST Client: Uses the modern REST API

To customize the client configuration, publish the configuration file:

php artisan vendor:publish --tag=laravel-vat-eu-validator-config

This will create a config/vat-validator.php file where you can configure which client to use:

<?php

use Danielebarbaro\LaravelVatEuValidator\Vies\ViesRestClient;
use Danielebarbaro\LaravelVatEuValidator\Vies\ViesSoapClient;

return [
    // Select which client to use for VIES validation
    // Available: ViesSoapClient::CLIENT_NAME, ViesRestClient::CLIENT_NAME
    'client' => ViesSoapClient::CLIENT_NAME, // Default: SOAP

    'clients' => [
        ViesSoapClient::CLIENT_NAME => [
            'timeout' => 10,
        ],
        ViesRestClient::CLIENT_NAME => [
            'timeout' => 10,
            'base_url' => ViesRestClient::BASE_URL,
        ],
    ],
];

Switching to REST Client

To use the REST client instead of SOAP, update your config/vat-validator.php:

'client' => ViesRestClient::CLIENT_NAME,

The REST client uses the official European Commission VIES REST API endpoints, which do not require authentication or API keys.

Customizing REST Client Configuration

You can customize the REST client timeout and base URL if needed:

'clients' => [
    ViesRestClient::CLIENT_NAME => [
        'timeout' => 10, // seconds
        'base_url' => env('VIES_REST_BASE_URL', ViesRestClient::BASE_URL),
    ],
],

By default, the client uses the official EU endpoint: https://ec.europa.eu/taxation_customs/vies/rest-api

Customizing Timeout

You can adjust the timeout for API requests:

'clients' => [
    ViesSoapClient::CLIENT_NAME => [
        'timeout' => 30, // seconds
    ],
],

Usage

use Danielebarbaro\LaravelVatEuValidator\Facades\VatValidatorFacade as VatValidator;

// Check VAT format and VIES existence
VatValidator::validate('IT12345');

// Check VAT format
VatValidator::validateFormat('IT12345678901'); 

// Check VAT existence
VatValidator::validateExistence('IT12345678901');

Validation

The package registers two new validation rules.

vat_number

The field under validation must be a valid and existing VAT number.

vat_number_exist

The field under validation check id is an existing VAT number.

vat_number_format

The field under validation must be a valid VAT number.

use Illuminate\Http\Request;

class Controller {

    public function foo(Request $request) 
    {
        $request->validate([
            'bar_field' => [new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumber()],
        ]);
        
        $request->validate([
            'bar_field' => [new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumberExist()],
        ]);
        
        $request->validate([
            'bar_field' => [new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumberFormat()],
       ]);
    }
}

Alternatively, you can also use the Rule directly.

use Illuminate\Http\Request;
use Danielebarbaro\LaravelVatEuValidator\Rules;

class Controller {

    public function foo(Request $request) 
    {
        $request->validate([
            'bar_field' => [ new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumber() ],
            'bar_field' => [ new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumberExist() ],
            'bar_field' => [ new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumberFormat() ],
        ]);
    }
}

or

use Illuminate\Http\Request;
use Danielebarbaro\LaravelVatEuValidator\Rules;

class Controller {

    public function foo(Request $request)
    {
        $request->validate([
            'bar_field' => [
                new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumber(),
                new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumberExist(),
                new \Danielebarbaro\LaravelVatEuValidator\Rules\VatNumberFormat(),
            ],
        ]);
    }
}

or

use Illuminate\Http\Request;
use Danielebarbaro\LaravelVatEuValidator\Rules;

class Controller {

    public function foo(Request $request)
    {
        $request->validate([
            'bar_field' => [
                'vat_number',
                'vat_number_format',
                'vat_number_exist',
            ],
        ]);
    }
}

Translations

Most of the displayed strings are defined in the vatEuValidator::validation translation files. The package ships with a few supported locales, but if yours is not yet included we would greatly appreciate a PR.

If not already published, you can edit or fill the translation files using php artisan vendor:publish --tag=laravel-vat-eu-validator-lang, this will copy our translation files to your app's vendor/laravelVatEuValidator "lang" path.

Testing

# Run unit tests
composer test

# Run functional tests (makes actual API calls)
composer test-functional

For detailed testing documentation, see tests/README.md.

Upgrading from v2.x to v3.0

No changes needed if you use the package as-is

The package works out-of-the-box with SOAP as the default client, exactly as before.

If you were instantiating VatValidator or Client manually

// ❌ Before (v2.x)
use Danielebarbaro\LaravelVatEuValidator\Vies\Client;
$validator = new VatValidator(new Client());

// ✅ After (v3.0)
use Danielebarbaro\LaravelVatEuValidator\Vies\ViesSoapClient;
$validator = new VatValidator(new ViesSoapClient());

// Or with REST client
use Danielebarbaro\LaravelVatEuValidator\Vies\ViesRestClient;
$validator = new VatValidator(new ViesRestClient());

If you want to switch to the REST client

1. Publish the configuration: php artisan vendor:publish --tag=laravel-vat-eu-validator-config
2. Update config/vat-validator.php:

'client' => ViesRestClient::CLIENT_NAME,

If your tests reference Vies\Client

Update references to ViesSoapClient or use ViesClientInterface for mocking.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email barbaro.daniele@gmail.com instead of using the issue tracker.

Credits

• Daniele Barbaro

Contributors

• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Laravel Package Boilerplate

This package was generated using the Laravel Package Boilerplate.