Laravel Ups Api Laravel Package

Technical Evaluation

Architecture fit ptondereau/Laravel-UPS-Api is a thin, conventional Laravel integration package: a service provider with auto-discovery, a publishable config file for UPS credentials, and facades fronting discrete service classes (Ups\Rate, Ups\Shipping, Ups\Tracking, Ups\Address, etc.) that speak to UPS's REST endpoints over OAuth client-credentials. It imposes no domain architecture — it is an infrastructure adapter you call from a service or job. That makes it a low-coupling fit for a Laravel monolith, a modular monolith, or a standalone shipping service. v5.0.0 does not add business capability; it is a platform-currency release that re-baselines the supported framework/runtime matrix and hardens the type contracts.

Integration feasibility composer require ptondereau/laravel-ups-api:^5.0 is mechanically trivial; feasibility is entirely gated by the host application's PHP and Laravel version. Laravel 13 and PHP 8.5 are the leading edge of the matrix, so for the majority of estates this release is not yet installable — and conversely, teams already running L13/PHP 8.5 previously had no supported path at all. The @mixin annotations on facades are a genuine integration accelerant: facade calls previously resolved to mixed under PHPStan and PhpStorm, which forced developers to read package source to learn return types and pushed teams toward blanket baselines or @phpstan-ignore. That friction is now removed.

Technical risk

• Major version bump without a stated floor. The changelog says what was added (L13, PHP 8.5) but not what was dropped. A v5 major almost certainly raises composer.json minimums; that is the single highest-impact unknown and must be confirmed before planning.
• PHPStan level 10 is a double-edged signal. It means the package's own public docblocks and signatures are now precise. Tightened parameter/return types are generally backward-compatible in PHP for consumers, but they are breaking for inheritance — any internal code that extends package classes or overrides methods is at risk.
• @mixin correctness is asserted, not proven. If a facade method is not actually present on the mapped Ups\* root class, static analysis will report confident-but-wrong types. It also converts previously-suppressed mixed flows into real type errors, which can surface as a wave of new PHPStan/PhpStorm diagnostics in consuming apps.
• Upstream API drift is unaddressed. UPS sunsets and versions its own APIs on an independent cadence. Nothing in the release notes indicates which UPS API versions are targeted or whether payload/DTO shapes changed.
• Operational risk dwarfs code risk. Credential provisioning, sandbox access, and UPS account entitlements are the real blockers, not the library.

Key questions

1. What are the minimum PHP and Laravel versions in v5.0.0, and precisely which versions were dropped relative to 4.1.0?
2. Are there changes to config keys, facade names, public method signatures, exception types, or response DTOs?
3. Is there a shippable PHPStan config/baseline or a documented recommended level for consumers?
4. Which UPS API versions/endpoints are targeted, and what are their published sunset dates?
5. Does the package cache the OAuth token, and does it ship retry/backoff for 429/5xx?

Integration Approach

Stack fit Treat v5.0.0 as a forward-looking adoption, not a maintenance upgrade. Estates on Laravel 10–12 with PHP 8.2–8.4 should remain on 4.1.x — this release is a no-op for them and forcing it will simply fail Composer resolution. Greenfield projects, or teams already piloting L13/PHP 8.5, are the natural first adopters and get the PHPStan/@mixin benefit for free.

Migration path (4.1.0 → 5.0.0)

1. Inspect composer.json in the tag to confirm the exact PHP/Laravel floor.
2. Upgrade PHP and Laravel in a separate, isolated PR; do not couple framework and package bumps.
3. Bump the package — the diff should be composer.json + composer.lock only.
4. Run the app test suite, then run PHPStan at your current level and capture the delta.
5. Remove baseline entries and @phpstan-ignore comments that existed only because facade calls returned mixed.
6. Smoke-test against the UPS sandbox: OAuth token acquisition, rate quote, label creation, tracking lookup, address validation.

Compatibility Audit for other packages pinned to Laravel ≤ 12 before touching framework versions. Audit internal code for (a) extends on package classes, (b) type hints against package types in interfaces, and (c) any code that previously accepted mixed from a facade and now receives a concrete type. The @mixin change is additive at runtime and safe to ship, but it will change IDE behavior — expect a one-time spike in editor diagnostics.

Sequencing Framework/runtime upgrade → package major bump → static analysis ratchet → baseline cleanup → production rollout behind a flag on shipping flows. Keep the package bump non-functional in scope so any regression is attributable to a single variable.

Operational Impact

Maintenance Low-to-moderate code maintenance, with a bus-factor consideration: this is effectively a single-maintainer package (@ptondereau). Release cadence tracks Laravel's, which is a healthy signal. The PHPStan level 10 addition is a net positive for maintainability — type-contract regressions are now caught upstream in CI rather than discovered by consumers at runtime.

Support Upstream support is GitHub issues and PRs; SLA expectations should be set accordingly. Internal support burden sits almost entirely in credential onboarding and UPS account entitlements rather than in the library. Incident triage requires correlating with the UPS status page — the package cannot distinguish "UPS is down" from "your credentials are wrong" without your own instrumentation.

Scaling The package is thin and not the bottleneck. Scaling is dominated by: UPS API quotas, OAuth token caching (a client-credentials token must be cached and reused, never fetched per request), HTTP timeouts and retry policy, and queueing non-interactive work (label generation, manifesting, end-of-day close-out). Recommended pattern: wrap facade calls in an internal service layer with backoff, jitter, and a circuit breaker, and never invoke facades directly from controllers. Note that the static analysis improvements in v5.0.0 change nothing about runtime throughput or latency.

Failure modes

• Auth failures — expired/rotated client ID or secret, or uncached tokens causing 401 storms and UPS-side throttling.
• API version sunset — UPS decommissions an endpoint the package targets; failures are hard and persist until an upstream release.
• Rate limiting and 5xx — 429/503 from UPS require backoff; the release notes make no claim about built-in retry.
• Static analysis over-confidence — @mixin improves IDE resolution but is not runtime validation. Malformed or drifted UPS payloads remain possible; keep validation at the boundary and never treat PHPStan green as behavioral correctness.
• Composer resolution failure on hosts below the new floor — a safe, build-time failure, but plan the rollout so it doesn't surprise CI.
• Inheritance breakage if internal code extends package classes and the level-10 docblocks tightened a signature.

Ramp-up A Laravel-fluent developer can integrate in under a day: publish config, set credentials, make a rate call. The real ramp-up cost is UPS account provisioning, sandbox access approval, and understanding rate/ship payload semantics — measured in days, not hours. The @mixin work directly reduces this: typed facade returns give autocomplete and inline signature help, eliminating the "read the source to find out what comes back" tax that previously dominated first-integration time for teams using PhpStorm or PHPStan.

Recommendation Adopt v5.0.0 only if you are on, or imminently moving to, Laravel 13 / PHP 8.5; otherwise pin ^4.1 and revisit. When you do adopt, fold the change into an existing static-analysis ratchet rather than a standalone initiative, and track both the maintainer's release cadence and UPS's published API sunset schedule as ongoing operational risks.