Download the PHP package omisai/vies-soap without Composer

PHP 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

• ✅ 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

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

Installation

Install the package via Composer:

Quick Start

Basic VAT Validation

Using the Test Service

For development and testing, use the VIES test service:

Configuration

Environment Configuration

SOAP Client Options

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

API Reference

ViesClient

The main client class for interacting with VIES services.

Constructor

Methods

checkVat(string $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:

checkVatApprox(CheckVatApproxRequest $request): CheckVatApproxResponse

Performs approximate VAT validation with trader details for enhanced verification.

Parameters:

• $request: A CheckVatApproxRequest object with trader information

Returns: CheckVatApproxResponse object

Example:

Data Transfer Objects (DTOs)

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

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

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

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

Country Code Validation

Error Handling

The package provides structured exception handling for different error scenarios.

Validation Errors

SOAP Service Errors

Common Exception Types

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

Advanced Usage

Custom SOAP Client

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

Custom Validation

Batch Processing

Testing

Run the test suite using Pest:

Testing with Mock Data

The package includes test helpers for mocking SOAP responses:

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

• 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

Please see CONTRIBUTING.md for details on how to contribute to this project.

Security

Please see SECURITY.md for details on reporting security vulnerabilities.

License

This package is open-sourced software licensed under the MIT license.

Sponsoring

If you find this package useful, please consider sponsoring the development: Sponsoring on GitHub

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

Official VIES Documentation

• European Commission VIES Website
• VIES SOAP API Documentation
• VIES Test Service