PHPackages                             omisai/vies-soap - 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. omisai/vies-soap

ActiveLibrary[API Development](/categories/api)

omisai/vies-soap
================

PHP package to check Vat number through SOAP API of VIES

v1.1.0(2mo ago)16MITPHPPHP ^8.1CI passing

Since Feb 9Pushed 2mo agoCompare

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

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

PHP VIES SOAP
=============

[](#php-vies-soap)

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

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

Features
--------

[](#features)

- ✅ **Type-safe**: Full PHP 8.1+ type declarations and modern enum support
- ✅ **Comprehensive validation**: Built-in country code and VAT number validation
- ✅ **Production ready**: Supports both production and test VIES services
- ✅ **Error handling**: Structured exceptions for SOAP faults and validation errors
- ✅ **Approximate matching**: Advanced VAT validation with trader details
- ✅ **All EU countries**: Support for all 27 EU member states plus Northern Ireland
- ✅ **Tested**: 100% test coverage with Pest PHP testing framework

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

[](#requirements)

- PHP 8.1 or higher
- SOAP extension (`ext-soap`) enabled

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

[](#installation)

Install the package via Composer:

```
composer require omisai/vies-soap
```

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

[](#quick-start)

### Basic VAT Validation

[](#basic-vat-validation)

```
use Omisai\ViesSoap\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)

For development and testing, use the VIES test service:

```
use Omisai\ViesSoap\ViesClient;
use Omisai\ViesSoap\ViesConfig;

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

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

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

[](#configuration)

### Environment Configuration

[](#environment-configuration)

```
use Omisai\ViesSoap\ViesConfig;

// Production environment (default)
$config = ViesConfig::production();

// Test environment
$config = ViesConfig::test();

// Custom WSDL URL
$config = new ViesConfig('https://custom-vies-service.com/service.wsdl');

// With SOAP options
$config = ViesConfig::production([
    'connection_timeout' => 30,
    'trace' => true,
    'cache_wsdl' => WSDL_CACHE_NONE,
]);
```

### SOAP Client Options

[](#soap-client-options)

You can pass additional SOAP client options to customize the HTTP requests:

```
use Omisai\ViesSoap\ViesClient;
use Omisai\ViesSoap\ViesConfig;

$options = [
    'connection_timeout' => 30,
    'trace' => true,
    'cache_wsdl' => WSDL_CACHE_BOTH,
    'user_agent' => 'MyApp/1.0',
    'proxy_host' => 'proxy.example.com',
    'proxy_port' => 8080,
];

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

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

[](#api-reference)

### ViesClient

[](#viesclient)

The main client class for interacting with VIES services.

#### Constructor

[](#constructor)

```
public function __construct(
    ViesConfig $config = new ViesConfig(),
    ?SoapClientFactoryInterface $clientFactory = null,
    ?VatNumberValidator $validator = null,
)
```

#### Methods

[](#methods)

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

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

Validates a VAT number and returns basic information.

**Parameters:**

- `$countryCode`: Two-letter EU country code (e.g., 'DE', 'FR', 'NL')
- `$vatNumber`: The VAT number to validate

**Returns:** `CheckVatResponse` object

**Example:**

```
$response = $client->checkVat('NL', '123456789B01');

echo "Country: {$response->countryCode}\n";
echo "VAT Number: {$response->vatNumber}\n";
echo "Valid: " . ($response->valid ? 'Yes' : 'No') . "\n";
echo "Request Date: {$response->requestDate->format('Y-m-d')}\n";
echo "Company Name: {$response->name}\n";
echo "Address: {$response->address}\n";
```

##### `checkVatApprox(CheckVatApproxRequest $request): CheckVatApproxResponse`

[](#checkvatapproxcheckvatapproxrequest-request-checkvatapproxresponse)

Performs approximate VAT validation with trader details for enhanced verification.

**Parameters:**

- `$request`: A `CheckVatApproxRequest` object with trader information

**Returns:** `CheckVatApproxResponse` object

**Example:**

```
use Omisai\ViesSoap\DTO\CheckVatApproxRequest;

$request = new CheckVatApproxRequest(
    countryCode: 'NL',
    vatNumber: '123456789B01',
    traderName: 'Example B.V.',
    traderStreet: 'Main Street 123',
    traderPostcode: '1234AB',
    traderCity: 'Amsterdam',
    requesterCountryCode: 'DE', // Optional: Your own VAT country
    requesterVatNumber: '123456789', // Optional: Your own VAT number
);

$response = $client->checkVatApprox($request);

echo "Valid: " . ($response->valid ? 'Yes' : 'No') . "\n";
echo "Request ID: {$response->requestIdentifier}\n";
echo "Name Match: {$response->traderNameMatch}\n";
echo "Address Match: {$response->traderStreetMatch}\n";
```

### Data Transfer Objects (DTOs)

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

#### CheckVatResponse

[](#checkvatresponse)

Contains the response from a basic VAT check.

**Properties:**

- `countryCode`: string - The validated country code
- `vatNumber`: string - The validated VAT number
- `requestDate`: DateTimeImmutable - When the request was made
- `valid`: bool - Whether the VAT number is valid
- `name`: ?string - Company name (if available)
- `address`: ?string - Company address (if available)

#### CheckVatApproxResponse

[](#checkvatapproxresponse)

Contains the response from an approximate VAT check with detailed matching information.

**Properties:**

- `countryCode`: string
- `vatNumber`: string
- `requestDate`: DateTimeImmutable
- `valid`: bool
- `traderName`: ?string
- `traderCompanyType`: ?string
- `traderAddress`: ?string
- `traderStreet`: ?string
- `traderPostcode`: ?string
- `traderCity`: ?string
- `traderNameMatch`: ?string - Match confidence for name
- `traderCompanyTypeMatch`: ?string - Match confidence for company type
- `traderStreetMatch`: ?string - Match confidence for street
- `traderPostcodeMatch`: ?string - Match confidence for postcode
- `traderCityMatch`: ?string - Match confidence for city
- `requestIdentifier`: string - Unique identifier for the request

#### CheckVatApproxRequest

[](#checkvatapproxrequest)

Request object for approximate VAT validation.

**Constructor parameters:**

- `countryCode`: string (required)
- `vatNumber`: string (required)
- `traderName`: ?string
- `traderCompanyType`: ?string
- `traderStreet`: ?string
- `traderPostcode`: ?string
- `traderCity`: ?string
- `requesterCountryCode`: ?string - Your country's code for the request
- `requesterVatNumber`: ?string - Your VAT number for the request

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

[](#supported-countries)

The package supports all current EU member states plus Northern Ireland (XI):

CodeCountryCodeCountryCodeCountryATAustriaELGreeceMTMaltaBEBelgiumESSpainNLNetherlandsBGBulgariaFIFinlandPLPolandCYCyprusFRFrancePTPortugalCZCzechiaHRCroatiaRORomaniaDEGermanyHUHungarySESwedenDKDenmarkIEIrelandSISloveniaEEEstoniaITItalySKSlovakiaLVLatviaXINorthern IrelandLTLithuaniaLULuxembourg### Country Code Validation

[](#country-code-validation)

```
use Omisai\ViesSoap\Enum\EuropeanUnionCountry;

// Check if a country code is valid
$isValid = EuropeanUnionCountry::isEuropeanUnionCountryCode('DE'); // true
$isValid = EuropeanUnionCountry::isEuropeanUnionCountryCode('US'); // false

// Get all supported countries
$countries = EuropeanUnionCountry::cases();
foreach ($countries as $country) {
    echo "{$country->name}: {$country->value}\n";
}
```

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

[](#error-handling)

The package provides structured exception handling for different error scenarios.

### Validation Errors

[](#validation-errors)

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

$client = new ViesClient();

try {
    $response = $client->checkVat('INVALID', '123');
} catch (ViesValidationException $e) {
    echo "Validation error: {$e->getMessage()}\n";
    // Handle invalid country code or VAT number format
}
```

### SOAP Service Errors

[](#soap-service-errors)

```
use Omisai\ViesSoap\Exceptions\ViesSoapException;
use Omisai\ViesSoap\ViesClient;

$client = new ViesClient();

try {
    $response = $client->checkVat('DE', '123456789');
} catch (ViesSoapException $e) {
    echo "SOAP error: {$e->getMessage()}\n";
    echo "Fault code: {$e->getFaultCode()}\n";
    echo "Fault string: {$e->getFaultString()}\n";
    // Handle service unavailability, invalid requests, etc.
}
```

### Common Exception Types

[](#common-exception-types)

- **`ViesValidationException`**: Invalid country code or VAT number format
- **`ViesSoapException`**: SOAP service errors (service unavailable, invalid requests, etc.)

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

[](#advanced-usage)

### Custom SOAP Client

[](#custom-soap-client)

You can inject custom SOAP client implementations for testing or advanced scenarios:

```
use Omisai\ViesSoap\ViesClient;
use Omisai\ViesSoap\Soap\SoapClientFactoryInterface;

class CustomSoapClientFactory implements SoapClientFactoryInterface
{
    // Implement your custom factory
}

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

### Custom Validation

[](#custom-validation)

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

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

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

### Batch Processing

[](#batch-processing)

```
use Omisai\ViesSoap\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
```

### Testing with Mock Data

[](#testing-with-mock-data)

The package includes test helpers for mocking SOAP responses:

```
use Omisai\ViesSoap\ViesClient;
use Tests\Support\FakeSoapClient;
use Tests\Support\FakeSoapClientFactory;

// Create a fake SOAP response
$soapResponse = (object) [
    'countryCode' => 'DE',
    'vatNumber' => '123456789',
    'requestDate' => '2024-01-01',
    'valid' => true,
    'name' => 'Test Company GmbH',
    'address' => 'Test Street 123, 12345 Test City',
];

$fakeClient = new FakeSoapClient($soapResponse);
$client = new ViesClient(
    clientFactory: new FakeSoapClientFactory($fakeClient)
);

$response = $client->checkVat('DE', '123456789');
// Response will contain the fake data
```

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

[](#performance-considerations)

- The VIES service has rate limits - avoid excessive requests
- SOAP 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
- SOAP extension must be enabled in PHP
- 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 SOAP API Documentation](https://ec.europa.eu/taxation_customs/vies/checkVatService.wsdl)
- [VIES Test Service](https://ec.europa.eu/taxation_customs/vies/checkVatTestService.wsdl)

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance83

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 98% 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 ~1 days

Total

4

Last Release

85d 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 (49 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

apiphpsdksoapviesapisdksoapvies

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

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

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

###  Alternatives

[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.

47073.9k5](/packages/deepseek-php-deepseek-php-client)[jstolpe/instagram-graph-api-php-sdk

Instagram Graph API PHP SDK

13998.4k2](/packages/jstolpe-instagram-graph-api-php-sdk)

PHPackages © 2026

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