Points d’extension
Vavang Invoice est conçu pour être adapté via des contrats Symfony explicites avant d’envisager un fork. Cette page recense les points d’extension réellement câblés par le plugin aujourd’hui et les distingue des détails d’implémentation.
Modèle de stabilité
Considérez les interfaces et tags documentés ici comme la surface d’intégration supportée pour la version majeure courante. Une montée de version doit néanmoins rester couverte par vos tests d’intégration.
Les classes concrètes, signatures de constructeurs, listeners Doctrine et détails internes des entités ne sont pas des contrats d’extension sauf mention explicite. Préférez une interface, une décoration de service ou une implémentation taggée plutôt qu’un héritage depuis une classe concrète Vavang.
Contrats de services remplaçables ou décorables
Le bundle associe notamment ces interfaces à des implémentations par défaut :
SyliusInvoicePlugin\FacturX\FacturXGeneratorInterface— construit le document Factur-X à partir de la facture électronique et des octets du PDF source ;SyliusInvoicePlugin\Validation\ElectronicDocumentValidatorInterface— valide le XML structuré de facture électronique ;SyliusInvoicePlugin\Generation\ComplianceDocumentStoreInterface— recherche et persiste les documents de conformité ;SyliusInvoicePlugin\Seller\SellerCompanyProviderInterface— résout les données de la société vendeuse ;SyliusInvoicePlugin\Product\VariantProductNatureResolverInterface— résout la nature produit d’une variante Sylius.
D’autres alias internes existent dans le conteneur, mais leur présence ne transforme pas tous les détails d’implémentation en API de personnalisation recommandée. Commencez par les contrats documentés ici.
Points d’extension par collection
Trois familles plateforme sont enregistrées pour l’autoconfiguration Symfony par l’extension du bundle : les implémentations déclarées par l’application hôte reçoivent donc automatiquement leur tag lorsque l’autoconfiguration est activée :
PlatformConnectorInterface→sylius_invoice.platform_connector;PlatformSendOperationInterface→sylius_invoice.platform_send_operation;PlatformStatusPollingOperationInterface→sylius_invoice.platform_status_polling_operation.
Les familles suivantes sont elles aussi consommées via des iterators taggés, mais les règles _instanceof du bundle sont limitées à son propre fichier de services et ne taggent pas globalement les services déclarés par l’application hôte. Les implémentations du projet doivent donc être taggées explicitement :
ElectronicInvoiceBusinessRuleInterface→sylius_invoice.business_rule;TransmissionConnectorInterface→sylius_invoice.transmission_connector;PaymentReportingConnectorInterface→sylius_invoice.payment_reporting_connector;ProviderWebhookAuthenticatorInterface→sylius_invoice.webhook_authenticator;ProviderWebhookDecoderInterface→sylius_invoice.webhook_decoder.
Pour ces familles à tag explicite, déclarez le tag correspondant dans l’application hôte même lorsque l’autoconfiguration Symfony est activée. Cela évite de dépendre de règles _instanceof qui ne s’appliquent qu’aux services chargés par la configuration du plugin.
Événements et hooks UI
Le traitement initial de conformité publie SyliusInvoicePlugin\Invoice\InvoiceCreated sur sylius.event_bus. Le message transporte un SourceInvoiceReference et un ActionOrigin. Il s’agit d’un événement de bus de messages, pas d’un événement Symfony EventDispatcherInterface.
L’intégration admin expose aussi des noms de Sylius Twig Hooks. Préférez le remplacement d’une contribution de hook à la copie d’un template complet du plugin. Voir Événements et Templates.
Frontières de responsabilité explicites
Vavang Invoice n’expose aucune stratégie propre de numérotation. Le numéro vient de la facture source du Sylius InvoicingPlugin. Voir Numérotation.
Vavang ne rend pas non plus le PDF visuel d’origine de la facture. Les octets du PDF source sont fournis par Sylius InvoicingPlugin puis intégrés dans le résultat Factur-X. Voir Génération PDF.
Le stockage par défaut des documents de conformité repose sur Doctrine. Une interface permet une décoration ou un remplacement contrôlé, mais aucun switch S3/filesystem n’est fourni nativement. Voir Stockage et intégrité.
Avant d’étendre
- Préférez la configuration quand elle suffit.
- Préférez une implémentation taggée quand le plugin agrège volontairement plusieurs implémentations.
- Préférez la décoration pour observer ou enrichir un service unique existant.
- Ne remplacez une implémentation d’interface que si vous préservez ses invariants et disposez de tests d’intégration.
- Ne forkez que lorsque le besoin ne peut pas être exprimé via les contrats supportés.