Madcoders Sylius E-Invoicing Plugin

Structured e-invoicing for Sylius 2: generates, stores and manages e-invoices for orders, with a pluggable submission port for external e-invoicing systems.

The core plugin is vendor-neutral and fully functional standalone - invoices are generated and kept locally. Government or platform integrations are separate adapter plugins that implement the submission port:

• madcoders/sylius-einvoicing-ksef-plugin - adapter for KSeF (Krajowy System e-Faktur), the Polish national e-invoicing system.

Features

• EInvoice resource linked to Sylius orders and channels, browsable in the admin panel
• Invoice number generation (replaceable EInvoiceNumberGeneratorInterface)
• Submission lifecycle as a Symfony Workflow state machine: new -> queued -> submitted -> accepted | rejected | failed (with requeue)
• EInvoiceSubmitterInterface port for external systems, NullSubmitter default
• SubmitEInvoiceProcessor orchestrating transition + submission + result handling

Requirements

	Version
PHP	^8.3
Sylius	^2.0
Symfony	^6.4 or ^7.x

Installation

composer require madcoders/sylius-einvoicing-plugin

1. Register the plugin in config/bundles.php (if not added by Flex):

   Madcoders\SyliusEinvoicingPlugin\MadcodersSyliusEinvoicingPlugin::class => ['all' => true],

2. Import the plugin configuration in config/packages/madcoders_sylius_einvoicing.yaml:

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

3. Import the admin routes in config/routes/madcoders_sylius_einvoicing.yaml:

   madcoders_sylius_einvoicing_admin:
       resource: "@MadcodersSyliusEinvoicingPlugin/config/routes/admin.yaml"

4. Update the database schema:

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

Usage

Create and submit an e-invoice for an order:

use Madcoders\SyliusEinvoicingPlugin\Factory\EInvoiceFactoryInterface;
use Madcoders\SyliusEinvoicingPlugin\Processor\SubmitEInvoiceProcessorInterface;

$eInvoice = $eInvoiceFactory->createForOrder($order);
$submitProcessor->process($eInvoice);
$entityManager->persist($eInvoice);
$entityManager->flush();

With no adapter installed the NullSubmitter accepts every invoice locally. To integrate an external system, implement EInvoiceSubmitterInterface and alias the madcoders_sylius_einvoicing.submitter service to your implementation - or install a ready-made adapter such as the KSeF plugin.

Development

Everything runs through Docker and Make - no host PHP required:

make init      # containers + dependencies + assets + database
make help      # list all commands

The test application (a full Sylius app embedding this plugin) is served at http://localhost once make init finishes (admin / admin at /admin after make load-fixtures).

Quality gates:

make static    # PHPStan + ECS
make phpunit   # PHPUnit suites
make behat     # Behat suites
make verify    # everything

Install the git hooks once: make install-hooks.

Multi-repo workspace

This is the main repository of the e-invoicing ecosystem. To check out and bootstrap the KSeF adapter next to it:

make init-workspace

See docs/workspace.md for the layout and the composer path-repository development flow.

Documentation

• docs/adr-log/ - architecture decision log (start here for the "why")
• ai/architecture.md - structural map of the plugin
• ai/coding-rules.md - conventions and quality gates
• AGENTS.md - orientation for AI agents and contributors
• docs/CONTRIBUTING.md - contribution guide

License

Licensed under the European Union Public Licence v1.2 (EUPL-1.2).