josemmo/verifactu-php
Josemmo Verifactu PHP is a framework-agnostic library for Spain’s VERI*FACTU e-invoicing rules, helping generate QR codes and XML, sign invoices, validate records, and submit them to AEAT. It simplifies compliance for PHP and Laravel applications.
Architecture fit. Verifactu-PHP is a framework-agnostic PHP library that implements Spain's Verifactu anti-fraud billing requirements (record chaining, hashing, QR payloads, and AEAT submission). It is not a Laravel package in the conventional sense — there is no documented service provider, config publishing, or facade — so in a Laravel codebase it behaves as a domain dependency rather than an infrastructure component. That is a reasonable fit for billing logic, which belongs in a dedicated service layer rather than in controllers or Eloquent models, but it means the integration surface is code we own, not code the vendor maintains.
What v0.3.4 changes. The release is additive on its face: support for requerimientos de información (AEAT information requests — a new interaction type beyond record submission), support for baja de remisión voluntaria (deregistration from the voluntary submission regime), and new usage guides in the documentation. The last item matters more than it looks — with prior documentation sparse, this is the first release where a TPM can reasonably estimate integration cost from the vendor's own artifacts rather than from reading source. The two functional additions expand the scope of the library from "emit records" to "manage the lifecycle of a relationship with AEAT," which slightly widens the compliance surface we inherit.
Integration feasibility. Technically straightforward: Composer install, a few classes instantiated behind an application-level interface. There is no migration, no DB schema imposed, and no runtime service dependency at request time (submission is asynchronous in practice). The real effort is in mapping our invoice domain onto the library's record model and persisting the chain state durably and atomically — chain integrity is a correctness requirement, not a performance concern, and it is the part the library cannot do for you.
Technical risk. Three items dominate. First, pre-1.0 versioning: at 0.3.x, a minor bump may carry breaking changes, and this release adds public surface (request handling, deregistration) that will likely be reshaped before 1.0. Pin exactly and treat upgrades as change-controlled work. Second, single-maintainer bus factor on a component with legal consequences — the failure mode is not a broken site but non-compliant invoices. Third, regulatory coupling: AEAT schema and procedural changes (the compliance deadlines themselves have already been deferred once) can invalidate assumptions faster than a community library's release cadence. The new information-request support is evidence of exactly this drift.
Key questions.
Stack fit. Compatible with any Laravel version on a supported PHP runtime; no framework coupling to fight. Adopt it behind a first-party InvoiceSubmission interface in the application's domain layer so the library is swappable and so the rest of the codebase never imports its namespace directly. That indirection is cheap now and expensive later.
Migration path. Not a migration in the data sense — there is no legacy state to convert unless we have been issuing Verifactu records another way. Sequence: (1) pin 0.3.4 and vendor it; (2) build the chain-state persistence and a replay/verification path; (3) implement submission in a single non-critical invoice flow first; (4) add the new information-request and deregistration handlers only when a regulatory owner confirms they are needed for our obligation tier. Do not build the deregistration flow speculatively; it is an edge case for a regime most integrators will not enter.
Compatibility. Verify PHP version support and whether the library depends on SOAP/curl extensions or optional sodium/openssl features that differ between local, CI, and production images. If we run queue workers and web nodes on different images, the extension parity matters for hash and certificate handling.
Sequencing. Treat this as a compliance project with an engineering component, not the reverse. The chain-state design and audit trail should land before the first production submission; the v0.3.4 features can trail by a sprint. Given pre-1.0 churn, budget one upgrade-and-retest cycle per quarter rather than a single "done" milestone.
Maintenance. Expect active upkeep during the pre-1.0 period: pinned version, changelog review per release, and a scheduled upgrade window. The library itself is small; the maintenance cost sits in regression-testing submission against AEAT's test environment after each bump, which is slow and externally gated.
Support. Support ultimately comes from the maintainer plus our own reading of Spanish regulations. Assign an internal owner who can interpret AEAT guidance — this is a named-role requirement, not a shared responsibility. Keep the new usage guides in the repo's docs alongside our own runbook, since they are the closest thing to an authoritative integration reference.
Scaling. Submission volume is bounded by invoicing volume, not user traffic — orders of magnitude below web load. The library is not the bottleneck; certificate handling, retry queues, and AEAT rate limiting are. Decouple submission into a queue so a slow or unavailable AEAT endpoint never blocks invoice issuance, and store records locally first so the system remains legally functional offline.
Failure modes. (1) Chain corruption — a duplicate or out-of-order record, typically from concurrent writes or a retried job; guard with DB-level locking and idempotency keys. (2) Submission outage at AEAT — records must persist and retry, never be dropped. (3) Silent schema drift — a rejected record looks like a normal API error; alert on rejection codes rather than on HTTP failures. (4) Upstream abandonment — mitigate with the interface boundary and enough internal documentation to fork or reimplement. (5) Unhandled new interaction types — an information request that goes unanswered because we never built the handler.
Ramp-up. Low for a PHP developer comfortable with Composer; moderate for the domain. A competent engineer is productive in the library within a day. Understanding Verifactu's obligations — what must be recorded, what must be chained, what must be sent — takes considerably longer and should not be learned from this library alone. Reserve roughly one to two weeks of engineering for a first compliant flow plus a parallel regulatory briefing for the product owner; the v0.3.4 guides should reduce the former but do not replace the latter.
How can I help you explore Laravel packages today?