How saleh7/php-zatca-xml works
Main Components
• Certificate Module – This module is in charge of generating certificate signing requests and handling compliance certificates. It is represented by classes like CertificateBuilder (in src), Certificate helper (in src/Helpers/Certificate), and exception classes in src/Exceptions.
• Invoice Generation Module – Contains all classes needed to create an invoice. This includes Invoice, InvoiceLine, and their related mappers (in src/Mappers) plus validators and helpers (e.g., InvoiceSignatureBuilder, InvoiceSigner in src/Helpers). The GeneratorInvoice is responsible for creating the raw XML.
• Digital Signing Module – Handles the task of digitally signing the generated invoice XML. The InvoiceSigner and accompanying certificate classes integrate with the Certificate module to apply the digital signature.
• API Communication Module – Encapsulated by the ZatcaAPI class (in src) and its associated API result classes (in src/Api), this module manages the communication with the external ZATCA servers (submitting CSR and signed invoices).
• XML & Storage Module – This module takes care of reading & writing files (see Storage class in src) and deals with saving or loading invoice XML, certificates, and output files.
• Utilities & Helpers – Contains supplementary functions such as the QRCodeGenerator (in src/Helpers) and additional functions for invoice extensions or document mapping.
Relationships and Interactions
• The Certificate Module generates a CSR and private key which, after external approval via the API module, becomes a compliance certificate.
• The Invoice Generation Module builds an invoice object from various components (invoice header, lines, taxes, payment means, seller/customer details, etc.). Once built, it is transformed into an XML format using the GeneratorInvoice.
• Before invoice submission, the Digital Signing Module uses the certificate information to sign the generated XML.
• The API Communication Module then uses the signed XML to interact with ZATCA’s servers (for final invoice submission) and to request the compliance certificate after CSR generation. There is also data persistence via the Storage module.
• Utilities such as QR code generation and invoice mapping/validation are tied to both certificate and invoice modules to ensure the data is compliant and ready for transmission.
Important Architectural Patterns and Design Principles
• Modularization: The project cleanly separates responsibilities into certificate, invoice generation, digital signing, and API communication. This modular design promotes easy maintenance and extensibility.
• Builder Pattern: Used in the CertificateBuilder and in constructing the invoice (evidenced by fluent methods configuring various parameters).
• Facade Pattern: The library provides high-level functions that abstract away the internal complexities (for example, the facade provided by InvoiceSigner::signInvoice).
• Separation of Concerns: Test cases and examples further confirm the aim for clear boundaries between various components (for instance, tests for mappers and signature builder).
Relevant Technologies and Frameworks
• PHP 8.1+ and Composer for dependency management.
• PHP extensions like DOM, libxml, openssl, etc., are critical for XML processing, digital signing, and certificate generation.
• The project uses unit test frameworks for testing (as seen in the tests directory).