Looking to hire Laravel developers? Try LaraJobs

laravel-vat-validator maintained by hansdeboeck

Description
EU VAT (BTW) validator for Laravel — VIES with automatic fallbacks (controleerbtwnummer.eu, btw-opzoeken.be), 24h cache, address parsing.
Author
Hans De Boeck
Last update
2026/04/26 13:33 (dev-main)
License
MIT
Links
GitHub - Packagist
Downloads
417
Tags
validator - vat - btw - laravel - vies - belgium

dev-main

Last update
2026/04/26 13:33
License
MIT
Require
  • php ^8.2
  • illuminate/http ^11.0|^12.0|^13.0
  • illuminate/cache ^11.0|^12.0|^13.0
  • illuminate/support ^11.0|^12.0|^13.0
  • illuminate/contracts ^11.0|^12.0|^13.0
v1.0.0

Last update
2026/04/26 13:33
License
MIT
Require
  • php ^8.2
  • illuminate/http ^11.0|^12.0|^13.0
  • illuminate/cache ^11.0|^12.0|^13.0
  • illuminate/support ^11.0|^12.0|^13.0
  • illuminate/contracts ^11.0|^12.0|^13.0
Comments
comments powered by Disqus

laravel-vat-validator

EU BTW-nummer validatie voor Laravel. VIES als primaire bron met automatische fallbacks naar controleerbtwnummer.eu en btw-opzoeken.be. Cached, geretry'd, met adres-parsing.

Installatie

Lokaal (path-repository) — voeg toe aan je app's composer.json:

{
    "require": {
        "hansdeboeck/laravel-vat-validator": "*"
    },
    "repositories": [
        { "type": "path", "url": "../laravel-vat-validator" }
    ]
}

Daarna:

composer require hansdeboeck/laravel-vat-validator:*
php artisan vendor:publish --tag=vat-validator-config   # optioneel

Gebruik

use HansDeBoeck\VatValidator\VatValidator;

$result = app(VatValidator::class)->lookup('BE0405622220');

if ($result->valid) {
    echo $result->name;                     // "ALDI HOLDING NV"
    echo $result->vatNumber;                // "BE0405622220"
    echo $result->countryCode;              // "BE"
    echo $result->source;                   // "vies" | "cbw" | "btwo"
    echo $result->address?->street;
    echo $result->address?->zipCode;
    echo $result->address?->city;
} else {
    echo $result->error;
}

Validation rule

$request->validate([
    'vat' => ['required', 'vat'],
]);

Vraagt VIES om de input te valideren — dezelfde semantiek als lookup().

Array access (legacy)

Het result-object implementeert ArrayAccess, zodat code die een array verwachtte blijft werken:

$result['valid'];
$result['vat_number'];
$result['address']['city'];

Configuratie

config/vat-validator.php:

Key Default Doel
cache_ttl 86400 (24u) Hoe lang positieve lookups gecached worden
cache_enabled true Voor tests/debug uit te zetten
cache_prefix vat: Wijzig om bestaande cache te invalideren
http_timeout 6s Per HTTP-request, niet onder 5
fallbacks_enabled true Schakel niet-VIES bronnen uit

Override via env: VAT_VALIDATOR_CACHE_TTL, VAT_VALIDATOR_FALLBACKS, etc.

Bronnen

  1. VIES (EU) — https://ec.europa.eu/taxation_customs/vies/rest-api/... — primaire bron, retried 2× met 200ms.
  2. controleerbtwnummer.eu — fallback voor alle EU-landen wanneer VIES geen antwoord geeft.
  3. btw-opzoeken.be — laatste redmiddel, alleen voor BE-nummers.

Negatieve lookups worden niet gecached (zodat een net geactiveerd BTW-nummer niet 24u onbruikbaar blijft).