rocketfellows/country-vat-number-format-validator

维护者

详细信息

github.com/rocketfellows/country-vat-number-format-validator

源代码

问题

安装: 0

依赖: 0

建议: 0

安全: 0

星标: 0

关注者: 0

分支: 0

开放问题: 0

v1.0.0 2023-07-08 15:27 UTC

Requires

Requires (Dev)

MIT fbe0a96d739602d4f355f084c95b6f7fe35d2c16

  • Arslan Imamutdinov <ara.imamutdinov.woop@gmail.com>

This package is not auto-updated.

Last update: 2024-09-15 19:04:26 UTC

README

Code Coverage Badge

该软件包提供了用于验证国家增值税号码格式的可配置服务。

安装

composer require rocketfellows/country-vat-number-format-validator

依赖

参考

以下软件包可以直接连接到验证器，因为它们包含以下国家的预配置验证器：

验证国家增值税号格式的接口。

检查国家增值税号格式的服务：rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidatorService

检查国家增值税号格式是否正确的函数：rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidatorService::validateCountryVatNumber

输入参数

  • countryCode - 字符串 - ISO 3166标准的国家代码（可处理格式：alpha2，alpha3，数字代码）；
  • vatNumber - 字符串 - 增值税号；

可抛出异常

  • rocketfellows\CountryVatNumberFormatValidator\exceptions\CountryCodeEmptyException - 当 countryCode 是空字符串时；
  • rocketfellows\CountryVatNumberFormatValidator\exceptions\UnknownInputCountryCodeException - 当 CountryFactory 根据给定的 countryCode 找不到国家时；
  • rocketfellows\CountryVatNumberFormatValidator\exceptions\CountryValidatorsNotFoundException - 当服务未找到给定国家的验证器时；
  • rocketfellows\CountryVatNumberFormatValidator\exceptions\VatNumberValidatingException - 当找到的国家验证器在处理过程中抛出任何异常时；

返回值是 rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidationResult 的实例。

VatNumberFormatValidationResult 描述

  • createInvalidResult - 创建无效验证结果的静态工厂函数，返回 VatNumberFormatValidationResult 的实例；
  • createValidResult - 创建有效验证结果的静态工厂函数，返回 VatNumberFormatValidationResult 的实例；
  • isValid - 如果增值税号对给定国家有效，则返回 true，如果增值税号无效，则返回 false；
  • getPassedValidatorsClasses - 返回在验证过程中通过的类（字符串数组）；
  • getSuccessfullyValidatorClass - 如果增值税号对给定国家有效，则返回成功验证的验证器类；

预配置国家验证器的使用示例。

要使用预配置的国家验证器，您需要从上面的“参考”部分安装相应的包列表。

VatNumberFormatValidatorService 实例化的示例

$validatorService = new VatNumberFormatValidatorService(
    new CountryVatNumberFormatValidatorsConfigs(
        new SKVatNumberFormatValidatorsConfig(),
        new SIVatNumberFormatValidatorsConfig(),
        new SEVatNumberFormatValidatorsConfig(),
        new RUVatNumberFormatValidatorsConfig(),
        new ROVatNumberFormatValidatorsConfig(),
        new PTVatNumberFormatValidatorsConfig(),
        new PLVatNumberFormatValidatorsConfig(),
        new NOVatNumberFormatValidatorsConfig(),
        new NLVatNumberFormatValidatorsConfig(),
        new MTVatNumberFormatValidatorsConfig(),
        new LVVatNumberFormatValidatorsConfig(),
        new LUVatNumberFormatValidatorsConfig(),
        new LTVatNumberFormatValidatorsConfig(),
        new ITVatNumberFormatValidatorsConfig(),
        new IEVatNumberFormatValidatorsConfig(),
        new HUVatNumberFormatValidatorsConfig(),
        new HRVatNumberFormatValidatorsConfig(),
        new GRVatNumberFormatValidatorsConfig(),
        new GBVatNumberFormatValidatorsConfig(),
        new FRVatNumberFormatValidatorsConfig(),
        new FIVatNumberFormatValidatorsConfig(),
        new ESVatNumberFormatValidatorsConfig(),
        new EEVatNumberFormatValidatorsConfig(),
        new DKVatNumberFormatValidatorsConfig(),
        new DEVatNumberFormatValidatorsConfig(),
        new CZVatNumberFormatValidatorsConfig(),
        new CYVatNumberFormatValidatorsConfig(),
        new CHEVatNumberFormatValidatorsConfig(),
        new BGVatNumberFormatValidatorsConfig(),
        new BEVatNumberFormatValidatorsConfig(),
        new ATVatNumberFormatValidatorsConfig()
    ),
    new CountryFactory()
);

有效的国家增值税号格式示例。

奥地利增值税号。

// country code case-insensitive
$result = $validatorService->validateCountryVatNumber('at', 'ATU62181819');

var_dump($result);

验证结果

class rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidationResult#101 (3) {
  private $isValid =>
  bool(true)
  private $passedValidatorsClasses =>
  array(1) {
    [0] =>
    string(55) "rocketfellows\ATVatFormatValidator\ATVatFormatValidator"
  }
  private $successfullyValidatorClass =>
  string(55) "rocketfellows\ATVatFormatValidator\ATVatFormatValidator"
}

德国增值税号。

// country code case-insensitive
$result = $validatorService->validateCountryVatNumber('de', 'DE282308599');

var_dump($result);

验证结果

class rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidationResult#101 (3) {
  private $isValid =>
  bool(true)
  private $passedValidatorsClasses =>
  array(1) {
    [0] =>
    string(55) "rocketfellows\DEVatFormatValidator\DEVatFormatValidator"
  }
  private $successfullyValidatorClass =>
  string(55) "rocketfellows\DEVatFormatValidator\DEVatFormatValidator"
}

无效的国家增值税号格式示例。

奥地利增值税号。

// country code case-insensitive
$result = $validatorService->validateCountryVatNumber('at', 'foo');

var_dump($result);

验证结果

class rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidationResult#99 (3) {
  private $isValid =>
  bool(false)
  private $passedValidatorsClasses =>
  array(1) {
    [0] =>
    string(55) "rocketfellows\ATVatFormatValidator\ATVatFormatValidator"
  }
  private $successfullyValidatorClass =>
  NULL
}

德国增值税号。

// country code case-insensitive
$result = $validatorService->validateCountryVatNumber('de', 'foo');

var_dump($result);

验证结果

class rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidationResult#99 (3) {
  private $isValid =>
  bool(false)
  private $passedValidatorsClasses =>
  array(1) {
    [0] =>
    string(55) "rocketfellows\DEVatFormatValidator\DEVatFormatValidator"
  }
  private $successfullyValidatorClass =>
  NULL
}

VatNumberFormatValidator。

如果您不需要国家增值税号格式的验证过程细节，只想得到“增值税号是否有效”的答案，可以使用 rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidator。

类方法

  • isValid - 以国家代码和增值税号作为参数，返回布尔值。

VatNumberFormatValidator 需要一个类型为 VatNumberFormatValidatorService 的对象作为依赖项，您必须预先配置。

可抛出异常

  • rocketfellows\CountryVatNumberFormatValidator\exceptions\CountryCodeEmptyException - 当 countryCode 是空字符串时；
  • rocketfellows\CountryVatNumberFormatValidator\exceptions\UnknownInputCountryCodeException - 当 CountryFactory 根据给定的 countryCode 找不到国家时；
  • rocketfellows\CountryVatNumberFormatValidator\exceptions\CountryValidatorsNotFoundException - 当服务未找到给定国家的验证器时；
  • rocketfellows\CountryVatNumberFormatValidator\exceptions\VatNumberValidatingException - 当找到的国家验证器在处理过程中抛出任何异常时；

VatNumberFormatValidator 配置示例。

$validator = new VatNumberFormatValidator(
    new VatNumberFormatValidatorService(
        new CountryVatNumberFormatValidatorsConfigs(
            new SKVatNumberFormatValidatorsConfig(),
            new SIVatNumberFormatValidatorsConfig(),
            new SEVatNumberFormatValidatorsConfig(),
            new RUVatNumberFormatValidatorsConfig(),
            new ROVatNumberFormatValidatorsConfig(),
            new PTVatNumberFormatValidatorsConfig(),
            new PLVatNumberFormatValidatorsConfig(),
            new NOVatNumberFormatValidatorsConfig(),
            new NLVatNumberFormatValidatorsConfig(),
            new MTVatNumberFormatValidatorsConfig(),
            new LVVatNumberFormatValidatorsConfig(),
            new LUVatNumberFormatValidatorsConfig(),
            new LTVatNumberFormatValidatorsConfig(),
            new ITVatNumberFormatValidatorsConfig(),
            new IEVatNumberFormatValidatorsConfig(),
            new HUVatNumberFormatValidatorsConfig(),
            new HRVatNumberFormatValidatorsConfig(),
            new GRVatNumberFormatValidatorsConfig(),
            new GBVatNumberFormatValidatorsConfig(),
            new FRVatNumberFormatValidatorsConfig(),
            new FIVatNumberFormatValidatorsConfig(),
            new ESVatNumberFormatValidatorsConfig(),
            new EEVatNumberFormatValidatorsConfig(),
            new DKVatNumberFormatValidatorsConfig(),
            new DEVatNumberFormatValidatorsConfig(),
            new CZVatNumberFormatValidatorsConfig(),
            new CYVatNumberFormatValidatorsConfig(),
            new CHEVatNumberFormatValidatorsConfig(),
            new BGVatNumberFormatValidatorsConfig(),
            new BEVatNumberFormatValidatorsConfig(),
            new ATVatNumberFormatValidatorsConfig()
        ),
        new CountryFactory()
    )
);

VatNumberFormatValidator 使用示例。

奥地利有效增值税号验证

$result = $validator->isValid('at', 'ATU62181819');
var_dump($result);

验证结果

bool(true)

奥地利无效增值税号验证

$result = $validator->isValid('at', 'ATU61819');
var_dump($result);

验证结果

bool(false)

可扩展性。

如果您需要扩展要检查的增值税号的国家列表，您需要执行以下操作

  • 实现所需国家的增值税号验证器 - 一个实现 rocketfellows\CountryVatFormatValidatorInterface\CountryVatFormatValidatorInterface 接口的类；
  • 通过实现接口 rocketfellows\CountryVatNumberFormatValidatorsConfig\CountryVatNumberFormatValidatorsConfigInterface 的类将验证器与国家连接；
  • 将连接国家与验证器的配置连接到 rocketfellows\CountryVatNumberFormatValidatorsConfig\CountryVatNumberFormatValidatorsConfigs；

示例

假设我们需要为卡塔尔添加增值税号验证器。

首先，我们需要实现该国家的增值税号验证器 - 一个实现接口 rocketfellows\CountryVatFormatValidatorInterface\CountryVatFormatValidatorInterface 的类。

为了简化，我们假设有效的增值税号是一个只包含数字且由三个字符组成的字符串。

为了实现验证器接口，我们使用准备好的抽象类 rocketfellows\CountryVatFormatValidatorInterface\CountryVatFormatValidator。

验证器实现

namespace rocketfellows\CountryVatNumberFormatValidator\qa;

use rocketfellows\CountryVatFormatValidatorInterface\CountryVatFormatValidator;

class QAVatFormatValidator extends CountryVatFormatValidator
{
    private const VAT_NUMBER_PATTERN = '/^\d{3}$/';

    protected function isValidFormat(string $vatNumber): bool
    {
        return (bool) preg_match(self::VAT_NUMBER_PATTERN, $vatNumber);
    }
}

接下来，您需要通过配置器类将验证器与国家关联。该类必须实现 rocketfellows\CountryVatNumberFormatValidatorsConfig\CountryVatNumberFormatValidatorsConfigInterface。

配置类

namespace rocketfellows\CountryVatNumberFormatValidator\qa;

use arslanimamutdinov\ISOStandard3166\Country;
use arslanimamutdinov\ISOStandard3166\ISO3166;
use rocketfellows\CountryVatFormatValidatorInterface\CountryVatFormatValidatorInterface;
use rocketfellows\CountryVatFormatValidatorInterface\CountryVatFormatValidators;
use rocketfellows\CountryVatNumberFormatValidatorsConfig\CountryVatNumberFormatValidatorsConfigInterface;

class QAVatNumberFormatValidatorsConfig implements CountryVatNumberFormatValidatorsConfigInterface
{
    private $validators;
    
    public function __construct(CountryVatFormatValidatorInterface $validator)
    {
        $this->validators = new CountryVatFormatValidators($validator);
    }

    public function getCountry(): Country
    {
        return ISO3166::QA();
    }

    public function getValidators(): CountryVatFormatValidators
    {
        return $this->validators;
    }
}

几乎就绪了，我们只需要将新的配置连接到 rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidatorService 服务。

VatNumberFormatValidatorService 配置

$validatorService = new VatNumberFormatValidatorService(
    new CountryVatNumberFormatValidatorsConfigs(
        new QAVatNumberFormatValidatorsConfig(new QAVatFormatValidator()),
        new ATVatNumberFormatValidatorsConfig(),
        new DEVatNumberFormatValidatorsConfig()
    ),
    new CountryFactory()
);

如您所见，除了奥地利和德国的增值税号验证器之外，我们还包含了一个针对卡塔尔的验证器。

我们的示例中卡塔尔的有效增值税号示例

$result = $validatorService->validateCountryVatNumber('qa', '123');
var_dump($result);

结果

class rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidationResult#17 (3) {
  private $isValid =>
  bool(true)
  private $passedValidatorsClasses =>
  array(1) {
    [0] =>
    string(69) "rocketfellows\CountryVatNumberFormatValidator\qa\QAVatFormatValidator"
  }
  private $successfullyValidatorClass =>
  string(69) "rocketfellows\CountryVatNumberFormatValidator\qa\QAVatFormatValidator"
}

我们的示例中卡塔尔无效增值税号示例

$result = $validatorService->validateCountryVatNumber('qa', 'foo');
var_dump($result);

结果

class rocketfellows\CountryVatNumberFormatValidator\VatNumberFormatValidationResult#15 (3) {
  private $isValid =>
  bool(false)
  private $passedValidatorsClasses =>
  array(1) {
    [0] =>
    string(69) "rocketfellows\CountryVatNumberFormatValidator\qa\QAVatFormatValidator"
  }
  private $successfullyValidatorClass =>
  NULL
}

如您所见，它运行得很好。

贡献。

欢迎提交拉取请求。如果有重大更改，请先打开一个问题进行讨论。

请确保根据需要更新测试。