Laravel Shiprocket Api Laravel Package

Technical Evaluation

Architecture fit. seshac/laravel-shiprocket-api is a thin Laravel wrapper around the Shiprocket (India-focused shipping/fulfilment aggregator) REST API, delivered as a service provider + facade with a published config file for credentials. Architecturally it is a low-coupling dependency: it sits at the integration edge of an e-commerce/order-management Laravel application and does not impose domain models, repositories, or persistence of its own. That is good for adoptability but means the package provides transport and endpoint ergonomics, not an abstraction — Shiprocket's request/response shapes and error semantics will leak into calling code unless we introduce our own adapter boundary.

Integration feasibility. High for a standard Laravel app: composer require, publish config, add SHIPROCKET_* env vars, resolve the facade or inject the client. The work is not in the install but in the surrounding concerns — credential management per environment, token/session handling, and mapping our order lifecycle to Shiprocket's create-order / assign-AWB / pickup / manifest / label flow.

Technical risk. Moderate-to-elevated, and mostly not about the code change in 2.0.0:

• Bus factor of one. Single maintainer (@seshac), small community, infrequent releases (1.0.4 → 2.0.0 with a changelog that is a single PR). Abandonment is a realistic scenario; we must assume we may have to fork.
• Quality gates were reduced, not increased. This release removes Psalm. Static analysis was the only visible type-safety signal on a package that talks to a third-party API with loosely-typed payloads. Net quality posture went down even as the platform requirement went up.
• No test signal in the release notes. No mention of PHPUnit/Pest, coverage, or CI matrix. We cannot infer regression safety from the changelog.
• Semver discipline is ambiguous. The major bump appears driven solely by dropping PHP 7.x for PHP 8.x support — a defensible reading of semver, but it tells us nothing about API-surface stability between minors.

Key questions.

1. What are the exact composer.json constraints — php, illuminate/*, guzzlehttp/guzzle? Does 2.0.0 support Laravel 9/10/11, or only the 8.x-era framework?
2. Is there a CI matrix and test suite, and what does it cover — request building only, or response/error handling?
3. Is Shiprocket API token acquisition and refresh handled internally, including caching and concurrent-request safety?
4. Does the package expose webhook handling (Shiprocket pushes shipment status callbacks), or is that ours to build?
5. Are rate limits, retries, and timeouts configurable, or hardcoded?
6. Is the Shiprocket API version pinned, and how are upstream breaking changes surfaced?
7. Who is accountable if the maintainer stops responding — do we have a fork-and-maintain budget approved?

Integration Approach

Stack fit. Targets Laravel with PHP 8.x. It is a conventional package: service provider, facade, config publish, Guzzle underneath. It fits a Laravel monolith or modular monolith that owns order fulfilment. It is a poor fit for a non-Laravel service, a multi-tenant SaaS where per-tenant Shiprocket credentials are needed (verify config is runtime-overridable, not boot-time only), or an event-driven architecture expecting first-class webhook/queue primitives.

Migration path.

• If we are on PHP 7.4: 2.0.0 is unusable. We stay on 1.0.4, which is now unsupported upstream — treat that as a tracked risk with a PHP 8 upgrade deadline, not a steady state.
• If we are on PHP 8.0/8.1: 2.0.0 is the right target, but it is a breaking major — audit every call site, since the version bump may accompany signature or return-type changes not itemised in the changelog.
• If we are already on the package: pin ^2.0 only after a green contract-test run against the Shiprocket sandbox; do not float the constraint.

Compatibility. Confirm framework constraint alignment before commit — the release notes advertise PHP 8 support but say nothing about Illuminate versions, and a package supporting "PHP 8.x" may still cap at Laravel 8/9. Also verify PHP 8.2/8.3 readiness (dynamic property deprecations are a common break in older wrappers) and that Guzzle major-version constraints do not conflict with the host app.

Sequencing.

1. Runtime upgrade (PHP 8.x) and framework upgrade land first, independently.
2. Add PHPStan/Larastan at a meaningful level in our codebase — this substitutes for the Psalm coverage the package just dropped and is non-negotiable given the removal.
3. Introduce an internal ShippingGateway interface with a Shiprocket-backed implementation wrapping the package; all application code calls the interface, never the facade.
4. Write contract tests against the Shiprocket sandbox pinning request shapes and error mapping.
5. Ship behind a feature flag on a low-volume lane (one warehouse / one courier partner) before full rollout.
6. Establish a fork-and-patch runbook, including a dev- Composer repository override path.

Operational Impact

Maintenance. Low day-to-day, high latent. The wrapper is small, so upgrades are rare — and that is the problem: rare releases mean long gaps in compatibility testing against new Laravel/PHP versions, discovered at the worst time. Budget an explicit quarterly "is this still alive" review (last commit, open issues, PHP/Laravel support) and record the result. Fork readiness is the real maintenance control.

Support. GitHub issues only — no SLA, no vendor, no commercial backing. Escalation for Shiprocket-side API problems goes to Shiprocket's own support and is entirely outside the package. Internally, name an owner for this integration; unowned third-party wrappers rot silently.

Scaling. The wrapper adds no scaling capability of its own; throughput is bounded by Shiprocket's rate limits and our HTTP client config. Three things must be tuned explicitly: connection pooling/timeouts, retry-with-backoff on 5xx and 429, and token refresh under concurrency (a naive implementation re-authenticates on every request or stampedes on expiry). Fulfilment calls — order creation, AWB assignment, label and manifest generation — should run on queued jobs with idempotency keys, not synchronously in the checkout path. Verify the package does not hold state in a singleton that breaks under Octane or queue workers.

Failure modes.

• Duplicate shipments. A timeout on create-order followed by a retry can produce two shipments and real financial loss. Mitigate with our own idempotency layer and a reconciliation job against Shiprocket order listings — do not rely on the package for this.
• Silent auth expiry. Token invalidation surfaces as generic 401s; without explicit handling we see order-creation failures that look like application bugs.
• Schema drift. Shiprocket changes a response field; the wrapper passes it through untyped (now with no Psalm) and we fail at unserialisation or, worse, silently persist nulls. Contract tests and strict response validation are the control.
• Maintainer abandonment. Package becomes uninstallable on a future Laravel/PHP release; the fork runbook must be executable within days, not quarters.
• Credential leakage. Config-file-driven credentials risk being committed; enforce env-only sourcing and secret scanning.

Ramp-up. Low technical ramp-up — a Laravel developer is productive in half a day. The genuine cost is domain ramp-up: Shiprocket's pickup-address, channel, courier-partner, AWB, manifest, and RTO concepts, plus India-specific GST/COD handling. Budget for a domain primer and sandbox access before the first sprint, and expect the first integration to take materially longer than the install time suggests.

Recommendation. Adopt 2.0.0 for PHP 8 applications, but only behind an internal adapter interface, with contract tests, an idempotency layer for shipment creation, and an approved fork contingency. Do not adopt it as a load-bearing dependency without an owner and a sandbox test suite.