Download the PHP package shipstream/ups-rest-php-sdk without Composer

UPS REST PHP SDK

A PHP SDK for the UPS REST API, brought to you by ShipStream.

Installation

Note: The latest version is compatible only with PHP 8.x. For PHP 7.4 support, please append the ^1.0 version constraint to the above command.

Basic Usage

Create a UPS Client instance using a configuration object:

The Client object contains methods for every endpoint available in the UPS OpenAPI definition files with PHPDoc comments that describe the parameters and return types, as well as any thrown exceptions. Method names for each endpoint is based on the operationId property of the OpenAPI specification.

Here's an example using the Tracking API:

Authentication

Client Credentials

Using Client Credentials flow works out of the box and requires no additional steps as the access token generation and refresh is handled internally.

Authorization Code

To start using the Authorization Code flow set grant_type config to Config::GRANT_TYPE_AUTHORIZATION_CODE, then call the authorizeClient endpoint and redirect the user to the returned login URL:

The user will be redirected back to your app after login with the authorization code that will be used to generate an access token:

The access token refresh will be handled internally so long that the refresh token is still valid. You can check if the client is authenticated at any time by calling $client->getAccessToken() which attempts to retrieve the access token from the cache and refresh it if it has already expired, otherwise it throws an AuthenticationException.

Preventing race conditions when refreshing expired tokens

When multiple PHP processes attempt to call an endpoint while the access token is expired, a race condition may occur resulting in one process refreshing the token successfully, while the other processes will fail with Invalid Refresh Token or a similar error. To help prevent this, locking can be enabled by passing a third argument to Client factory that can be any class implementing the FileAccessTokenLock is provided for convenience, it takes a writable file path and uses it for locking. Example:

Caching Access Tokens

The library uses an in-memory cache for access tokens by default which is useful when doing quick tests, but for a production environment you'd want to use something like Redis or a filesystem cache to avoid doing round trips to generate an access token on every request. To achieve this, the Client factory accepts a second parameter which can be any object that implements the AccessTokenCache interface. For example, a Redis implementation could look like this:

Using a custom HTTP Client

If you wish to customize how HTTP requests are made, perhaps for logging or to add additional headers, the Client factory supports a third parameter that can be any HTTP Client that implements the PSR-18 standard. E.g.:

Note that the HTTP Client must not throw exceptions for 4xx and 5xx responses, as those should be handled by the SDK.

Development

The classes under the ShipStream\Ups\Api namespace are all generated using janephp.

Run the generate.sh script to regenerate the classes when needed.