README

以应有的方式处理与欧盟MOSS税/增值税规定相关的所有难题。可以与 Laravel 5 / Cashier 一起使用 — 或者 独立使用。

// Easy to use!
$countryCode = VatCalculator::getIPBasedCountry();
VatCalculator::calculate( 24.00, $countryCode );
VatCalculator::calculate( 24.00, $countryCode, $postalCode );
VatCalculator::calculate( 71.00, 'DE', '41352', $isCompany = true );
VatCalculator::getTaxRateForLocation( 'NL' );
// Check validity of a VAT number
VatCalculator::isValidVATNumber('NL123456789B01');

内容

安装
- 独立使用
用法
配置（可选）
更新日志
许可证

安装

要安装增值税计算器，只需运行

$ composer require mpociot/vat-calculator

独立使用

您也可以不使用Laravel来使用此软件包。只需创建增值税计算器的新实例并使用它。所有文档示例都使用Laravel 5 门面代码，因此请确保不要将这些方法当作静态方法来调用。

示例

use Mpociot\VatCalculator\VatCalculator;

$vatCalculator = new VatCalculator();
$vatCalculator->setBusinessCountryCode('DE');
$countryCode = $vatCalculator->getIPBasedCountry();
$grossPrice = $vatCalculator->calculate( 49.99, 'LU' );

用法

计算含税价格

要计算含税价格，请使用带有净价和国家代码参数的 calculate 方法。

$grossPrice = VatCalculator::calculate( 24.00, 'DE' );

第三个参数是客户的邮政编码。

作为第四个参数，您可以传递一个布尔值，指示客户是公司还是个人。如果客户是公司，您应该通过验证增值税号来检查，如果客户是公司，则返回净价。

$grossPrice = VatCalculator::calculate( 24.00, 'DE', '12345', $isCompany = true );

获取更多信息

在计算含税价格后，您可以从 VatCalculator 中提取更多信息。

$grossPrice = VatCalculator::calculate( 24.00, 'DE' ); // 28.56
$taxRate    = VatCalculator::getTaxRate(); // 0.19
$netPrice   = VatCalculator::getNetPrice(); // 24.00
$taxValue   = VatCalculator::getTaxValue(); // 4.56

验证欧盟增值税号

在验证客户的增值税号之前，您可以使用 shouldCollectVAT 方法检查是否需要收集该国家代码的增值税。

if (VatCalculator::shouldCollectVAT('DE')) {

}

要验证客户的增值税号，请使用 isValidVATNumber 方法。增值税号应采用VIES指定的格式。给定的增值税号将被截断，并将自动删除不相关的字符/空白。

此服务依赖于欧盟提供的第三方SOAP API。如果由于任何原因，此API不可用，则将抛出 VATCheckUnavailableException。

try {
	$validVAT = VatCalculator::isValidVATNumber('NL 123456789 B01');
} catch( VATCheckUnavailableException $e ){
	// Please handle me
}

获取欧盟增值税号详情

要获取增值税号的详细信息，请使用 getVATDetails 方法。增值税号应采用VIES指定的格式。给定的增值税号将被截断，并将自动删除不相关的字符/空白。

此服务依赖于欧盟提供的第三方SOAP API。如果由于任何原因，此API不可用，则将抛出 VATCheckUnavailableException。

try {
	$vat_details = VatCalculator::getVATDetails('NL 123456789 B01');
	print_r($vat_details);
	/* Outputs
	stdClass Object
	(
		[countryCode] => NL
		[vatNumber] => 123456789B01
		[requestDate] => 2017-04-06+02:00
		[valid] => false
		[name] => Name of the company
		[address] => Address of the company
	)
	*/
} catch( VATCheckUnavailableException $e ){
	// Please handle me
}

Laravel 验证器扩展

如果您想将增值税号验证直接包含在现有的表单请求/验证中，请使用 vat_number 验证规则。

示例

$rules = array(
    'first_name'  => 'required',
    'last_name'   => 'required',
    'company_vat' => 'vat_number'
);

$validator = Validator::make(Input::all(), $rules);

重要：验证器扩展在增值税ID检查SOAP API不可用时返回 false。

Cashier 集成

如果您想将此软件包与Laravel Cashier一起使用，您可以让可收费模型使用 BillableWithinTheEU 特性。因为此特性覆盖了 Billable 特性的 getTaxPercent 方法，所以我们必须明确告诉我们的模型这样做。

use Laravel\Cashier\Billable;
use Mpociot\VatCalculator\Traits\BillableWithinTheEU;
use Laravel\Cashier\Contracts\Billable as BillableContract;

class User extends Model implements BillableContract
{
    use Billable, BillableWithinTheEU {
        BillableWithinTheEU::taxPercentage insteadof Billable;
    }

    protected $dates = ['trial_ends_at', 'subscription_ends_at'];
}

通过使用 BillableWithinTheEU 特性，您的可收费模型有新的方法来设置可收费模型的税率。

一键设置所有内容

setTaxForCountry($countryCode, $company = false)

或者使用更易读的链式方法

useTaxFrom($countryCode) — 使用给定国家的税率
asIndividual() — 计费模式不是公司（默认）
asBusiness() — 计费模式是有效的公司

因此，在订阅客户之前设置正确的税率，请考虑以下工作流程

$user = User::find(1);

// For individuals use:
$user->useTaxFrom('NL');

// For business customers with a valid VAT ID, use:
$user->useTaxFrom('NL')->asBusiness();

$user->subscription('monthly')->create($creditCardToken);

获取用户的国家/地区IP

目前，您需要提供一个方式让用户选择他们的国家/地区——可能是一个下拉菜单——以便使用该国家/地区进行增值税计算。

此包包含一个小的辅助函数，尝试根据用户的IP查找用户的国家/地区。

$countryCode = VatCalculator::getIPBasedCountry();

$countryCode 将会是 false，如果服务不可用，或者国家/地区无法查找。否则，该变量包含两字母的国家/地区代码，可以用来预先填充用户的选择。

前端集成 — vat_calculator.js

哇——所以您知道如何使用这个类，构建了您的支付表单，现在……？嗯——您想向用户显示正确的价格，并希望它动态更新。所以，继续添加一些路由，编写一些JavaScript，很快您就可以开始运行了，对吧？

或者您使用内置路由和 vat_calculator.js 库。

VAT计算器JS库将自动

当所选国家/地区值更改时计算税费
自动验证VAT-IDs / VAT号码并用于计算
使用基于IP的国家/地区预先填充用户的国家/地区

JavaScript库不依赖于第三方框架。

为了使用JavaScript辅助函数，您需要首先发布包文件。继续输入

$ php artisan vendor:publish --provider="Mpociot\VatCalculator\VatCalculatorServiceProvider"

现在您在 public/js 文件夹中有一个名为 vat_calculator.js 的文件。

在您的支付表单中集成它

将发布的JavaScript文件添加到您的支付表单中。

<head>
  ...
<script type="text/javascript" src="/js/vat_calculator.js"></script>
</head>

默认情况下，VAT计算器JS脚本正在寻找一个ID为 payment-form 的表单。此表单需要有一个 data-amount 属性，指定用于税计算的金额（就像Stripe使用的那样）。

因此，当您要计算24.99 €的税费时，您的表单应该如下所示

<form method="post" id="payment-form" data-amount="2499">

接下来，您需要一个下拉菜单让用户选择他们的计费国家/地区。此选择字段需要 data-vat="country" 属性，这样VAT计算器JS就知道在哪里查找国家/地区代码。

由于还有一些特定区域或城市的增值税率例外，因此强烈建议添加一个输入字段来收集邮政编码。此字段需要 data-vat="postal-code" 属性。

最后但同样重要的是，要自动验证VAT号码 / VAT ID，您可以使用一个具有 data-vat="vat_number" 属性指定的输入字段。

因此，您的表单将如下所示

<form method="POST" id="payment-form" data-amount="2499">

        <div class="form-row">
            <label>
                <span>Country</span>
                <select data-vat="country">
                    <option value="US">United States</option>
                    <option value="GB">United Kingdom</option>
                    <option value="DE">Germany</option>
                    <option value="FR">France</option>
                    <option value="IT">Italy</option>
                    <option value="ES">Spain</option>
                    <option value="CA">Canada</option>
                    <option value="AU">Australia</option>
                </select>
            </label>
        </div>
        
        <div class="form-row">
            <label>
                <span>Postal Code</span>
                <input data-vat="postal-code"/>
            </label>
        </div>
        
        <div class="form-row">
            <label>
                <span>VAT Number</span>
                <input data-vat="vat-number"/>
            </label>
        </div>
</form>

额外字段

要显示实时税费计算，您可以使用 vat-subtotal、vat-taxrate、vat-taxes 和 vat-total 类在任何DOM元素上，VAT计算器JS将自动为您设置内HTML内容。

示例

<strong>Subtotal</strong>: € <span class="vat-subtotal"></span>
<strong>Tax rate</strong>: <span class="vat-taxrate"></span>%
<strong>Taxes</strong>: € <span class="vat-taxes"></span>
<strong>Total</strong>: € <span class="vat-total"></span>

表单属性

表单字段

为了计算正确的税费，您需要在支付表单中添加一些额外的输入字段。所有这些字段都需要 data-vat 属性。您至少需要包含 country。

高级用法

使用不同的表单选择器

使用 VATCalculator.init('#my-selector') 在不同的表单上初始化实时计算。

使用自定义格式化函数修改计算结果HTML

使用 VATCalculator.setCurrencyFormatter 使用不同的方法格式化计算结果以供HTML输出。此函数将接收计算结果作为参数。

示例

VATCalculator.setCurrencyFormatter(function(value){
    return value.toFixed(2) + ' €';
});

手动触发计算

调用 VATCalculator.calculate() 手动触发计算。例如，当您更改表单上的 data-amount 属性时。

预配置路由

为了让VAT Calculator JS正确运行，这些路由将被添加到您的应用程序中。如果您不想使用JavaScript库，当然可以在配置文件中禁用这些路由。

配置

默认情况下，VAT计算器已预定义所有欧盟增值税规则，因此它可以轻松更新，如果特定国家的规则发生变化。

如果您需要定义其他增值税率，可以通过发布配置并添加更多规则来实现。

配置文件还决定了您是否想使用VAT Calculator JS路由。

重要：请确保在配置文件中设置您的业务国家代码，以便在向本国商业客户销售时获得正确的增值税计算。

要发布配置文件，请运行vendor:publish命令

$ php artisan vendor:publish --provider="Mpociot\VatCalculator\VatCalculatorServiceProvider"

这将创建一个位于您的配置目录中的vat_calculator.php文件。

更新日志

有关更多信息，请参阅变更日志。

许可证

此库采用MIT许可证。有关更多信息，请参阅许可证文件。

viddyoze-engineering / vat-calculator

维护者

详细信息