How sulaman0/zacta-phase2 works
Project type and purpose
• This is a PHP library/package (with example front-end scripts) that implements Saudi Arabia ZATCA’s E-Invoicing phases.
• It provides modules to generate/ onboard EGS (E-Invoice Generation System) units, sign invoices, build UBL-compliant XML, produce QR codes, and call ZATCA’s external compliance APIs.
File structure
Top‐level:
• index.php, phase-1.php – example scripts (presentation layer)
• composer.json / composer.lock – dependency management, autoloader
• ZATCA/ – core PHP namespace:
– EGS.php – key generation, CSR, compliance certificate, signInvoice(), checkInvoiceCompliance()
– GenerateQrCode.php – QR payload builder
– API.php – encapsulates remote calls to ZATCA web services
– Tag.php + Tags/* – domain model for XML tags (InvoiceDate, TaxNumber, Seller, etc.)
– templates/ – PHP partials to render UBL/XML segments and signature wrappers
• assets/ – static files (CSS/JS/images) used by example pages
• docs/ + User_Manual_Developer_Portal_Manual_Version_3.pdf – specifications and user guidance
README for additional insights
• Supports EGS onboarding (x.509 CSIDs), cryptographic stamp generation, simplified tax invoice creation, signing, compliance checking.
• Depends on OpenSSL for ECDSA keypair & CSR generation; other modules are pure PHP and can run in lightweight environments (e.g., React Native).
• Examples run on PHP’s built-in server (php -S), demonstrating phases 1 & 2.
Main components & interactions
a. Presentation Layer (Examples)
• index.php, phase-1.php
• Loads Composer autoloader → instantiates ZATCA\EGS and invoice objects → triggers flows
• Outputs HTML + embedded QR code (using GenerateQrCode)
b. Application / Service Layer
• ZATCA\EGS
– generateNewKeysAndCSR() → calls OpenSSL CLI / PHP’s openssl extension
– issueComplianceCertificate() → uses API.php to call ZATCA’s compliance endpoint (SOAP/REST)
– signInvoice() →
· Builds XML via Tag classes + templates
· Applies XML digital signature (templates/ubl_signature*.php)
– checkInvoiceCompliance() → remote API call for compliance status
c. Domain Model
• ZATCA\Tag + ZATCA\Tags\*
– Represent each UBL XML element (InvoiceDate, TaxNumber, LegalMonetaryTotal, etc.)
– Provide typed getters/setters and render logic (XML fragments)
d. Template Engine
• ZATCA/templates/*.php
– Partial templates to assemble the final UBL 2.1 tax invoice XML
– Handle signature, signed properties, invoice lines, totals, billing references
e. Infrastructure Layer
• Composer autoloader / PHP runtime
• OpenSSL (system dependency)
• External ZATCA E-Invoicing web services (issuance & validation endpoints)
f. External / Consumer
• ZATCA web APIs (Compliance, Reporting)
• QR Reader Apps (mobile, to scan and validate base64 QR payload)
Architectural patterns & design principles
• Separation of concerns:
· Presentation (example scripts) vs. Service (EGS) vs. Domain (Tags) vs. Template (XML fragments).
• Modular, namespace-driven code organization (ZATCA\… classes).
• Thin API adapter (API.php) abstracts remote calls.
• Template-based XML generation to maintain UBL standard compliance.
• Dependency management via Composer.