PHPackages                             matav5/vies-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. matav5/vies-sdk

ActiveLibrary[API Development](/categories/api)

matav5/vies-sdk
===============

PHP SDK for the EU VIES (VAT Information Exchange System) REST API

v0.0.3(4mo ago)2118↓89.3%MITPHPPHP >=8.1

Since Feb 20Pushed 4mo agoCompare

[ Source](https://github.com/Matav5/vies-sdk)[ Packagist](https://packagist.org/packages/matav5/vies-sdk)[ RSS](/packages/matav5-vies-sdk/feed)WikiDiscussions main Synced yesterday

READMEChangelog (3)Dependencies (2)Versions (4)Used By (0)

VIES SDK
========

[](#vies-sdk)

PHP SDK for the [EU VIES (VAT Information Exchange System)](https://ec.europa.eu/taxation_customs/vies/) REST API.

Validate EU VAT numbers and check the availability of member states via a clean, PSR-18 compatible HTTP client.

Requirements
------------

[](#requirements)

- PHP 8.1+
- A PSR-18 HTTP client (e.g. `symfony/http-client`)
- A PSR-17 request & stream factory (e.g. `nyholm/psr7`)

Installation
------------

[](#installation)

```
composer require matav5/vies-sdk
```

You also need a PSR-18 client and PSR-17 factories. The recommended combination:

```
composer require symfony/http-client nyholm/psr7
```

Usage
-----

[](#usage)

### Setup

[](#setup)

```
use Matav5\ViesSdk\ViesClient;
use Nyholm\Psr7\Factory\Psr17Factory;
use Symfony\Component\HttpClient\Psr18Client;

$psr17 = new Psr17Factory();
$http  = new Psr18Client(null, $psr17, $psr17);

$vies = new ViesClient($http, $http, $http);
```

`Psr18Client` implements PSR-18, PSR-17 RequestFactory and PSR-17 StreamFactory simultaneously, which is why it is passed three times.

### Validate a VAT number

[](#validate-a-vat-number)

```
use Matav5\ViesSdk\Request\CheckVatRequest;

$response = $vies->vat()->check(new CheckVatRequest('CZ', '27082440'));

$response->isValid();        // true
$response->getCountryCode(); // 'CZ'
$response->getVatNumber();   // '27082440'
$response->getName();        // 'Alza.cz a.s.'
$response->getAddress();     // 'Jankovcova 1522/53 ...'
$response->getRequestDate(); // '2024-01-01T00:00:00Z'
```

### Approximate trader matching

[](#approximate-trader-matching)

Pass optional trader fields to verify company details against the VIES registry. The API returns a `MatchStatus` for each field if the member state supports approximate matching.

```
use Matav5\ViesSdk\Enum\MatchStatus;
use Matav5\ViesSdk\Request\CheckVatRequest;

$request = new CheckVatRequest(
    countryCode: 'DE',
    vatNumber:   '123456789',
    traderName:  'Example GmbH',
    traderCity:  'Berlin',
);

$response = $vies->vat()->check($request);

$response->getTraderNameMatch(); // MatchStatus::VALID | INVALID | NOT_PROCESSED | null
$response->getTraderCityMatch();
```

`NOT_PROCESSED` means the member state does not support approximate matching for that field.

To also receive a `requestIdentifier`, provide your own VAT number as the requester:

```
$request = new CheckVatRequest(
    countryCode:              'DE',
    vatNumber:                '123456789',
    requesterMemberStateCode: 'CZ',
    requesterNumber:          'CZ27082440',
);

$response->getRequestIdentifier(); // 'WAPPws...'
```

### Test endpoint

[](#test-endpoint)

The VIES API provides a test endpoint that works without a real VAT number:

```
// vatNumber 100 → valid, 200 → invalid (documented test values)
$response = $vies->vat()->checkTest(new CheckVatRequest('CZ', '100'));
$response->isValid(); // true
```

### Member state availability

[](#member-state-availability)

```
$status = $vies->status()->check();

$status->isVowAvailable(); // true
$status->getCountries();   // array

foreach ($status->getCountries() as $country) {
    echo $country->getCountryCode();  // 'CZ'
    echo $country->getAvailability(); // 'Available' | 'Unavailable' | 'Monitoring Disabled'
}
```

### Error handling

[](#error-handling)

```
use Matav5\ViesSdk\Exception\ApiException;
use Matav5\ViesSdk\Exception\ViesSdkException;

try {
    $response = $vies->vat()->check(new CheckVatRequest('CZ', ''));
} catch (ApiException $e) {
    // HTTP error response from the VIES API
    $e->getStatusCode();  // 400
    $e->getErrorCodes();  // ['VOW-ERR-11']
    $e->getResponse();    // PSR-7 ResponseInterface
} catch (ViesSdkException $e) {
    // Network error or invalid JSON response
}
```

`ApiException` extends `ViesSdkException`, so you can catch all SDK errors with a single `catch (ViesSdkException $e)`.

### Custom configuration

[](#custom-configuration)

```
use Matav5\ViesSdk\Config;
use Matav5\ViesSdk\ViesClient;

$config = new Config(
    baseUrl: 'https://ec.europa.eu/taxation_customs/vies/rest-api',
    timeout: 10,
);

$vies = new ViesClient($http, $http, $http, $config);
```

Running tests
-------------

[](#running-tests)

```
# Unit tests only
composer test

# Integration tests (calls the real VIES API)
composer test:integration

# All tests
composer test:all
```

License
-------

[](#license)

MIT

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance75

Regular maintenance activity

Popularity13

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

133d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/44439735?v=4)[Matěj Verner](/maintainers/Matav5)[@Matav5](https://github.com/Matav5)

---

Top Contributors

[![Matav5](https://avatars.githubusercontent.com/u/44439735?v=4)](https://github.com/Matav5 "Matav5 (1 commits)")

---

Tags

sdkvattaxvieseu

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/matav5-vies-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/matav5-vies-sdk/health.svg)](https://phpackages.com/packages/matav5-vies-sdk)
```

###  Alternatives

[temporal/sdk

Temporal SDK

4072.9M25](/packages/temporal-sdk)[deepseek-php/deepseek-php-client

deepseek PHP client is a robust and community-driven PHP client library for seamless integration with the Deepseek API, offering efficient access to advanced AI and data processing capabilities.

46688.8k5](/packages/deepseek-php-deepseek-php-client)[storyblok/php-management-api-client

Storyblok PHP Client for Management API

1233.5k3](/packages/storyblok-php-management-api-client)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)