README

一个用于验证和标准化增值税号码的PHP库

本项目提供了一个库，用于检查和标准化增值税号码（包括查询欧洲国家的VIES VoW（增值税信息交换系统 - 网上增值税信息交换服务））。

要求

VATLib有以下要求

• 它从PHP 5.5版本开始工作（完全支持PHP 5.5.x、5.6.x、7.x和 8.x）。
• 非常灵活的在线服务查询依赖关系，如VIES
  • 不需要SOAP扩展
  • 库会自动使用这些适配器（你只需要一个，而不是全部）
    • Guzzle库
    • PHP cURL扩展
    • Zend HTTP库
    • PHP http流包装器
• 检查某些国家（荷兰和斯洛伐克）的增值税号码的语法需要处理大数字：在32位系统上，你可能需要 bcmath 或 gmp PHP扩展。

安装

手动安装

下载最新版本，解压并添加以下行到我们的PHP文件中

require_once 'path/to/vatlib/vat-lib.php';

使用Composer安装

只需运行

composer require mlocati/vat-lib

或将以下行添加到您的composer.json文件中

"require": {
    "mlocati/vat-lib": "^1"
}

检查和标准化增值税号码

您可以使用VATLib\Checker类来验证和标准化增值税号码。

您可以通过以下方式获得其实例

$checker = new \VATLib\Checker();

然后您可以使用其check方法。此方法接受一到两个参数：第一个参数是要检查的增值税号码，第二个参数（可选）是与该增值税号码关联的国家的ISO 3166 alpha-2代码。

一些示例（它们会产生相同的有效结果）

$checkResult = $checker->check('IT00159560366');
$checkResult = $checker->check('00159560366', 'IT');
$checkResult = $checker->check('IT00159560366', 'IT');
$checkResult = $checker->check('IT 00159560366');
$checkResult = $checker->check('IT 001-595-603-66');
$checkResult = $checker->check('00.15-95 603  66', 'IT');

验证有效性

$checkResult提供了isSyntaxValid()方法，它返回

• 如果增值税号码在语法上有效，则返回true
• 如果增值税号码在语法上无效，则返回false
• 如果无法验证增值税号码在语法上是否有效，则返回null。此情况的一些示例包括
  • 你提供了一个不受支持（或无效）的国家代码
  • 你没有提供国家代码，并且无法确定提供的增值税号码所关联的国家（例如，如果你调用$checker->check('00159560366')）

当增值税号码在语法上有效时，库也会查询欧盟国家的VIES服务。

您可以使用以下代码检查VIES响应

$viesCheck = $checker->getViesResult();
if ($viesCheck === null) {
    // The VIES service has not been queried, or an error occurred while querying the VIES service.
} elseif ($viesCheck->isValid() === true) {
    // The VIES service told us that the VAT number is valid
} elseif ($viesCheck->isValid() === false) {
    // The VIES service told us that the VAT number is NOT valid
    // That is, even if the VAT number is syntactically valid, it's not actually valid.
}

$checkResult提供了一个快速的方法来检查isSyntaxValid()和VIES的结果：您可以使用其isValid()方法，它返回

• 如果增值税号码在语法上有效，并且VIES未查询或其响应成功，则返回true
• 如果增值税号在语法上无效，或者VIES服务告知其无效，则返回false
• 如果无法验证增值税号的有效性，则返回null

获取格式化后的增值税号

要获取规范化的增值税号，您可以使用$checkResult类的getShortVatNumber()或getLongVatNumber()方法

$checkResult = $checker->check('IT 00-15 956.0366');
echo $checkResult->getShortVatNumber();
// prints 00159560366
echo $checkResult->getLongVatNumber();
// prints IT00159560366

获取增值税号信息

您可以获取有关增值税号的一些详细信息

$checker = new \VATLib\Checker();
$checkResult = $checker->check('EL999080536');
$format = $checkResult->getFormat();
if ($format === null) {
    echo 'The VAT number is not valid';
} else {
    echo "The VAT number is for the country with ISO 3166 alpha-2 code {$format->getCountryCode()}";
}

上述代码将打印

The VAT number is for the country with ISO 3166 alpha-2 code GR

检查错误

在检查增值税号时可能发生意外问题（例如，因为VIES服务暂时不可用）。

您可以使用$checkResult的hasExceptions方法来检查是否发生了错误

if ($checkResult->hasExceptions()) {
    echo "The following errors occurred:\n";
    foreach ($checkResult->getExceptions() as $exception) {
        echo "- {$exception->getMessage()}\n";
    }
}

根据增值税号检测可能的的国家

如果您有一个通用的增值税号，并且想了解它可能在哪些国家定义，您可以使用VATLib\Checker类的getApplicableFormats()方法

$checker = new \VATLib\Checker();
$formats = $checker->getApplicableFormats('00159560366');
if ($formats === []) {
    echo 'The VAT number is not valid';
} else {
    echo "The VAT number may be used in these countries:\n";
    foreach ($formats as $format) {
        echo "- {$format->getCountryCode()}\n";
    }
}

上述代码将打印

The VAT number may be used in these countries:
- FR
- HR
- IT
- LV

检查VIES服务的状态

$viesClient = new \VATLib\Vies\Client();
$status = $viesClient->checkStatus();
if ($status->getVowStatus()->isAvailable()) {
    echo "The Vies-on-the-web service is available\n";
} else {
    echo "The Vies-on-the-web service is NOT available\n";
}

$countryCodes = $status->getCountryCodes();
echo 'Vies supports these countries: ', implode(', ', $countryCodes), "\n";
// Sample outout: AT, BE, BG, CY, CZ, DE, DK, EE, EL, ES, FI, FR, HR, HU, IE, IT, LT, LU, LV, MT, NL, PL, PT, RO, SE, SI, SK, XI

$countryStatus = $status->getCountryStatus('IT');
if ($countryStatus->isAvailable()) {
    echo "Italian VAT validation is available\n";
} else {
    echo "Italian VAT validation is NOT available (", $countryStatus->getAvailability(), ")\n";
}

手动查询VIES

您还可以直接查询VIES

$viesClient = new \VATLib\Vies\Client();
$request = new \VATLib\Vies\CheckVat\Request('IT', '00159560366');
$response = $viesClient->checkVatNumber($request);
if ($response->isValid()) {
    echo "The VAT number {$request->getCountryCode()}{$request->getVatNumber()} is correct: it's assigned to the '{$response->getName()}' company\n";
} else {
    echo "The VAT number {$request->getCountryCode()}{$request->getVatNumber()} is NOT correct\n";
}

上述代码可能输出

The VAT number IT00159560366 is correct: it's assigned to the 'FERRARI S.P.A.' company

自定义VIES的HTTP适配器

默认情况下，VATLib会自动检测可用的适配器，但当然您可以指定自己的。

例如，如果您正在使用Guzzle并且需要配置代理，您可以编写如下代码

$guzzle = new \GuzzleHttp\Client([
    'proxy' => 'tcp://username:password@192.168.16.1:10',
]);
$adapter = new \VATLib\Http\Adapter\Guzzle($guzzle);
$viesClient = new \VATLib\Vies\Client($adapter);
$checker = new \VATLib\Checker();
$checker->setViesClient($viesClient);

同样，可以使用cURL PHP扩展来实现

$adapter = new \VATLib\Http\Adapter\Curl([
    CURLOPT_PROXY => 'tcp://username:password@192.168.16.1:10',
]);
// ... same previous example

同样，可以使用http流包装器来实现

$adapter = new \VATLib\Http\Adapter\Stream([
    'proxy' => 'tcp://username:password@192.168.16.1:10',
    'request_fulluri' => true,
]);
// ... same previous example

支持的国家

该库支持以下国家

• 所有欧盟国家
  • 奥地利（AT）
  • 比利时（BE）
  • 保加利亚（BG）
  • 克罗地亚（HR）
  • 塞浦路斯（CY）
  • 捷克（CZ）
  • 丹麦（DK）
  • 爱沙尼亚（EE）
  • 芬兰（FI）
  • 法国（FR）
  • 德国（DE）
  • 希腊（GR国家代码，增值税号以EL开头）
  • 匈牙利（HU）
  • 爱尔兰（IE）
  • 意大利（IT）
  • 拉脱维亚（LV）
  • 立陶宛（LT）
  • 卢森堡（LU）
  • 马耳他（MT）
  • 荷兰（NL）
  • 波兰（PL）
  • 葡萄牙（PT）
  • 罗马尼亚（RO）
  • 斯洛伐克（SK）
  • 斯洛文尼亚（SI）
  • 西班牙（ES）
  • 瑞典（SE）
• 瑞士（既有CHE-123.456.789也有123.456.789 UID号码）
• 英国（GB），具有以下扩展
  • 对于以XI开头的增值税号，VIES服务将根据爱尔兰和北爱尔兰协议进行查询
• MOSS增值税号（EU）