Sdk Laravel Package

Technical Evaluation

What the package is. peppol-sh/peppol-sh-php is a PHP client for the peppol.sh hosted Peppol hub. It abstracts Peppol network access — outbound document submission (UBL / Peppol BIS Billing 3.0), inbound document retrieval, and participant/recipient lookups — so a Laravel application does not need to become a certified Peppol Access Point itself. Integration is Laravel-idiomatic (Composer, service provider, publishable config, env-based credentials), but the package is a thin SDK over a commercial API; the durable dependency is the vendor relationship, not the code.

Release signal for v0.3.0 is effectively nil. The published notes contain only a v0.2.0...v0.3.0 compare link — no changelog body, no breaking-change statement, no migration notes. For a pre-1.0 package where semver permits breaking changes on a minor bump, this release is unassessable from the artifact alone. This is a governance finding in its own right: it means every upgrade requires a manual source diff, and it should factor into the adoption decision as an ongoing cost rather than a one-off.

Architecture fit. Strong if the strategic choice is to consume Peppol rather than operate it. Running your own Access Point implies AS4 transport, SMP/SML publication, certificate lifecycle management, and continuous BIS conformance testing — realistically a multi-quarter programme. Outsourcing that to a hub is the correct call for most product teams. The trade-off is a hard dependency on a single commercial intermediary for a legally significant document path.

Technical risk.

• Pre-1.0 churn. Minor-version breaking changes are permitted and, given the empty changelog, plausible. Pin exactly; treat every bump as a review gate.
• Legally significant payloads. Invoices carry statutory retention and audit obligations. Confirm how the hub handles document persistence, retrieval window, and whether our system remains system-of-record.
• Validation boundary. Local EN 16931 / BIS Billing 3.0 validation posture matters — rejected-at-AP errors are typically opaque and expensive to debug against a counterparty.
• Idempotency and delivery semantics. Whether the API exposes a client-generated message ID determines whether safe retry is possible.
• Data residency and credential handling. EU hosting and secret management through config/env, not committed config.
• Mandate drift. National e-invoicing regimes (Italy SdI, France, Germany) move independently of Peppol; clarify who owns that compliance surface.

Key questions for the vendor/maintainer. What changed in v0.3.0, and is it breaking? Is a maintained changelog now an expectation? What are the API uptime commitments and status-page history? Does the package surface a stable, typed error taxonomy suitable for automated retry/alerting? Is there a Peppol-certified sandbox with test participants? What are the per-document economics and rate limits? Is inbound delivery push (webhook) or pull, and is replay guaranteed? Which Peppol AP / SMP certifications are held?

Integration Approach

Stack fit. Targets Laravel applications on modern PHP (8.1+) via Composer. The natural placement is a bounded adapter — a small internal InvoiceTransport interface with a peppol-sh implementation — rather than direct SDK calls from controllers or jobs. This preserves the option to swap hubs and makes the transport testable.

Compatibility checks before committing. Confirm the supported Laravel/PHP matrix, whether the SDK pins a Guzzle major version (a common conflict source in larger Laravel estates), and whether it routes through Laravel's HTTP client — if it does, Http::fake() gives cheap contract tests; if not, integration tests require a sandbox or a mock-server harness. Verify response types are DTOs or arrays, since that determines how much of our code breaks on a minor bump.

Migration path. Greenfield: no migration, straight to sandbox. Replacing an incumbent access point (Storecove, Tickstar, Basware, etc.): introduce the adapter seam first, run both providers against the same sandbox participants, and compare accept/reject behaviour and generated UBL byte-for-byte where possible. Do not dual-send to real recipients — duplicate deliveries to a counterparty's AP are visible and reputationally costly.

Sequencing.

1. Pin v0.3.0 exactly; read the full v0.2.0...v0.3.0 diff and record what broke.
2. Obtain sandbox credentials; stand up config and secret handling.
3. Outbound: validate a UBL against EN 16931 locally, then send, then confirm status polling/acknowledgement semantics.
4. Inbound: wire the receive path (webhook or poll), make handlers idempotent, add a reconciliation job as a safety net.
5. Participant lookup with caching — lookups are latency-bearing and cacheable by participant ID with a sane TTL.
6. Production with one counterparty and one document type, then widen.

Operational Impact

Maintenance. The dominant cost is version review, not code. With no changelog content, each minor bump implies a source diff and regression pass — budget roughly one to two days per release, and gate upgrades behind the adapter's contract tests. If release cadence is high, that overhead compounds; it is a legitimate reason to pin and upgrade on a scheduled cadence rather than continuously.

Support. Two support surfaces — community OSS maintenance and commercial hub operations — and the boundary between them should be explicit in the contract. When a transmission fails, the question is whether it is our payload, the SDK, or the hub, and resolution time depends entirely on the vendor's responsiveness. Test this during evaluation, not after go-live.

Scaling. Our infrastructure is not the constraint; per-document pricing and API rate limits are. Outbound volume is naturally spiky (month-end, batch onboarding), so outbound should be queued with backoff and concurrency capped below the vendor's limit. Inbound handlers must tolerate bursts and replays. Cost model should be modelled per document at projected volume, including retries that may bill.

Failure modes.

• Hub outage blocks a statutory delivery path — define a documented manual/fallback procedure and a customer-communication path for periods when invoices cannot be transmitted.
• Non-idempotent retries producing duplicate invoice submissions to a counterparty.
• Counterparty-side certificate or SMP registration expiry, surfacing as delivery failures we cannot fix — needs a diagnostic runbook that distinguishes our-fault from their-fault.
• Silent inbound loss if webhooks fail without a polling reconciliation backstop.
• Opaque AP rejections consuming engineering time; mitigate with strict pre-submission validation.

Ramp-up. A competent Laravel engineer integrates the SDK in days; the real ramp is Peppol domain literacy — participant identifiers and schemes, SMP/SML, BIS Billing 3.0 profile rules, and the difference between "delivered to the AP" and "accepted by the recipient." Plan one to two weeks to genuine competence, plus a written operational runbook for finance/ops covering failed transmissions, resends, and archive retrieval.