PHPackages                             omisai/vies-rest - 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. [HTTP & Networking](/categories/http)
4. /
5. omisai/vies-rest

ActiveLibrary[HTTP & Networking](/categories/http)

omisai/vies-rest
================

PHP package to check Vat number through REST API of VIES

v1.1.1(2mo ago)11561MITPHPPHP ^8.1CI passing

Since Feb 10Pushed 2mo agoCompare

[ Source](https://github.com/omisai-tech/php-vies-rest)[ Packagist](https://packagist.org/packages/omisai/vies-rest)[ Docs](https://github.com/omisai-tech/php-vies-rest)[ RSS](/packages/omisai-vies-rest/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (8)Versions (5)Used By (1)

PHP VIES REST
=============

[](#php-vies-rest)

[![Latest Version on Packagist](https://camo.githubusercontent.com/0dc1d4de1d394584d3246ef90aeeaabfbeeef29c1e3ecc6e49a1f5fe27a96da0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6d697361692f766965732d726573742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/omisai/vies-rest)[![License](https://camo.githubusercontent.com/458425f8985b0b0c8a736cffe75e05a098e3d77906acddbcad2bfc54492a4e02/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e7376673f7374796c653d666c61742d737175617265)](https://github.com/sponsors/omisai-tech/LICENSE)[![Test](https://github.com/omisai-tech/php-vies-rest/actions/workflows/test.yml/badge.svg)](https://github.com/omisai-tech/php-vies-rest/actions/workflows/test.yml)[![PHP Version Require](https://camo.githubusercontent.com/5a7c3fe4812f22f94f5e0df5cf2ef1169288c850de4e43a80a2073ca8f96d65e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d253345253344382e312d626c75653f7374796c653d666c61742d737175617265266c6f676f3d706870)](https://packagist.org/packages/omisai/vies-rest)

A lightweight, type-safe PHP package for validating EU VAT numbers via the European Commission's VIES (VAT Information Exchange System) REST service.

Features
--------

[](#features)

- **Type-safe**: PHP 8.1+ type declarations and modern enum support
- **Clean architecture**: DTOs, validation, and HTTP adapters
- **Production + test modes**: Switch services via `ViesConfig`
- **Error handling**: Structured exceptions for validation and REST errors
- **Approximate matching**: Trader detail matching support
- **All EU countries**: EU member states plus Northern Ireland
- **Tested**: Pest-based test suite

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

[](#requirements)

- PHP 8.1 or higher
- ext-curl
- ext-json
- ext-mbstring

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

[](#installation)

Install the package via Composer:

```
composer require omisai/vies-rest
```

Quick Start
-----------

[](#quick-start)

### Basic VAT Validation

[](#basic-vat-validation)

```
use Omisai\ViesRest\ViesClient;

$client = new ViesClient();
$response = $client->checkVat('DE', '123456789');

if ($response->valid) {
    echo "✅ Valid VAT: {$response->countryCode}{$response->vatNumber}\n";
    echo "Company: {$response->name}\n";
    echo "Address: {$response->address}\n";
} else {
    echo "❌ Invalid VAT number\n";
}
```

### Using the Test Service

[](#using-the-test-service)

```
use Omisai\ViesRest\ViesClient;
use Omisai\ViesRest\ViesConfig;

$client = new ViesClient(ViesConfig::test());
$response = $client->checkVat('DE', '100');

var_dump($response->valid); // true for test numbers
```

Configuration
-------------

[](#configuration)

### Environment Configuration

[](#environment-configuration)

```
use Omisai\ViesRest\ViesConfig;

$production = ViesConfig::production();
$test = ViesConfig::test();

$custom = ViesConfig::production(baseUrl: 'https://custom-vies.example.com');
```

### HTTP Client Options

[](#http-client-options)

```
use Omisai\ViesRest\ViesClient;
use Omisai\ViesRest\ViesConfig;

$options = [
    'timeout' => 30,
    'connect_timeout' => 10,
    'headers' => [
        'User-Agent' => 'MyApp/1.0',
    ],
];

$client = new ViesClient(ViesConfig::production(options: $options));
```

API Reference
-------------

[](#api-reference)

### ViesClient

[](#viesclient)

#### `checkVat(string $countryCode, string $vatNumber): CheckVatResponse`

[](#checkvatstring-countrycode-string-vatnumber-checkvatresponse)

Validates a VAT number and returns basic information.

#### `checkVatApprox(CheckVatRequest $request): CheckVatResponse`

[](#checkvatapproxcheckvatrequest-request-checkvatresponse)

Performs approximate validation with trader details.

#### `checkStatus(): StatusInformationResponse`

[](#checkstatus-statusinformationresponse)

Returns availability info for member states.

### Data Transfer Objects (DTOs)

[](#data-transfer-objects-dtos)

#### CheckVatRequest

[](#checkvatrequest)

```
use Omisai\ViesRest\DTO\CheckVatRequest;

$request = new CheckVatRequest(
    countryCode: 'NL',
    vatNumber: '123456789B01',
    traderName: 'Example B.V.',
    traderStreet: 'Main Street 123',
    traderPostalCode: '1234AB',
    traderCity: 'Amsterdam',
    requesterMemberStateCode: 'DE',
    requesterNumber: '123456789',
);
```

#### CheckVatResponse

[](#checkvatresponse)

```
echo $response->countryCode;
echo $response->vatNumber;
echo $response->requestDate->format('Y-m-d');
echo $response->valid ? 'Yes' : 'No';
```

Supported Countries
-------------------

[](#supported-countries)

```
use Omisai\ViesRest\Enum\EuropeanUnionCountry;

$isValid = EuropeanUnionCountry::isEuropeanUnionCountryCode('DE'); // true
$isValid = EuropeanUnionCountry::isEuropeanUnionCountryCode('US'); // false
```

Error Handling
--------------

[](#error-handling)

### Validation Errors

[](#validation-errors)

```
use Omisai\ViesRest\Exceptions\ViesValidationException;
use Omisai\ViesRest\ViesClient;

$client = new ViesClient();

try {
    $client->checkVat('INVALID', '123');
} catch (ViesValidationException $e) {
    echo "Validation error: {$e->getMessage()}\n";
}
```

### REST API Errors

[](#rest-api-errors)

```
use Omisai\ViesRest\Exceptions\ViesApiException;
use Omisai\ViesRest\ViesClient;

$client = new ViesClient();

try {
    $client->checkVat('DE', '123456789');
} catch (ViesApiException $e) {
    echo "API error: {$e->getMessage()}\n";
    echo "Status code: {$e->getStatusCode()}\n";
}
```

Advanced Usage
--------------

[](#advanced-usage)

### Custom HTTP Client Factory

[](#custom-http-client-factory)

```
use Omisai\ViesRest\ViesClient;
use Omisai\ViesRest\Http\HttpClientFactoryInterface;

class CustomHttpClientFactory implements HttpClientFactoryInterface
{
    public function create(string $baseUrl, array $options = [])
    {
        // Return a custom adapter implementing HttpClientInterface
    }
}

$client = new ViesClient(clientFactory: new CustomHttpClientFactory());
```

### Custom Validation

[](#custom-validation)

```
use Omisai\ViesRest\ViesClient;
use Omisai\ViesRest\Validation\VatNumberValidator;

class CustomVatNumberValidator extends VatNumberValidator
{
    // Implement custom validation logic
}

$client = new ViesClient(validator: new CustomVatNumberValidator());
```

### Batch Processing

[](#batch-processing)

```
use Omisai\ViesRest\ViesClient;

$client = new ViesClient();
$vatNumbers = [
    ['DE', '123456789'],
    ['NL', '123456789B01'],
    ['FR', '12345678901'],
];

$results = [];
foreach ($vatNumbers as [$country, $vat]) {
    try {
        $response = $client->checkVat($country, $vat);
        $results[] = [
            'country' => $response->countryCode,
            'vat' => $response->vatNumber,
            'valid' => $response->valid,
            'name' => $response->name,
        ];
    } catch (Exception $e) {
        $results[] = [
            'country' => $country,
            'vat' => $vat,
            'error' => $e->getMessage(),
        ];
    }
}

print_r($results);
```

Testing
-------

[](#testing)

Run the test suite using Pest:

```
composer test
```

Performance Considerations
--------------------------

[](#performance-considerations)

- The VIES service has rate limits - avoid excessive requests
- REST calls are synchronous and may take 1-5 seconds
- Consider caching valid VAT numbers to reduce API calls
- Use the test service for development to avoid affecting production quotas

Limitations
-----------

[](#limitations)

- Requires internet connection to VIES service
- Service may be unavailable during maintenance windows
- Rate limiting applies to prevent abuse
- Some countries may have additional validation rules

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.

Security
--------

[](#security)

Please see [SECURITY.md](.github/SECURITY.md) for details on reporting security vulnerabilities.

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Sponsoring
----------

[](#sponsoring)

If you find this package useful, please consider sponsoring the development: [Sponsoring on GitHub](https://github.com/sponsors/omisai-tech)

Your support helps us maintain and improve this open-source project!

Official VIES Documentation
---------------------------

[](#official-vies-documentation)

- [European Commission VIES Website](https://ec.europa.eu/taxation_customs/vies)
- [VIES REST API Documentation](https://ec.europa.eu/assets/taxud/vow-information/swagger_publicVAT.yaml)

###  Health Score

43

—

FairBetter than 91% of packages

Maintenance88

Actively maintained with recent releases

Popularity17

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 98.4% 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 ~11 days

Total

4

Last Release

61d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/818e031ac6546efe377b692f91166dc1a6c89b8838ce720b8786e4b15a30db62?d=identicon)[bornemisza](/maintainers/bornemisza)

---

Top Contributors

[![bornemisza](https://avatars.githubusercontent.com/u/22169041?v=4)](https://github.com/bornemisza "bornemisza (63 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

apiphprestsdkviesapisdkrestvies

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/omisai-vies-rest/health.svg)

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

###  Alternatives

[onesignal/onesignal-php-api

A powerful way to send personalized messages at scale and build effective customer engagement strategies. Learn more at onesignal.com

34170.2k2](/packages/onesignal-onesignal-php-api)[ory/hydra-client

Documentation for all of Ory Hydra's APIs.

17435.9k](/packages/ory-hydra-client)[zenditplatform/zendit-php-sdk

PHP client for Zendit API

1204.3k](/packages/zenditplatform-zendit-php-sdk)[huaweicloud/huaweicloud-sdk-php

Huawei Cloud SDK for PHP

1829.2k2](/packages/huaweicloud-huaweicloud-sdk-php)[ory/hydra-client-php

Documentation for all of Ory Hydra's APIs.

1710.8k](/packages/ory-hydra-client-php)

PHPackages © 2026

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