Italian Invoiceable Order Plugin

Sylius plugin which allows Italian merchants to collect invoice data for their orders such as tax code, VAT number, SDI code, etc... as well as allowing the merchant to only apply taxes to those customers that can (and must) pay taxes in advance.

Installation

0. This plugin requires the MyOnlineStore/ViesBundle but this is not actually compatible with Symfony 7, there is an open PR: MyOnlineStore/ViesBundle#18

   Thus, you have to run the following command to require a fork of the bundle which is compatible with Symfony 7:

   composer config repositories.sandwich/vies-bundle git https://github.com/mmenozzi/ViesBundle.git

   and you have to run this command too to allow "dev" versions of the bundle (we need the "dev-patch-1" version):

   composer config minimum-stability dev

1. Require the plugin:

   composer require webgriffe/sylius-italian-invoiceable-order-plugin

2. If they have not been added automatically, you have to add these bundles to config/bundles.php file:

       Sandwich\ViesBundle\SandwichViesBundle::class => ['all' => true],
       Webgriffe\SyliusItalianInvoiceableOrderPlugin\WebgriffeSyliusItalianInvoiceableOrderPlugin::class => ['all' => true],

3. Configure your ActiveCampaign API connection parameters by creating the config/packages/webgriffe_sylius_italian_invoiceable_order_plugin.yaml file with the following content:

   imports:
       - { resource: "@WebgriffeSyliusItalianInvoiceableOrderPlugin/config/config.yaml" }

4. By default, the parameter app.taxation.eu_zone_code is set to "EU", as it must be the code of a zone representing the EU. This is used to determine if an order is invoiced to a company within the EU or not. Please change this parameter according to your Sylius's zone configuration if needed:

   # config/services.yaml
   parameters:
       app.taxation.eu_zone_code: 'EU' # Change it if needed

5. Your Address entity must implement the Webgriffe\SyliusItalianInvoiceableOrderPlugin\Model\ItalianInvoiceableAddressInterface and the Symfony\Component\Validator\GroupSequenceProviderInterface. You can use the Webgriffe\SyliusItalianInvoiceableOrderPlugin\Model\ItalianInvoiceableAddressTrait as implementation for both interfaces.

6. Your Order entity must implement the Webgriffe\SyliusItalianInvoiceableOrderPlugin\Model\ItalianInvoiceableOrderInterface. You can use the Webgriffe\SyliusItalianInvoiceableOrderPlugin\Model\ItalianInvoiceableOrderTrait as default implementation for the interface.

7. You need to import the Address and Order validator configuration into your project by copying the configuration files provided by this plugin:

   mkdir -p config/validator/
   cp vendor/webgriffe/sylius-italian-invoiceable-order-plugin/tests/TestApplication/config/validation/Address.xml config/validator/
   cp vendor/webgriffe/sylius-italian-invoiceable-order-plugin/tests/TestApplication/config/validation/Order.xml config/validator/

   WAIT! We are not done with this step yet. You must edit these files to change the namespace Tests\Webgriffe\SyliusItalianInvoiceableOrderPlugin to your own project namespace: there are 3 references that you have to change among these files.

   If you have the "App" as the base namespace of your app, this command should be enough:

   Linux:

   sed -i 's/Tests\\Webgriffe\\SyliusItalianInvoiceableOrderPlugin/App/g' config/validator/Address.xml config/validator/Order.xml

   MacOS:

   sed -i '' 's/Tests\\Webgriffe\\SyliusItalianInvoiceableOrderPlugin/App/g' config/validator/Address.xml config/validator/Order.xml

   If you alread have some validator file for these entities you have to merge the configuration manually.

8. Configure Sylius to use the Italian tax calculation tax calculation strategy.

9. To properly enable group sequence validation of your Address entity you must set the Default validation group instead of the sylius validation group:

   # config/parameters.yaml
   parameters:
       # ...
       sylius.form.type.address.validation_groups: ['Default']

   For more information see here.

10. Run migration

    bin/console cache:clear
    bin/console doctrine:migrations:migrate

11. Add invoiceable fields to the address show template for admin. To do so you have to override this template:

    vendor/sylius/sylius/src/Sylius/Bundle/AdminBundle/templates/shared/helper/address.html.twig

    by copying directly our implementation provided in the plugin:

    mkdir -p templates/bundles/SyliusAdminBundle/shared/helper/
    cp vendor/webgriffe/sylius-italian-invoiceable-order-plugin/tests/TestApplication/templates/bundles/SyliusAdminBundle/shared/helper/address.html.twig templates/bundles/SyliusAdminBundle/shared/helper/address.html.twig

    or by copying the original template and adding the invoiceable fields by yourself. In this case your template should look like the following:

    {% macro address(address) %}
        <address>
            {% include '@WebgriffeSyliusItalianInvoiceableOrderPlugin/shared/address/billingAddressInfo.html.twig' with { address } only %}
            {{ address.phoneNumber }}<br/>
            {{ address.street }}<br/>
            {{ address.city }}<br/>
            {% if address|sylius_province_name is not empty %}
                {{ address|sylius_province_name }}<br/>
            {% endif %}
            {{ address.countryCode|sylius_country_name|upper }} {{ address.postcode }}
        </address>
    {% endmacro %}

Features

Once installed this plugin will allow the users of the shop to enter all the invoicing information needed by an Italian company to properly invoice the order. In addition, this plugin checks the billing data of the order and uses them to decide whether the customer has to pay taxes or not.

This plugin will add the following fields to your address form:

• Billing recipient type, which allows the user to specify if the billing address is for a company or for an individual. This field will be required for every address used as the billing address for an order.
• Tax code, which in Italy is known as "Codice Fiscale". It's, more or less, like the social security number (SSN) in the US but in Italy both companies and individuals have a tax code. This field will be required for Italian individuals and companies and validated according the proper checksum algorithm.
• VAT Number, which in Italy is known as "Partita IVA". It's another identification number but for companies only not only in Italy but also in the EU. This field will be required for Italian companies and validated according the proper checksum algorithm. This field will be also required for EU companies and validated using the EU's VIES service using the MyOnlineStore/ViesBundle.
• SDI Code, where SDI stands for "Sistema Di Interscambio". It's a code that is needed to be able to properly generate an "electronic invoice" which is mandatory in Italy since January the 1st of 2019. This field will be required for Italian companies and validated according the proper rules of the Italian IRS (called "Agenzia delle Entrate" in Italy).
• PEC address, where PEC stands for "Posta Elettronica Certificata" (the Italian translation of "certified email"). It's like an email address but for a special email type meant to provide a legal equivalent of the traditional mail. See here for more information. This field will not be required even for Italian companies, but if entered it must be a valid email address.

This plugin will also require the Sylius's company field to be populated if the billing recipient type is set to company.

This plugin also replaces the Sylius's Sylius\Component\Addressing\Comparator\AddressComparatorInterface implementation by decorating it and by comparing also invoiceable fields. So different invoiceable address information provided during checkout are saved in the customer address book as new addresses.

This plugin also allows to select an invoiceable address from the address book in the checkout and properly fill the address form with all the invoicing information.

Contributing

To contribute you need to:

1. Clone this repository into you development environment and go to the plugin's root directory,

2. Then, from the plugin's root directory, run the following commands:

   composer install

3. Copy tests/TestApplication/.env in tests/TestApplication/.env.local and set configuration specific for your development environment.

4. Link node_modules:

   ln -s vendor/sylius/test-application/node_modules node_modules

5. Run docker (create a compose.override.yml if you need to customize services):

   docker-compose up -d

6. Then, from the plugin's root directory, run the following commands:

   composer test-app-init

7. Run your local server:

   symfony server:ca:install
   symfony server:start -d

8. Now at http://localhost:8080/ you have a full Sylius testing application which runs the plugin

Testing

After your changes you must ensure that the tests are still passing.

First setup your test database:

    APP_ENV=test vendor/bin/console doctrine:database:create
    APP_ENV=test vendor/bin/console doctrine:migrations:migrate -n
    # Optionally load data fixtures
    APP_ENV=test vendor/bin/console sylius:fixtures:load -n

And build assets:

    (cd vendor/sylius/test-application && yarn install)
    (cd vendor/sylius/test-application && yarn build)
    vendor/bin/console assets:install

The current CI suite runs the following tests:

• PHPUnit

  vendor/bin/phpunit

• PHPSpec

  vendor/bin/phpspec run

• Behat (non-JS scenarios)

  vendor/bin/behat --strict --tags="~@javascript"

• Behat (JS scenarios)

  1. Install Symfony CLI command.

  2. Start Headless Chrome:

  google-chrome-stable --enable-automation --disable-background-networking --no-default-browser-check --no-first-run --disable-popup-blocking --disable-default-apps --allow-insecure-localhost --disable-translate --disable-extensions --no-sandbox --enable-features=Metal --headless --remote-debugging-port=9222 --window-size=2880,1800 --proxy-server='direct://' --proxy-bypass-list='*' http://127.0.0.1

  3. Install SSL certificates (only once needed) and run test application's webserver on 127.0.0.1:8080:

  symfony server:ca:install
  APP_ENV=test symfony server:start --port=8080 --dir=tests/TestApplication/public --daemon

  4. Run Behat:

  vendor/bin/behat --strict --tags="@javascript"

• Static Analysis

  • Psalm

    vendor/bin/psalm

  • PHPStan

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

• Coding Standard

  vendor/bin/ecs check src

License

This library is under the MIT license. See the complete license in the LICENSE file.

Credits

Developed by Webgriffe®.