Download the PHP package znojil/vies without Composer

Znojil VIES

A simple and modern PHP library for communicating with the VIES VAT number validation service of the European Commission.

Covers all endpoints of the VIES REST API, with typed DTOs, enums and full PHPStan level max coverage. No API key or registration is needed — VIES is a public service.

🚀 Installation

📖 Usage

1. Checking a VAT Number

The VAT number is passed without the country prefix — the country is a separate Country enum argument. To get there from what users type, see Parsing User Input.

Member states are free to withhold the name and address even for a valid number, so name and address are null whenever the service returns no value. Do not treat a missing name as an invalid number — valid is the answer.

The address is free text from the member state's register and its layout differs by member state. getAddressLines() splits it into lines without interpreting them:

To confirm individual address parts, use approximate matching instead of parsing the lines.

2. Parsing User Input

VatNumber::parse() turns a VAT number as people write it into the country and the national part the request expects. It removes spaces, dots and dashes, uppercases the input and splits off the country prefix. GR is accepted for Greece and converted to EL, the code VIES uses.

When the input has no prefix, pass the country. A prefix in the input must then match it, so a form expecting a Czech number rejects a Slovak one:

France is the exception: its numbers may themselves start with two letters, so for France only FR is treated as a prefix — parse('AT123456789', Country::France) gives FRAT123456789, not a mismatch with Austria.

InvalidArgumentException is thrown when the input has no prefix and no country is given, when the prefix is not a supported country (e.g. GB), when the prefix does not match the given country, or when the national part does not match the generic format VIES accepts — 2 to 12 letters, digits, + or *.

parse() does not apply any country specific rules: no length or check digit validation, no zero padding. A number that parses can still be invalid, and only VIES can tell. It works without a client, so it can also be used on its own, e.g. to normalize form input.

3. Approximate Matching

Supplying trader details asks VIES to compare them with the registered ones. To also get a requestIdentifier — the consultation number proving the check was made — supply your own VAT number as the requester:

Fields you do not submit come back as NotProcessed. Matching is advisory: member states differ in how strictly they compare, and Invalid does not by itself mean the VAT number is invalid.

4. Checking Service Status

Worth checking before a batch run — an unavailable member state cannot be validated no matter how many times you ask.

5. Testing Error Handling

VIES provides a test endpoint that returns canned responses, so error handling can be exercised without depending on a member state actually being down:

Each TestVatNumber case other than Valid and Invalid produces the error code of the same name. The responses are abridged — no trader data is returned — which the DTO handles.

6. Using a Custom HTTP Client

By default the library uses znojil/http. You can inject your own implementation as the first argument to the Client constructor. It must implement the Znojil\Vies\Http\Client interface.

$data is encoded according to the Content-Type header (JSON or form); an empty array or null means no content. String keys in $options are transport-agnostic options defined by this library — your implementation must honor them and reject any other string key with an exception. This library does not define any at the moment. Integer keys are raw CURLOPT_* constants — non-cURL implementations must reject them with an exception rather than silently ignore them, so that a consumer never ends up with options that silently don't apply.

⚠️ Error Handling

VIES reports most errors with HTTP status 200 and an error payload rather than with a 4xx/5xx status. The client detects those and throws an exception, so a successful send() always means a real answer.

The client throws exceptions to help you identify the issue:

• Znojil\Vies\Exception\ApiException: For errors VIES reports in the body of a successful response (e.g. MS_UNAVAILABLE). Contains the reported errors, each with a code and an optional message.
• Znojil\Vies\Exception\ClientException: For HTTP client-side errors (4xx). When the body carries an error payload, getPrevious() is an ApiException.
• Znojil\Vies\Exception\ServerException: For HTTP server-side errors (5xx). When the body carries an error payload, getPrevious() is an ApiException.
• Znojil\Vies\Exception\ResponseException: For other unsuccessful HTTP responses. The base class of the three above and of UnexpectedResponseException — it carries statusCode and the raw responseBody.
• Znojil\Vies\Exception\JsonException: When a response body is not valid JSON.
• Znojil\Vies\Exception\JsonResponseException: When a response body is valid JSON but not an object or array (subtype of UnexpectedResponseException).
• Znojil\Vies\Exception\UnexpectedResponseException: When a successful response body does not match the expected shape (e.g. an unknown enum value, a missing or mistyped field). The original error is available as getPrevious().
• Znojil\Vies\Exception\InvalidArgumentException: For invalid input (e.g. a VAT number VatNumber::parse() cannot handle).

All exceptions thrown by the library implement the Znojil\Vies\Exception\Exception marker interface, so a single catch can cover them all.

Error Codes

The REST contract does not list the error codes. These are the ones known from the VIES SOAP service definitions; the descriptions come from checkVatService.wsdl:

Other codes can appear, e.g. VOW-ERR-1 with HTTP 500 for a malformed request.

Fair Use

VIES is a free public service with no published rate limit, but it does throttle: GLOBAL_MAX_CONCURRENT_REQ and MS_MAX_CONCURRENT_REQ are returned when too many requests arrive at once. Validate sequentially, cache results, and back off when you receive these, MS_UNAVAILABLE or TIMEOUT.

📄 License

This library is open-source software licensed under the MIT license.