belghiti/vies-client

Core PSR-18 VIES (VoW) REST API client (Belghiti\Vies) with retry and DTOs.

v0.1.1 2026-02-23 14:52 UTC

Requires

• php: >=8.1
• guzzlehttp/psr7: ^2.6
• psr/http-client: ^1.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.1

Requires (Dev)

• guzzlehttp/guzzle: ^7.9
• justinrainbow/json-schema: ^6.0
• phpunit/phpunit: ^10.5
• symfony/yaml: ^6.4 || ^7.0

MIT

README

A lightweight, framework‑agnostic PSR‑18 client for the European Commission’s VIES (VAT Information Exchange System) REST API.

• DTOs for requests/responses (CheckVatRequest, CheckVatResponse, StatusInformationResponse)
• Retry decorator (exponential backoff)
• Contract test against the official Swagger (downloaded in CI)
• Non‑fatal smoke test of GET /check-status to the public VIES REST base

Requirements

• PHP 8.1+ (CI matrix covers 8.1 – 8.5)
• Any PSR‑18 HTTP client + PSR‑17 factories (e.g., Guzzle + Nyholm PSR‑7)

Installation

composer require belghiti/vies-client
# (optional) choose a PSR-18 stack:
composer require guzzlehttp/guzzle guzzlehttp/psr7     # Guzzle PSR-18 + PSR-7
# or
composer require symfony/http-client nyholm/psr7       # Symfony Psr18Client + PSR-7

Quick start (Guzzle PSR‑18)

use Belghiti\Vies\Client\HttpViesClient;
use Belghiti\Vies\Support\Adapter\GuzzlePsr18Client;
use Belghiti\Vies\Dto\CheckVatRequest;
use GuzzleHttp\Client as Guzzle;
use GuzzleHttp\Psr7\HttpFactory;

$psr18   = new GuzzlePsr18Client(new Guzzle());
$factory = new HttpFactory();

$client = new HttpViesClient(
    http:           $psr18,
    requestFactory: $factory,
    streamFactory:  $factory,
    baseUri:        'https://ec.europa.eu/taxation_customs/vies/rest-api'
);

$res = $client->checkVatNumber(new CheckVatRequest('FR', '40303265045'));
var_dump($res->valid);

API surface

interface ViesClientInterface {
    public function checkVatNumber(CheckVatRequest $request): CheckVatResponse;
    public function checkVatTestService(CheckVatRequest $request): CheckVatResponse;
    public function checkStatus(): StatusInformationResponse;
}

• CheckVatRequest matches the public contract fields (countryCode, vatNumber, optional requester* & trader fields)
• checkStatus() returns overall VOW availability and per‑country availability entries

Retry & caching

• Wrap the core client with Belghiti\Vies\Decorator\RetryingViesClient for exponential backoff
• Add your own cache decorator, or use the Laravel/Symfony packages for prebuilt caching

Quality

composer lint   # PSR-12 via PHP_CodeSniffer
composer stan   # PHPStan (level max)
vendor/bin/phpunit

License

MIT