Sdk Laravel Package

Technical Evaluation

Architecture fit. The SDK is a framework-agnostic PHP client, which is a reasonable fit for Laravel but not a drop-in one. There is no service provider, config file, facade, or published contract, so the integration work is ours: binding a configured client into the container, externalizing credentials, and wrapping calls behind an application-owned interface. That is straightforward work, but it means the SDK should sit behind a thin adapter (e.g., ShippingProvider port) rather than being called directly from controllers, jobs, and checkout code. This preserves the ability to swap carriers or fall back to raw HTTP if the package stalls.

Integration feasibility. High for the core flows: create shipment, fetch label PDF, poll track & trace, list delivery options and pickup points. These map cleanly onto queued Laravel jobs and events. The main unknowns are around webhooks (does MyParcel push status updates, and is signature verification supported?), idempotency on shipment creation (critical — a timeout plus retry must not create duplicate labels that we pay for), and whether the SDK exposes the underlying API error codes with enough granularity to build a retryable/non-retryable taxonomy.

Technical risk.

• License is NOASSERTION. This is a hard gate. We cannot ship a dependency into a commercial checkout path without legal confirming redistribution and modification rights. This alone can block adoption.
• Low adoption (31 stars) and unknown repository provenance. Bus factor and maintenance continuity are unproven; we should assume we may need to fork and patch.
• No Laravel packaging. No tested support matrix for Laravel/PHP versions; Guzzle version constraints may collide with existing dependencies.
• Credential and PII handling. API keys and customer addresses flow through this client; logging must be scrubbed, and label PDFs are personal data requiring retention rules.
• Vendor coupling to MyParcel's API version. Breaking changes upstream surface as runtime failures unless versioning is explicit.

Key questions.

1. What are the actual license terms, and is the package officially maintained by MyParcel or a third party?
2. Is there a sandbox/test environment, and what are its rate limits and data-reset behavior?
3. Does shipment creation support idempotency keys or a dedupe window?
4. Are webhooks available, and how are they authenticated? If not, what is the required polling cadence and its cost?
5. What is the supported PHP/Laravel matrix, and is there CI/test coverage we can inspect?
6. Which carriers, regions (NL/BE/EU), and customs flows are covered, and what happens for unsupported destinations?
7. Is there a security disclosure process and a release cadence we can depend on?

Integration Approach

Stack fit. Treat the SDK as an infrastructure detail inside a bounded Shipping module: a MyParcelClientFactory bound as a singleton, credentials from config/services.php and env, and a ShipmentService/LabelService that returns our own DTOs. Controllers and checkout components never touch SDK classes. Register the binding in a dedicated service provider so tests can substitute a fake.

Migration path. If we already generate labels manually or via raw HTTP, introduce the adapter interface first and reimplement the existing path behind it. Then add the SDK as a second implementation and run both in shadow mode for a limited cohort: create the shipment via the SDK but reconcile against the manual result before cutting over. Feature-flag by carrier and region so a MyParcel outage or defect degrades to the prior path rather than blocking fulfillment.

Compatibility. Pin an exact minor version and commit the lockfile. Verify PHP version, Guzzle major, and ext-* requirements against our runtime before the spike. If the SDK lags our Laravel/PHP upgrade cadence, plan to fork with a minimal patch branch rather than waiting upstream. Isolate the dependency so a future replacement only touches the adapter layer.

Sequencing.

1. License and security review; confirm maintainer status — gate.
2. Sandbox spike: create a shipment, retrieve a label, read track & trace, capture the real error payloads.
3. Adapter interface, service provider, config, and credential handling.
4. Shipment creation and label retrieval behind queued jobs with idempotency and retries.
5. Tracking: webhook endpoint if supported, otherwise a scheduled poller with backoff.
6. Checkout delivery options and pickup-point selection, with caching for pickup locations.
7. Observability, error taxonomy, runbook, then progressive rollout by region.

Operational Impact

Maintenance. Expect to own the integration, not just consume it. Budget for periodic dependency bumps, monitoring upstream API changes, and a realistic possibility of carrying a fork. Assign a named owner and track the package in our dependency-review process; a stale release or silent breaking change should surface as an alert, not an incident.

Support. Distinguish three support layers: MyParcel's API/carrier support, the package maintainer (likely best-effort), and our internal on-call. Contractual questions — SLA, incident contacts, label cost disputes — go to MyParcel, not the package. Document this escalation path before launch.

Scaling. Label generation is I/O and PDF-heavy; keep it off the request cycle and in queue workers with bounded concurrency. Respect API rate limits with a per-account limiter; cache pickup points and delivery options with short TTLs since they are read-heavy at checkout. Watch for per-account throughput ceilings during peak (e.g., holiday) and load-test the queue path, not just the happy-path API call.

Failure modes.

• API timeout after a successful create → duplicate labels and double carrier cost. Mitigate with idempotency keys and a reconciliation job keyed on our order ID.
• Invalid or ambiguous address → shipment rejected late; validate before enqueue and surface actionable errors to ops.
• Label PDF retrieval failure or storage error → shipment exists but label is lost; add a retry-and-recover job since labels are retrievable by ID.
• Webhook loss or signature mismatch → stale tracking; run a low-frequency poller as a safety net.
• Rate-limit and auth failures → distinguish 401/403 (alert, do not retry) from 429/5xx (backoff, then DLQ).
• Silent SDK behavior changes on version drift → enforce pinned versions and contract tests against the sandbox.

Ramp-up. There is real domain learning here: carrier product codes, delivery options, customs data for non-EU, and NL/BE-specific conventions, with documentation that may be partly Dutch-language. Plan a short ramp with a shipping-operations stakeholder, build a small sandbox harness for the team, and encode the carrier/option matrix in configuration rather than code so ops can adjust without a deploy. Start with one carrier and one region, prove the label and tracking loop end to end, then widen.