Laravel Zatca Laravel Package

Technical Evaluation

Architecture fit: corecave/laravel-zatca remains a useful Laravel-native integration adapter for ZATCA Phase 2 e-invoicing, not a compliance system of record. The v1.2.0 QR image feature reinforces that boundary: QR rendering is a presentation convenience, while the canonical ZATCA QR payload, XML/UBL generation, cryptographic stamping, CSID handling, and clearance/reporting remain regulated integration concerns. Keep the package behind an internal ZatcaGateway interface and treat generated QR images as derived artifacts from the stored ZATCA-compliant QR payload, not as the source of truth.

Integration feasibility: Feasibility is unchanged and slightly improved by the README rewrite and end-to-end example. The new qr_code_image and qr_code_svg attributes can reduce effort for embedding QR codes in emails, PDFs, and receipts. However, v1.2.0 introduces an additional Composer dependency, simplesoftwareio/simple-qrcode, so feasibility now includes dependency review, rendering-extension checks, and confirming whether QR image generation is optional or required. The documentation clarifications—production CSID does not require OTP and the VAT number format 3XXXXXXXXXX0003—are useful, but they should be verified against current ZATCA guidance before being treated as authoritative.

Technical risk: Core maturity risk remains: small adoption footprint, limited ecosystem validation, and regulated-domain correctness requirements. v1.2.0 does not appear to introduce breaking changes, but the new QR dependency expands the supply-chain surface and may bring image-rendering requirements or behavior differences across PNG/SVG generation. The highest-risk failure remains incorrect ZATCA QR payload generation or signing, not the visual rendering itself. Confirm that qr_code_image and qr_code_svg encode the correct ZATCA TLV/base64 payload and fail safely if the optional QR package is unavailable.

Key questions:

• Which ZATCA Phase 2 flows are supported: standard invoices, simplified invoices, credit/debit notes, clearance, reporting, compliance checks, and production CSID onboarding?
• Does it implement UBL 2.1 XML, cryptographic stamping, QR payload generation, CSR/CSID handling, and certificate renewal correctly per current ZATCA specifications?
• Does the v1.2.0 QR image feature render the ZATCA-compliant QR payload, or does it only render invoice data? Is the underlying QR payload stored and auditable independently of the image?
• Is simplesoftwareio/simple-qrcode optional? What PHP extensions or system libraries does it require, and does it affect Laravel/PHP version compatibility?
• Are qr_code_image and qr_code_svg safe for untrusted output contexts such as HTML emails and PDFs, including escaping and SVG sanitization?
• Which Laravel and PHP versions are supported, and are dependencies healthy, pinned, and audited?
• How are private keys, CSIDs, and tenant credentials stored, encrypted, and rotated?
• Does it provide idempotency, retry/backoff, queue support, and audit logging for submissions and responses?
• Is there test coverage against ZATCA sandbox responses, including rejection, timeout, and QR rendering cases?
• What is the support model and release cadence, and can we fork under MIT if maintenance stops?
• Does it handle multi-tenant SaaS isolation, or does it assume one company/one credential set?

Integration Approach

Stack fit: Best fit remains a Laravel application using Composer, queues, and centralized secrets management. Keep the package at the infrastructure boundary: domain services create invoice records, an internal service builds submission requests, the package handles ZATCA transport/signing/QR payload handling, and results are persisted as compliance artifacts. The new QR image attributes should be used in downstream presentation layers—email, PDF, receipt generation—without letting controllers couple checkout or ERP posting to QR rendering.

Migration path: Re-run the time-boxed sandbox spike against v1.2.0 if QR images are in scope. Validate representative invoices, Arabic content, VAT scenarios, credit/debit notes, and ZATCA sandbox credentials. Add contract tests for both the ZATCA QR payload and the optional PNG/SVG rendering output. For existing ZATCA processes, run the package in parallel in sandbox or pilot mode before cutover. Because adoption signals remain limited, assume greenfield integration and budget for missing production plumbing rather than relying on community patterns.

Compatibility: Confirm Laravel/PHP constraints, required PHP extensions, HTTP client behavior, database assumptions, queue driver, secret manager, logging/audit stack, and multi-tenant model. Specifically evaluate whether simplesoftwareio/simple-qrcode is required in production and whether it introduces GD/Imagick or SVG-related constraints. Pin the Composer version for both packages and record the exact commit/tag used; do not allow floating versions in production.

Sequencing:

1. Confirm ZATCA Phase 2 scope with tax/legal: invoice types, thresholds, clearance vs. reporting, Arabic requirements, QR payload requirements, retention, and audit obligations.
2. Run package provenance and security review for v1.2.0: Packagist ownership, repository history, release tags, dependency audit, license, and maintainer responsiveness. Include simplesoftwareio/simple-qrcode in the dependency review.
3. Execute the sandbox spike with representative invoices, failure cases, and QR image generation for PNG/SVG outputs.
4. Build internal adapter, credential storage, audit log, idempotency, retry, dead-letter handling, and QR artifact persistence.
5. Complete ZATCA sandbox/compliance validation and internal finance acceptance.
6. Pilot with a limited invoice stream or entity, then roll out by tenant/entity with rollback to manual or alternate provider.

Operational Impact

Maintenance: Expect to own more maintenance than the package’s adoption metrics suggest. Pin versions, monitor ZATCA specification changes, and maintain a fork contingency. Assign an engineer as package steward and document the adapter boundary so upgrades are isolated. v1.2.0 adds one more dependency to track: include simplesoftwareio/simple-qrcode in dependency review, security patching, and compatibility testing. The README rewrite is helpful but does not replace an internal runbook.

Support: Community support is likely thin given limited adoption signals. Do not rely on upstream for production incidents. Establish an internal escalation path covering Laravel, ZATCA API, cryptography/certificates, QR rendering, and finance/tax interpretation. If the package becomes critical, consider a lightweight vendor-risk review or maintainer contact before production. Treat documentation clarifications—production CSID OTP and VAT format—as inputs to validation, not as final compliance evidence.

Scaling: ZATCA submission is mostly I/O, XML processing, signing, and API rate-limit management rather than high-compute work. Scale with queued workers, bounded concurrency, per-tenant rate limits, and backoff. QR image generation is lightweight but should be cached or generated asynchronously for high-volume email/PDF workflows. Keep invoice generation, QR payload persistence, and submission separate from QR image rendering so presentation spikes do not block checkout.

Failure modes: Plan for XML/schema validation failures, signing and certificate errors, expired or misconfigured CSIDs, ZATCA API timeouts and outages, duplicate submissions, clearance/reporting rejections, queue backlog, secret misconfiguration, tenant credential leakage, incorrect QR payloads, QR image rendering failures, missing QR dependencies, and unsafe SVG output. Use idempotency keys, retry with backoff only for safe failures, dead-letter queues, alerting on rejection rates, and a manual reconciliation path. Certificate expiry, ZATCA spec changes, and dependency breakage are operational events that need calendar-based monitoring, not just application errors.

Ramp-up: The team needs both Laravel integration skills and ZATCA domain literacy. Budget for a sandbox spike, compliance validation, dependency review for the new QR package, and finance/legal review before production. A realistic ramp-up includes a short technical evaluation, a pilot implementation behind an adapter, and a controlled rollout by entity or tenant. v1.2.0 is a useful convenience release, but the TPM should continue to plan for certification, audit, QR correctness, and exception handling as first-class workstreams rather than assuming the package delivers compliance end to end.