gewebe/sylius-vat-plugin

VAT number address field with validation, EU VAT rates plugin for Sylius

v2.0.0 2025-04-20 20:15 UTC

Requires

• php: ^8.2
• ext-soap: *
• ibericode/vat: ^2.0
• sylius/sylius: ~2.0.0

Requires (Dev)

• behat/behat: ^3.16
• dmore/behat-chrome-extension: ^1.4
• dmore/chrome-mink-driver: ^2.9
• friends-of-behat/mink: ^1.11
• friends-of-behat/mink-browserkit-driver: ^1.6
• friends-of-behat/mink-debug-extension: ^2.1
• friends-of-behat/mink-extension: ^2.7
• friends-of-behat/page-object-extension: ^0.3
• friends-of-behat/suite-settings-extension: ^1.1
• friends-of-behat/symfony-extension: ^2.6
• friends-of-behat/variadic-extension: ^1.6
• nyholm/psr7: ^1.8
• phpspec/phpspec: ^7.5
• phpstan/phpstan: ^1.12
• phpstan/phpstan-doctrine: ^1.3
• phpstan/phpstan-webmozart-assert: ^1.2
• phpunit/phpunit: ^10.5
• robertfausk/behat-panther-extension: ^1.1
• sylius-labs/coding-standard: ^4.4
• sylius-labs/suite-tags-extension: ~0.2
• sylius/sylius-rector: ^2.0
• symfony/browser-kit: ^6.4 || ^7.1
• symfony/debug-bundle: ^6.4 || ^7.1
• symfony/dotenv: ^6.4 || ^7.1
• symfony/flex: ^2.4
• symfony/http-client: ^6.4 || ^7.1
• symfony/intl: ^6.4 || ^7.1
• symfony/web-profiler-bundle: ^6.4 || ^7.1
• symfony/webpack-encore-bundle: ^2.2

MIT

• symfony
• vat
• e-commerce
• sylius
• sylius-plugin

README

Features

• Installer for EU VAT rates with countries and zones
• New fields for VAT number at Address and ShopBillingData entity
• Configure VAT number field requirement:
  • Optional / Required
  • Required if customer filled “Company” field
  • Required in selected countries
• Validate VAT number:
  • Format for selected country
  • Country is same as selected country
  • Validity using VIES API for EU VAT number
• Revalidate customers VAT numbers after a given time
• Placing an order without VAT in the EU, if
  • VAT number validation was successful
  • Customers taxation country is different from shop billing country

Installation

Download the plugin via composer

composer require gewebe/sylius-vat-plugin

Enable the plugin in bundles.php

# config/bundles.php

return [
    # ...
    
    Gewebe\SyliusVATPlugin\GewebeSyliusVATPlugin::class => ['all' => true],
];

Import the plugin configurations

# config/packages/_sylius.yaml

imports:
    # ...
       
    - { resource: '@GewebeSyliusVATPlugin/config/config.yaml'}

Configure taxation address

For EU VAT, the address for taxation should be set to the shipping address in the Sylius configuration.

# config/packages/_sylius.yaml

sylius_core:
    shipping_address_based_taxation: true

Copy templates

Copy customized templates to your templates directory (e.g templates/bundles/):

mkdir -p templates/bundles/SyliusAdminBundle/
cp -R vendor/gewebe/sylius-vat-plugin/templates/SyliusAdminBundle/* templates/bundles/SyliusAdminBundle/
mkdir -p templates/bundles/SyliusShopBundle/
cp -R vendor/gewebe/sylius-vat-plugin/templates/SyliusShopBundle/* templates/bundles/SyliusShopBundle/

Extend Address entity

# src/Entity/Addressing/Address.php

namespace App\Entity\Addressing;

use Doctrine\ORM\Mapping as ORM;
use Gewebe\SyliusVATPlugin\Entity\VatNumberAddressInterface;
use Gewebe\SyliusVATPlugin\Entity\VatNumberAwareTrait;
use Sylius\Component\Core\Model\Address as BaseAddress;

/**
 * @ORM\Entity
 * @ORM\Table(name="sylius_address")
 */
#[ORM\Entity]
#[ORM\Table(name: 'sylius_address')]
class Address extends BaseAddress implements VatNumberAddressInterface
{
    use VatNumberAwareTrait;

If you use yaml mapping add also:

# config/doctrine/Address.orm.yaml

App\Entity\Addressing\Address:
    type: entity
    table: sylius_address
    fields:
        vatNumber:
            type: string
            column: vat_number
            nullable: true
        vatValid:
            type: boolean
            column: vat_valid
        vatValidatedAt:
            type: datetime
            column: vat_validated_at
            nullable: true

Add or Extend ShopBillingData entity

# src/Entity/Channel/ShopBillingData.php

namespace App\Entity\Channel;

use Doctrine\ORM\Mapping as ORM;
use Gewebe\SyliusVATPlugin\Entity\ShopBillingDataVatNumberAwareTrait;
use Gewebe\SyliusVATPlugin\Entity\ShopBillingDataVatNumberInterface;
use Sylius\Component\Core\Model\ShopBillingData as BaseShopBillingData;

/**
 * @ORM\Entity
 * @ORM\Table(name="sylius_shop_billing_data")
 */
#[ORM\Entity]
#[ORM\Table(name: 'sylius_shop_billing_data')]
class ShopBillingData extends BaseShopBillingData implements ShopBillingDataVatNumberInterface
{
    use ShopBillingDataVatNumberAwareTrait;

If you use yaml mapping add also:

# config/doctrine/ShopBillingData.orm.yaml

App\Entity\Channel\ShopBillingData:
    type: entity
    table: sylius_shop_billing_data
    fields:
        vatNumber:
            type: string
            column: vat_number
            nullable: true

Override the resource for shop_billing_data in your sylius config:

# config/packages/_sylius.yaml

sylius_core:
    resources:
        shop_billing_data:
            classes:
                model: App\Entity\Channel\ShopBillingData

Update your database schema

bin/console doctrine:migrations:diff
bin/console doctrine:migrations:migrate

Usage

Install EU countries and VAT rates

# EU VAT on digital services (MOSS scheme)
bin/console vat:install:eu

# EU with French VAT (cross-border)
bin/console vat:install:eu FR

# EU with French VAT and passed threshold in Spain and Portugal (cross-border)
bin/console vat:install:eu FR -t ES,PT

# EU with French VAT included in price
bin/console vat:install:eu FR -i

# EU with German standard and reduced VAT categories
bin/console vat:install:eu DE -c standard,reduced

Validate customers VAT number

1. Create new order with VAT number at shipping address

2. Show VAT number and validation status at admin orders

Testing

Traditional

1. From the plugin root directory, run the following commands:

   $ composer install
   $ (cd tests/Application && yarn install)
   $ (cd tests/Application && yarn build)
   $ (cd tests/Application && APP_ENV=test bin/console assets:install public)
   
   $ (cd tests/Application && APP_ENV=test bin/console doctrine:database:create)
   $ (cd tests/Application && APP_ENV=test bin/console doctrine:schema:create)
   # Optionally load data fixtures
   $ (cd tests/Application && APP_ENV=test bin/console sylius:fixtures:load --no-interaction)

To be able to set up a plugin's database, remember to configure your database credentials in tests/Application/.env and tests/Application/.env.test.

1. Run your local server:

   symfony server:ca:install
   APP_ENV=test symfony server:start --dir=tests/Application/public --daemon

2. Open your browser and navigate to https://localhost:8000.

Docker

1. Execute make init to initialize the container and install the dependencies.

2. Execute make database-init to create the database and run migrations.

3. (Optional) Execute make load-fixtures to load the fixtures.

4. Your app is available at http://localhost.

Running plugin tests

• PHPUnit

  vendor/bin/phpunit

• PHPSpec

  vendor/bin/phpspec run

• Behat (non-JS scenarios)

  vendor/bin/behat --strict --tags="~@javascript&&~@mink:chromedriver"

• PHPStan - Static Analysis

  vendor/bin/phpstan analyse -c phpstan.neon -l max src/  

  • Coding Standard

    vendor/bin/ecs check