How asamirsherif/zatca-integration works
Project type and purpose
• This is a Laravel-compatible PHP package (a composer library) whose purpose is to integrate with ZATCA API servers and generate TLV-encoded, signed QR codes for Saudi Arabia’s e-invoicing requirements.
• It is not a standalone full-stack app but a reusable package that plugs into a Laravel application via a ServiceProvider and Facade.
File structure
• Top-level files
• composer.json – package metadata, dependencies, PSR-4 autoload rules
• Readme.md – usage instructions
• LICENSE, .gitignore
• src/
• Facades/Zatca.php – Laravel Facade interface
• ZatcaServiceProvider.php – registers the service binding and facade alias
• Zatca.php – core service class that provides the TLV builder, API calls, and code generation
• Utilis/Tag.php – builds TLV tags
• Utilis/QrCodeOptions.php – DTO for QR code rendering options
• helpers.php – global helper functions (e.g., zatca(), qrCodeOptions() shortcuts)
Key insights from the README
• The flow: consumer calls Zatca facade → sets sellerName, VAT, timestamp, totals → calls toBase64() or toQrCode() → package generates TLV binary or renders a QR code with the given options.
• Laravel auto-discovery means no manual registration is normally needed.
Components and relationships
a. Main components
• Consuming Laravel Application (Client)
• Laravel Service Container
• ZatcaServiceProvider (binds Zatca class into the container)
• Zatca Facade (static interface to underlying service)
• Core Zatca Service (Asamirsherif\Zatca\Zatca)
• TLV Builder (Utilis\Tag)
• QR Code Generator (external library dependency, invoked inside Zatca)
• QrCodeOptions DTO
• External ZATCA API Endpoint (optional if phase-two implements real API calls)
b. Relationships and data flow
1. Client code invokes Zatca::sellerName(...)->…->toBase64()/toQrCode()
2. Facade routes the call through Laravel’s Service Container to the Zatca Service instance
3. Zatca Service uses Tag to assemble TLV segments in the correct sequence
4. For Base64: Zatca Service encodes TLV to Base64 and returns
5. For QR Code: Zatca Service calls QR library, passing in the TLV Base64 and QrCodeOptions parameters, then returns an image/svg or PNG
6. (Future) Zatca Service may also sign or POST data to the ZATCA API server and validate responses
c. Architectural patterns and principles
• Facade pattern: simplifies consumer interface
• Service Provider / IoC Container: decouples instantiation
• Single Responsibility: Tag handles TLV encoding, QrCodeOptions holds config, Zatca Service orchestrates processes
• Extensibility: hooks/helpers for adding options or swapping QR library
d. Technologies and libraries
• PHP 7+ / Composer for autoload and dependency management
• Laravel’s Service Container & Facades
• Endroid QR Code or similar underlying QR library (implicit)
• PSR-4 autoloading
Elements
• Facade → Service Container → Zatca Service
• Zatca Service → Tag (build TLV)
• Zatca Service → QR Library (render)
• (Optional) Zatca Service ↔ External API
• Host application in another
• External dependencies/services in a third