- How do I install ptondereau/laravel-ups-api in a Laravel app?
- Install it with Composer using composer require ptondereau/laravel-ups-api. The package ships a service provider with Laravel auto-discovery, so no manual registration is normally needed. After installing, publish the package config file with php artisan vendor:publish and select the UPS package provider or tag. Then add your UPS credentials to your .env file.
- Which Laravel and PHP versions does laravel-ups-api v5 support?
- Version 5.0.0 re-baselines the supported matrix around Laravel 13 and PHP 8.5. If your application runs Laravel 10, 11, or 12 on PHP 8.2 through 8.4, you should stay on the 4.1.x line, because Composer will not resolve v5 for those platforms. Always confirm the exact minimums by reading the composer.json in the tagged release before planning an upgrade.
- How do I configure UPS credentials for this Laravel package?
- Credentials live in the publishable config file, which is populated from environment variables so secrets stay out of source control. The package authenticates against UPS using the OAuth client-credentials flow, so you will need a client ID, client secret, and your UPS account number. Point the config at the UPS sandbox endpoints while developing and switch to production values at deploy time. Keep separate credential sets per environment to avoid mixing test and live shipments.
- How do I get UPS shipping rates in Laravel with this package?
- Rates are handled by the dedicated Rate service class, which you call through its facade from a controller, service, or queued job. You pass the shipment details such as origin, destination, weight, and service options, and UPS returns the available rates and transit times. Because the package is a thin infrastructure adapter, it is best to wrap the call in your own class so you can cache quotes, apply markup, and handle failures consistently.
- Can I create UPS shipping labels from Laravel with this package?
- Yes, label creation is covered by the Shipping service, which handles the shipment request and returns the label data from UPS. In practice the blocker is rarely the code: you need a UPS account with the correct entitlements, plus approved sandbox access, before labels can be generated. Store returned label documents and tracking numbers in your own database rather than relying on UPS as the system of record.
- How do I track a UPS package in Laravel using this package?
- Use the Tracking service, passing the UPS tracking number to retrieve the current status and the scan event history. It fits naturally behind a scheduled job or a webhook-driven refresh so customer-facing tracking pages stay current without hammering the API. Because each tracking call is a live request to UPS, cache results briefly and handle upstream timeouts gracefully.
- Does the package support UPS address validation?
- Yes, address validation is exposed through its own Address service class and facade, letting you verify or normalize a street address before you create a shipment. Running validation up front reduces failed label requests and rejected deliveries. Treat the response as advisory: UPS may suggest corrections, and you should decide whether to auto-accept them or surface them to the user.
- How can I test UPS integration without hitting the live API?
- There is no documented built-in fake, so the usual approach is to point the config at the UPS sandbox using test credentials and to mock the facade or HTTP client in your automated tests. Credential provisioning and sandbox approval are the real friction points, not the library code, so request access early. Keep a small integration test suite that hits the sandbox separately from your fast unit tests.
- Does the package cache the UPS OAuth token or retry failed requests?
- The package authenticates with OAuth client credentials, but token caching and retry/backoff behavior for 429 and 5xx responses are not clearly documented, so verify both in the source before relying on them in production. A safe pattern is to wrap calls in queued jobs with your own retry and exponential backoff, and to catch exceptions at the boundary where you call the facade. Token handling matters at scale, since re-authenticating on every request adds latency and can trip UPS rate limits.
- How do I migrate from laravel-ups-api v4 to v5, and what breaks?
- Version 5.0.0 is a major release focused on platform currency and tighter type contracts, so treat it as an adoption rather than a routine bump. Confirm the new PHP and Laravel floors, upgrade the framework and PHP in an isolated pull request, then bump the package in a separate change where the diff is essentially composer.json and composer.lock. Run your test suite and PHPStan afterwards to capture the delta, since the new mixin annotations and stricter signatures can surface previously hidden type errors, and any code that extends or overrides package classes is at real risk.