codingtriplets / laravel-zatca
ZATCA Phase 2 (Fatoora) e-invoicing engine and management console for Laravel: B2B clearance, B2C reporting, device onboarding, ICV/PIH chaining, corrections and audit.
Requires
- php: ^8.1
- ext-dom: *
- ext-json: *
- ext-libxml: *
- ext-mbstring: *
- ext-openssl: *
- brick/math: ^0.9.3|^0.10|^0.11|^0.12|^0.13|^0.14|^1.0
- guzzlehttp/guzzle: ^7.5
- guzzlehttp/psr7: ^2.0
- illuminate/bus: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/cache: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/console: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/contracts: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/database: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/events: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/filesystem: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/http: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/queue: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/routing: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/support: ^9.52|^10.0|^11.0|^12.0|^13.0
- illuminate/view: ^9.52|^10.0|^11.0|^12.0|^13.0
- nesbot/carbon: ^2.62|^3.0
- opis/json-schema: ^2.3
- phpseclib/phpseclib: ^3.0.36
- psr/clock: ^1.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/log: ^1.1|^2.0|^3.0
Requires (Dev)
- openspout/openspout: ^4.0
- orchestra/testbench: ^7.0|^8.0|^9.0|^10.0|^11.0
- phpunit/phpunit: ^9.5.10|^10.0|^11.0|^12.0
Suggests
- laravel/horizon: Redis queue dashboard; the package's own queue page works without it.
- league/flysystem-aws-s3-v3: S3-compatible artifact storage.
- openspout/openspout: Read .xlsx / .ods files in Zatca::devices()->import() (CSV works without it).
- promphp/prometheus_client_php: Prometheus metrics adapter.
- spatie/laravel-permission: Role/permission storage for the zatca.* abilities (zatca:permissions:sync).
Provides
None
Conflicts
None
Replaces
None
README
ZATCA Phase 2 (Fatoora) e-invoicing engine and management console for Laravel, by CodingTriplets Technologies.
Status: under development (milestone M6 done: issuing, B2C reporting, B2B clearance, corrections and credit/debit notes, verified in ZATCA's developer sandbox). The dashboard follows in M7. Not for production before 1.0. Architecture and design decisions:
docs/ARCHITECTURE.md, which is the source of truth.
Documentation
| Guide | |
|---|---|
| Documentation site | Full user documentation (VitePress; published to GitHub Pages by .github/workflows/docs.yml) |
| Implementation guide | Step-by-step integration into an application, from sandbox to production |
| Technical documentation | Internals as built: flows, transactions, concurrency, state machines |
| Installation | Requirements, install options (Packagist, VCS, local path), first setup |
| Configuration | Every option in config/zatca.php |
| User Guide | Concepts, what works today, data model, validation helpers, roadmap |
| Testing | Test suite, other databases, Laravel version matrix, CI |
| Publishing | Releasing on Packagist or privately |
| Architecture | Design source of truth |
| ZATCA references | Official documents the code is checked against |
| Changelog |
What it will do
- Separate B2B (standard invoice → clearance) and B2C (simplified invoice → reporting) pipelines.
- Database-first processing: every invoice is persisted before any ZATCA call, and dispatched through a transactional outbox.
- Device (EGS) onboarding and renewal: CSR, compliance CSID, compliance checks, production CSID, certificate history.
- Atomic per-device ICV allocation and PIH hash chaining, with database-level guarantees against duplicates and forks.
- Human-in-the-loop correction of rejected invoices: one internal record, versioned JSON, and a new legal issuance (new UUID/ICV) per correction.
- Built-in Blade admin console at
/admin/zatca.
Supported versions
Compatibility is claimed only for combinations that pass CI (.github/workflows/ci.yml).
| Laravel | PHP | Status |
|---|---|---|
| 9.52+ | 8.1 – 8.2 | Supported (framework EOL: no upstream security fixes) |
| 10.x | 8.1 – 8.3 | Targeted (framework EOL) |
| 11.x | 8.2 – 8.4 | Targeted (framework EOL) |
| 12.x | 8.2 – 8.4 | Targeted |
| 13.x | 8.3 – 8.4 | Targeted |
| 14.x | — | Not released; added once stable and green in CI |
Supported databases: MySQL 8.0+, MariaDB 10.6+, PostgreSQL 13+ and SQL Server 2019+ (needs Microsoft ODBC Driver 18 and the pdo_sqlsrv extension; ⚠ its automated test run has not completed yet, see the docs). SQLite is for development and tests only.
Installation (development)
composer require codingtriplets/laravel-zatca php artisan vendor:publish --tag=zatca-config php artisan migrate
Set a dedicated key for credential encryption:
ZATCA_ENVIRONMENT=sandbox ZATCA_ENCRYPTION_KEY=base64:... # 32 random bytes, base64 ZATCA_ARTIFACT_DISK=local # private disk; use a shared disk (e.g. s3) on multi-server setups
Testing
composer test # unit + integration (in-memory SQLite) php tools/check-core-boundary.php ZATCA_TEST_DB=pgsql DB_PASSWORD=secret vendor/bin/phpunit # against PostgreSQL / mysql / mariadb / sqlsrv