Sdk Laravel Package

Getting Started

1. Install and pin the version. This is still a 0.x package, so treat minor bumps as potentially breaking:

   composer require peppol-sh/peppol-sh-php:0.3.*
   

   Avoid ^0.3 if you want stability; the changelog between 0.2.0 and 0.3.0 is the only signal you have, so read it before upgrading.

2. Publish and configure. If the package ships a service provider, publish its config and wire credentials into .env rather than committing them:

   php artisan vendor:publish --tag=peppol-sh-config
   

   Check config/peppol-sh.php (or equivalent) for endpoint, credentials, and any sandbox/production switch.

3. Where to look first.

   • src/ for the client class and any DTOs/value objects.
   • The service provider for bindings — resolve the client from the container rather than new-ing it.
   • tests/ or the README examples for the canonical request/response shape.

4. First use case. The most common day-one task is sending a UBL document to a Peppol participant. Start with a single hard-coded receiver Peppol ID in a tinker session or a throwaway artisan command before wiring it into application code. Confirm you can send one document end-to-end against the sandbox before building queues, webhooks, or persistence around it.

Implementation Patterns

• Wrap the SDK, don't scatter it. Put a thin application-level service (e.g. App\Services\PeppolSender) around the package client. When the SDK inevitably changes shape in a 0.4.0, you have one file to touch instead of twenty call sites.

• Queue outbound sends. Network calls to an access point are slow and flaky. Dispatch a job per document, store the returned document/transaction identifier on your model, and poll or await a webhook for final status. Never send synchronously inside a web request.

• Validate before you send. Use the package's validation (if present) or run UBL/Peppol BIS validation upstream. Getting a clean rejection from the access point is far slower to debug than catching a malformed cbc:CustomizationID locally.

• Treat inbound documents as webhooks. If the package supports receiving, follow the same pattern as Stripe: verify the signature, persist the raw payload, then process asynchronously. Store the raw XML/JSON — you will need it for reconciliation and disputes.

• Model the Peppol ID properly. It is a scheme:identifier pair (e.g. 0088:1234567890123), not a single string. Store scheme and identifier separately, or use a value object, so you can filter and display them correctly.

• Log correlation IDs, not payloads. Log the document ID and HTTP status. Invoice bodies contain customer PII and pricing — keep them out of your default log channel.

• Feature-flag the integration. Gate sending behind a config flag or Pennant feature so you can dark-launch and roll back without a deploy.

Gotchas and Tips

• 0.x semver means breaking changes are fair game. The v0.2.0 → v0.3.0 jump could rename methods or change return types. Pin exactly, and read the full changelog diff — the release notes here are just a link, so click through to the comparison and skim the commit titles.

• Sandbox vs. production endpoints are easy to mix up. Assert in your test suite that the configured endpoint matches the environment, and never let a .env copy-paste send a real invoice to a real supplier.

• Idempotency. If the SDK exposes an idempotency key or a client-generated document ID, use it. Retries after a timeout are the classic way to double-send an invoice.

• Retry policy. Wrap sends in retry() with backoff, but only for connection errors and 5xx. A 4xx validation failure will never succeed on retry and will just burn rate limit.

• Config caching. After changing .env in a deployed environment, php artisan config:clear — a cached config is the number one cause of "it works locally" with SDK packages.

• Timeouts. Set an explicit HTTP timeout (10–30s). Defaults in HTTP clients can be infinite, and a hung send will exhaust your queue workers.

• Extension points. If the client accepts a custom Guzzle handler stack or PSR-18 client, inject it — that's your hook for tracing, mocking in tests, and pointing at a local mock server.

• Testing. Mock at the HTTP layer (Guzzle MockHandler or Http::fake() if it uses the Laravel client) rather than mocking the SDK's classes, so you catch contract changes when you upgrade.