Speedy Laravel Package

Technical Evaluation

Architecture fit. gdinko/speedy is a thin Laravel service-provider/facade wrapper over the Speedy (Bulgarian courier) REST API. Architecturally it slots in as an outbound integration adapter: configuration for credentials/endpoints via published config, a facade for label creation, rate calculation, tracking, and reference-data lookups (cities, offices, services). It is not a domain model — it will not own shipment state, pricing rules, or order lifecycle. That is the right shape for a wrapper, but it means the surrounding application must remain the system of record and must not let the vendor SDK's types leak into core domain code.

Integration feasibility. Composer install, config publish, credentials from the Speedy customer portal, and a sandbox/test endpoint is a sub-day spike for a Laravel developer. The blocker is not effort, it is coverage verification: with 21 stars and a low composite score (0.405), the package's surface area must be measured against the endpoints the business actually needs (calculation, shipping/label, print, tracking, pickup requests, cancellation, COD). Anything missing means either a fork or a fallback to a hand-rolled Guzzle client on the same endpoints.

Technical risk.

• Maintenance / bus factor: effectively a single-maintainer, low-adoption package. Treat abandonment as the base case, not the tail case.
• API drift: Speedy can change auth, payload shapes, or endpoints; the package has no commercial incentive to chase them. Silent breakage is more likely than loud breakage.
• Framework compatibility: Illuminate version constraints and PHP version floors must be checked against the target app; a major Laravel upgrade may strand the dependency.
• Test coverage: unverifiable from the outside — assume no contract tests against the live sandbox.
• Reference data: city/office datasets are large and change; if the package does not cache them, it becomes a per-request latency and rate-limit liability.

Key questions.

1. Which Speedy endpoints are covered, and which are stubs or absent?
2. What are the declared illuminate/* and PHP constraints, and does it work on our target Laravel version?
3. Does it use Laravel's HTTP client, and are timeouts, retries, and exception mapping configurable?
4. How is auth token acquisition/refresh handled, and is it cached across requests?
5. Is there any test suite, CI, or sandbox fixture set?
6. Does it model responses as typed DTOs or raw arrays?
7. Is reference data cacheable, and does the package respect Laravel's cache driver?
8. What is the commit/release cadence over the last 12 months, and is there an issue backlog response pattern?

Integration Approach

Stack fit. Native Laravel fit: service provider, facade, config file, Composer autoload. It assumes standard Laravel conventions and will not conflict with queue workers, schedulers, or an existing HTTP client stack. If the application is not Laravel, this package is the wrong dependency — port the endpoints, not the wrapper.

Migration path. Do not call the facade from controllers or jobs directly. Introduce an application-owned ShippingGateway interface, implement it with this package behind a feature flag, and keep a second implementation (direct HTTP client or a competing wrapper) as a swap target. This is the single most important decision: it converts "vendor abandonment" from a rewrite into a one-class change, and it gives you a seam to add idempotency, retries, logging, and metric capture the wrapper will not provide.

Compatibility. Pin the exact version and commit the lockfile. Verify PHP and Illuminate constraints before the spike, not after. Confirm config caching works (no closures in the config file) and that the facade resolves in a queued context. Check that the package does not ship global helpers or conflicting singletons.

Sequencing.

1. Sandbox spike: credentials, one rate calculation, one label, one tracking lookup — timeboxed, output is a coverage matrix, not production code.
2. Coverage gap analysis against business requirements; decide buy vs. fork vs. hand-roll.
3. Define the gateway interface and error taxonomy; wrap the package behind it.
4. Contract tests against the sandbox (happy path plus 4xx/5xx/timeout).
5. Pilot on a single low-volume shipping route or internal-only flow behind a flag.
6. Promote, then set a scheduled dependency review (quarterly) with a documented fork trigger.

Operational Impact

Maintenance. Budget for ownership. Realistically this becomes "we maintain a fork" within 12–24 months. Assign a named owner, track upstream commits, and keep the fork diff small by confining local patches to the adapter layer. A quarterly check of upstream activity and Speedy API changelog is the minimum viable cadence.

Support. Community-only, no SLA, no vendor escalation for the wrapper itself (Speedy support covers the API, not the package). Internal runbook must document: how to rotate credentials, how to enable verbose HTTP logging, how to reproduce a failed label call in the sandbox, and who to escalate to when Speedy changes something.

Scaling. Throughput is bounded by Speedy's API, not by the package. The operational levers are all application-side: queue label creation rather than doing it synchronously in the checkout path, apply exponential backoff on 429/5xx, cache reference data (cities/offices) with a long TTL and a scheduled refresh, and cache auth tokens. Label creation must be idempotent on our side — a timeout does not mean the shipment was not created.

Failure modes.

• Auth token expiry or credential rotation → total integration outage until config is updated.
• Timeout during label creation → duplicate shipments and duplicate courier charges if not reconciled; requires an idempotency key and a reconciliation job.
• Reference-data staleness → invalid office IDs, failed labels, customer-facing pickers showing closed offices.
• Silent response-schema drift → null fields written to the database, discovered downstream by finance or ops rather than by monitoring.
• Package abandoned mid-upgrade → blocked framework upgrade until the adapter is replaced.
• Rate limiting under seasonal volume → queue backlog, delayed dispatch.

Ramp-up. Low for a Laravel developer to get a sandbox call working; moderate to production-grade because the hard part is courier domain knowledge (service codes, COD, weight/dimension rules, label formats, return flows) and Speedy's regional specifics, not the PHP. Plan for one developer-week to a competent integration with tests and the adapter seam, plus review time from whoever owns shipping operations.