Verifactu Bundle Laravel Package

Technical Evaluation

Architecture fit

• Despite the "Laravel/PHP package" framing, the artifact is a Symfony bundle (verifactu-bundle). It is designed to be registered via a Symfony kernel/DI container, not a Laravel service provider. In a Laravel codebase it will not "just install" — it needs a bridge or a standalone invocation of the underlying Verifactu library.
• Domain fit: Verifactu is the Spanish anti-fraud invoicing regime (SIF). A bundle like this is a compliance layer, not a business feature. It should sit behind an internal InvoiceCompliance / TaxAuthorityGateway interface so the rest of the application never imports vendor classes directly.
• Coupling risk is moderate-to-high: the bundle likely owns invoice record construction, hash chaining, QR generation, and AEAT submission. All four are regulatory surfaces where vendor behavior becomes your legal exposure.

Integration feasibility

• Feasible for a small, well-contained billing service. Not feasible as a drop-in for a large Laravel monolith without an adapter.
• Expect the usual PHP/Symfony dependency graph (HttpKernel, DI, HTTP client, XML/JSON serializers, certificate handling). Each of these is a version-constraint negotiation against your existing composer.json.
• Requires outbound connectivity to AEAT endpoints plus X.509 certificate material for signing — this is a security and secrets-management integration, not just an API client.

Technical risk

• Pre-1.0 version (0.1.x) implies no backward-compatibility guarantee. A patch bump from 0.1.5 → 0.1.6 can still contain breaking changes under semver's 0.x rules.
• Release transparency is poor. The v0.1.6 notes contain only a diff link and no changelog entries, no described fixes, no migration guidance. This is a material signal: you cannot triage upgrade risk from the release itself; you must read the diff.
• Regulatory risk dominates technical risk. If hash chaining, record sequencing, QR payload format, or AEAT schema handling is wrong, the failure mode is legal/audit non-compliance in Spain, not a 500 error. A pre-1.0 library is a thin foundation for that obligation.
• Vendor concentration risk. The GitHub org appears to be a small independent publisher. Bus factor, long-term maintenance, and response time to AEAT regulatory changes are unknown and are the single biggest risk in this assessment.

Key questions

1. Does v0.1.6 contain breaking changes? (Diff must be reviewed — release notes do not answer this.)
2. Is there a documented compatibility matrix (PHP version, Symfony version, Laravel version)?
3. Is the bundle a wrapper over a separately maintained core library, or self-contained? Is the core library versioned and released independently?
4. Who is the publisher, what is their track record, and is there any commercial support or SLA?
5. How are AEAT schema/regulatory changes tracked and how quickly are they shipped?
6. What is the test story — is there a preproducción (AEAT test environment) harness, fixtures, or recorded-response tests?
7. How is certificate material supplied and stored? Does the bundle require filesystem paths to .p12/.pem, or does it accept an injected signing service?
8. What is the license, and does it impose obligations on a closed-source commercial product?

Integration Approach

Stack fit

• Treat the bundle as a replaceable infrastructure dependency. Define a narrow internal interface (submitInvoice(), voidInvoice(), getRecordStatus(), generateQrPayload()) and implement it with a thin adapter around the bundle. This preserves the option to swap to a commercial SIF provider — a realistic alternative under Verifactu — without touching domain code.
• In Laravel, do not attempt to load the bundle's Symfony service definitions into Laravel's container. Prefer either (a) a small standalone bootstrap that instantiates the bundle's services manually, or (b) if the bundle is a thin shell over a core library, depend on the core library directly and skip the bundle entirely. Option (b) is usually cleaner and is worth validating first.

Migration path

1. Spike (1–2 weeks): install in an isolated service, exercise the happy path against AEAT preproducción, and confirm the bundle is usable without a full Symfony application.
2. Pin and vendor: pin 0.1.6 exactly ("0.1.6", not ^0.1), commit composer.lock, and archive the resolved dependency tree. Do not allow automatic minor/patch upgrades while pre-1.0.
3. Adapter layer: implement the internal interface, with contract tests that assert hash-chain and QR output against known-good fixtures.
4. Shadow mode: generate and persist Verifactu records for real invoices without submitting, and reconcile against a manual/independent check for a defined period.
5. Cutover: enable submission behind a feature flag, per-entity, with a documented rollback to manual/legacy process.

Compatibility

• Verify PHP constraint, Symfony component constraints (6.x vs 7.x), PSR HTTP client implementation, and any XML extension requirements (ext-soap, ext-dom, ext-openssl) against the current runtime image.
• Confirm the bundle's HTTP client is injectable — otherwise you inherit its transport, timeout, and retry behavior, which will not match your observability stack.
• Confirm Laravel queue compatibility indirectly: if submission is synchronous inside a request, you will need to wrap it in a job regardless.

Sequencing

• Do not sequence this behind other billing refactors. Because it is a compliance dependency with an external deadline, it warrants its own track with an explicit go/no-go gate at the end of the spike. The gate should include "publisher is responsive and has a credible plan for regulatory updates," not just "the demo worked."

Operational Impact

Maintenance

• Pinning is mandatory, and pinning means you own the upgrade decision each time. Budget recurring effort for diff review on every release, because the changelogs are not usable as-is.
• Pre-1.0 churn plus a small upstream means you should expect to occasionally carry a local fork or patch. Confirm the license permits that and that the maintainer accepts patches.
• Regulatory drift is the real maintenance cost: AEAT schema revisions, QR spec clarifications, and hash-chain rule updates will force upgrades on someone else's timetable. Plan a standing "compliance dependency review" cadence rather than ad-hoc upgrades.

Support

• Assume no SLA. This is community OSS from an independent publisher. There is no escalation path if a submission bug appears during a filing period.
• Mitigation: identify a named internal owner (not a shared team), and consider a paid support or commercial SIF fallback contract if invoice volume or audit exposure is material.
• Document a manual fallback procedure for AEAT submission — the regulation generally permits a contingency process, and you will need one written down before you need it.

Scaling

• AEAT submission is an external, rate-limited, latency-bound operation. It must run asynchronously via queued jobs with idempotency keys; synchronous in-request submission will not scale and will couple invoice creation to tax-authority availability.
• Hash chaining is serial by nature — per-issuer record sequencing is the throughput bottleneck. Design for a single-writer-per-entity worker to avoid chain corruption under concurrency. This is a real architectural constraint that the bundle may not enforce for you.
• QR generation and signing are cheap; XML/JSON payload construction and retries are the cost centers. Instrument them separately.

Failure modes

• AEAT unavailability / timeout: invoices must still be issued and records persisted; submission must be retried. Verify the bundle distinguishes "record created" from "record accepted."
• Hash-chain break: a duplicate or out-of-order insert corrupts the chain and may require a formal incident process. Enforce sequencing at the database level, not in application code alone.
• Certificate expiry or rotation: a silent expiry takes down all submissions. Add explicit expiry monitoring.
• Rejected records: a schema mismatch after an AEAT change surfaces as mass rejection. Alert on rejection rate, not just on exceptions.
• Silent dependency upgrade: ^0.1 resolving to a future 0.1.x with changed payload format. Prevented only by exact pinning.
• Clock skew: record timestamps are regulatory data; NTP discipline is a hard prerequisite.

Ramp-up

• Expect 1–3 weeks for an engineer unfamiliar with Verifactu to become productive: the regulation itself is nontrivial, and understanding what "correct" means is a bigger lift than learning the library's API.
• Pair the engineering ramp-up with a finance/tax-owner review of the generated records. This is a two-discipline integration, and the finance side is usually the slower half.
• Do not onboard this package onto a team without a designated owner who can read the AEAT specification directly. Relying solely on the library's docs for compliance semantics is the most common and most expensive mistake with this class of dependency.

Verdict on v0.1.6: Insufficient release information to assess the change. The version warrants a cautious, time-boxed evaluation rather than adoption, and any integration should be gated on the publisher's responsiveness and on a successful preproducción spike.