PHPackages shipstream/fedex-rest-sdk - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. shipstream/fedex-rest-sdk ActiveLibrary[API Development](/categories/api) shipstream/fedex-rest-sdk ========================= A PHP SDK for FedEx's REST API v1.4.0(3mo ago)108.9k↓32.7%2[1 issues](https://github.com/ShipStream/fedex-rest-php-sdk/issues)Apache-2.0PHPCI passing Since Jun 5Pushed 3mo ago4 watchersCompare [ Source](https://github.com/ShipStream/fedex-rest-php-sdk)[ Packagist](https://packagist.org/packages/shipstream/fedex-rest-sdk)[ RSS](/packages/shipstream-fedex-rest-sdk/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (8)Dependencies (10)Versions (11)Used By (0) FedEx SDK for PHP ----------------- [](#fedex-sdk-for-php) This is a PHP SDK for working with [FedEx's REST APIs](https://developer.fedex.com/api/en-us/catalog.html). The SDK is autogenerated from FedEx's OpenAPI models (with substantial model refactoring) and built on top of [Saloon](https://docs.saloon.dev/). Warning This SDK is licenesed under Apache 2.0 and all disclaimers of liability apply. We will try to follow Semver versioning practices and avoid publishing changes which affect backwards-compatibility. However, always test new versions thoroughly before putting them into production! If you find any problems, we'd really appreciate it if you [submitted an issue](https://github.com/ShipStream/fedex-rest-php-sdk/issues/new). Installation ------------ [](#installation) `composer require shipstream/fedex-rest-sdk` Quickstart ---------- [](#quickstart) The `FedEx` class is the jumping-off point for accessing all segments of the FedEx API. To get started, instantiate an instance of the FedEx class with your client ID and secret key: ``` use ShipStream\FedEx\FedEx; $connector = new FedEx( clientId: 'asdf1234.....', clientSecret: 'qwertyuiop1234567890.....' ); ``` To access a particular set of endpoints, get an instance of the relevant resource collection class from the connector: ``` $api = $connector->postalCodeValidationV1(); $response = $api->validatePostal( new FullSchemaValidatePostal( carrierCode: 'FDXG', countryCode: 'US', stateOrProvinceCode: 'NY', postalCode: '10001', shipDate: '2024-05-20', ) ); // To get the raw response JSON: $json = $response->json(); // To get the response data as a DTO: $dto = $response->dto(); ``` It is recommended to use named parameters with DTOs, as the order of parameters could change when the SDK is updated. To figure out which DTO(s) need(s) to be passed to a particular endpoint method, use your editor to inspect the method's arguments: [![](img/dto-hint.png)](img/dto-hint.png) ### Configuration options [](#configuration-options) The `FedEx` class constructor accepts the following arguments: - `clientId`: The OAuth client ID from the developer console. Required. - `clientSecret`: The OAuth client secret from the developer console. Required. - `endpoint`: An `ShipStream\FedEx\Enums\Endpoint` value, either `Endpoint::PROD` or `Endpoint::SANDBOX`. Defaults to `Endpoint::PROD`. - `childKey`: If you're working with child credentials, this is the child's OAuth client ID. Optional. - `childSecret`: The corresponding secret key for the child client ID, if one is provided. Optional. - `proprietaryChild`: Specifies if the child credentials (if any) are for a proprietary parent/child relationship. Default `false`. - `tokenCache`: An implementation of the [`TokenCache`](https://github.com/ShipStream/fedex-rest-php-sdk/blob/main/src/Contracts/TokenCache.php) interface. This is used to cache access tokens, so that a new one isn't retrieved on every request. Defaults to the [`MemoryCache`](https://github.com/ShipStream/fedex-rest-php-sdk/blob/main/src/Auth/MemoryCache.php) implementation. - `transactionIdGenerator`: A closure that takes a `PendingRequest` and returns a `string`, which will be used to inject `x-customer-transaction-id` header values into requests. Optional. Saloon features --------------- [](#saloon-features) Since this SDK is built on top of [Saloon](https://docs.saloon.dev/), it inherits Saloon's many useful built-in features, such as [automatic request retries](https://docs.saloon.dev/digging-deeper/retrying-requests), [easy request debugging](https://docs.saloon.dev/the-basics/debugging), [middleware](https://docs.saloon.dev/digging-deeper/middleware), [request pools](https://docs.saloon.dev/digging-deeper/concurrency-and-pools), and more. Contributing ------------ [](#contributing) We welcome any and all contributions! There are a few ways you can contribute to this project: - If you find a bug or run into an issue getting set up, please search the [existing issues](https://github.com/shipstream/fedex-rest-php-sdk/issues), and [open a new issue](https://github.com/shipstream/fedex-rest-php-sdk/issues/new) if you don't find anything that matches the problem you're having. - Browse through the existing issues and help people out! - Submit a [pull request](https://github.com/shipstream/fedex-rest-php-sdk/pull) if you find an issue and want to fix it yourself! ### Issues [](#issues) Before submitting an issue, please make sure you search the existing issues to see if anyone else has already reported and/or solved the same problem you're reporting. If you don't find anything that matches your problem, submit a new issue. Please make sure to include: - The version of the library you're running (you can find this in your `composer.json` file) - Your complete code, with any credentials removed - A thorough description of the problem - Steps to reproduce the problem ### Pull Requests [](#pull-requests) We welcome PRs! If you want to submit a PR, we encourage you to first submit an issue describing the change you want to make. That way, you don't end up in the frustrating situation of putting a lot of work into a PR only to have us reject it because it's not a change/feature we want to support. Once you're ready to start work on your PR, please check out the [SDK Design](#sdk-design) section below to make sure your changes conform to the overall design of this library. Before submitting a PR for review, please ensure the test suite is working with `composer test` and that the code is linted using `composer lint`. ### Testing [](#testing) To get the tests up and running, you'll need a set of FedEx REST API sandbox credentials. Since FedEx has a fairly complete sandbox environment, we use their actual sandbox instead of mocking responses. Once you have credentials, copy `phpunit.dist.xml` to `phpunit.xml` and fill in the `CLIENT_ID` and `CLIENT_SECRET` environment variables with your test credentials. Now you should be able to run the test suite! Since we are using the actual sandbox API instead of mocking, **make sure you use the `Endpoint::SANDBOX` endpoint in all tests!** FedEx has separate production and sandbox credentials, so you will likely just get an error if you specify the production endpoint, but if you accidentally put production creds in `phpunit.xml` (see below) you will be making real API requests during testing. SDK Design ---------- [](#sdk-design) This SDK is (almost) entirely autogenerated from FedEx's OpenAPI model files, using [highsidelabs/saloon-sdk-autogenerator](https://github.com/highsidelabs/saloon-sdk-autogenerator). As with most big multi-file OpenAPI specifications, the FedEx spec took quite a bit of massaging to get into a format that worked well with an autogenerator. We put a lot of work into making sure that the generation process, from downloading the model files to the generated code, is idempotent and reliable. There are three major steps to building this library: 1. Downloading the raw OpenAPI schema files from FedEx 2. Combining and editing those files to make their formatting more consistent and usable 3. Generating the final code from the modified OpenAPI schema files The details of each step are described below. Each of these steps is run via its own CLI command, defined in `bin/console`. The CLI commands accept the following options, both of which can accept multiple values: - `--schema`: The names of the schemas to apply the command to, by their hyphenated names as defined in [`resources/apis.json`](#apisjson). - `--schema-version`: The schema versions to apply the command to, by their version codes as defined in [`resources/apis.json`](#apisjson). So, to download `v1` of the `authorization` and `pickup-request` APIs, you can run: ``` $ php bin/console schema:download \ --schema authorization --schema pickup-request \ --schema-version 1 ``` ### Downloading schemas: `php bin/console schema:download` [](#downloading-schemas-php-binconsole-schemadownload) This step is the simplest of the three. The `resources/apis.json` is the primary source of truth for what all the different segments of FedEx's REST API are, what their names are, and the URLs of their OpenAPI schema files. Some API segments (for instance, the Service Availability API) are composed of multiple OpenAPI model files. The `apis.json` file is also built to support multiple versions of the same API segment, in case FedEx later releases new versions of these APIs. There is a more complete description of the `apis.json` file [below](#apisjson). Downloaded OpenAPI models are placed in `resources/models/.raw/`. Once the models for a particular API segment have been downloaded, they can then be refactored. ### Refactoring schemas: `php bin/console schema:refactor` [](#refactoring-schemas-php-binconsole-schemarefactor) A wide variety of refactoring processes are run on the raw schemas to get them ready to be used in the following step: code generation. A broad overview of the refactoring steps: - **Combine raw schemas:** If a given API segment has multiple OpenAPI model files, they are combined into a single file. Routes, methods, and component schemas are aggregated across original OpenAPI files, and combined into a single model object. So far, we have not found any OpenAPI model files from the same API segment with overlapping routes, nor conflicting component schemas, so we're not handling those cases. - **Clean combined schema:** There are often inconsistencies, missing elements, and duplicated or unnecessary component schemas in the OpenAPI models, so this step takes care of those issues. Some specific current steps that are taken: - Filling in missing `404` and `429` response schemas - Removing unnecessary `allOf` and `oneOf` definitions in requests, responses, and component schemas - Setting the types of schemas and properties that are missing explicit types - Flattening multi-level `$ref`s, where a component or property is a `$ref` to another `$ref`. - Deduplicating component schemas by comparing properties and requirements, and combining the component schemas whenever possible - **Apply manual modifications:** Certain schema changes need to be made manually, because they are too specific or too cumbersome to make using code. These modifications are defined in the `resources/modifications.json` file, which is explained more thoroughly [below](#modificationsjson). Once refactoring is complete, the finalized OpenAPI model file is saved to `resources/models//.json`. These files *are* version-controlled, unlike the raw models, because having them available to everyone makes it easier to reason about the autogeneration process. ### Generating code: `php bin/console schema:generate` [](#generating-code-php-binconsole-schemagenerate) Finally, the code is generated from the finalized OpenAPI models. We use `highsidelabs/saloon-sdk-generator` for this, which handles most of the heavy lifting. All the code in the `ShipStream\FedEx\Api` namespace is autogenerate, so *do not* edit any of that code directly! Any changes in that namespace will be overridden the next time the library is generated, so if you want to make a change to any of that code, that change will have to be made by either a) modifying/extending the generator code, or b) via the [`modifications.json`](#modificationsjson) file. The `config.json` file provides some basic configuration parameters to the autogenerator, and the files in `src/Generator/Generators` override `highsidelabs/saloon-sdk-generator`'s default file generators to make minor modifications. There are several different generator files that can be overridden – you can see all of them [here](https://github.com/highsidelabs/saloon-sdk-generator/tree/master/src/Generators). If you have questions about how to go about extending or modifying the generator files, please [open an issue](https://github.com/highsidelabs/saloon-sdk-generator/issues) in the `highsidelabs/saloon-sdk-generator` repository. ### Generator control files [](#generator-control-files) #### `apis.json` [](#apisjson) This file is the source of truth for all API segments, names, versions, and upstream OpenAPI model URLs. The top-level object keys (e.g., `authorization`, `address-validation`, etc) are the names that are used to reference and retrieve a particular API segment throughout the codebase. Each top-level sub-object is the definition for an API segment. It contains a human-readable `name`, and an array of version definitions. Each version consists of a `version` code (e.g., `1`), and a `url` key which is either a string or an array of strings, depending on whether or not FedEx defines the API segment via a single OpenAPI model file or multiple model files. #### `modifications.json` [](#modificationsjson) This file contains manually-defined OpenAPI model modifications. These modifications are applied after all other model refactoring steps. Each modification definition has two or three elements: - `path`, the dot-separated JSON path to the value to be modified in the model file - `action`, which is one of the following: - `replace`: Replaces the value at `path` with the value in the `value` key (see below) - `merge`: Combines the value at `path` with the value in the `value` key - `delete`: Removes the value at `path` entirely, along with the final key in `path`, from the model - `value`, the value to merge/replace. Not required if `action` is `delete` Authors ------- [](#authors) This SDK was built in collaboration with [Jesse Evers](https://github.com/jlevers) of [Highside Labs](https://github.com/highsidelabs). ### Health Score 46 — FairBetter than 93% of packages Maintenance79 Regular maintenance activity Popularity33 Limited adoption so far Community15 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 59.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~87 days Recently: every ~133 days Total 8 Last Release 101d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/38738?v=4)[Colin Mollenhour](/maintainers/colinmollenhour)[@colinmollenhour](https://github.com/colinmollenhour) ![](https://www.gravatar.com/avatar/03f3b43533bd18c337ac4402910d4977dd0a327927d0a994cec096d8d3269205?d=identicon)[jlevers](/maintainers/jlevers) --- Top Contributors [![jlevers](https://avatars.githubusercontent.com/u/4974856?v=4)](https://github.com/jlevers "jlevers (78 commits)")[![bob2021](https://avatars.githubusercontent.com/u/8102829?v=4)](https://github.com/bob2021 "bob2021 (48 commits)")[![colinmollenhour](https://avatars.githubusercontent.com/u/38738?v=4)](https://github.com/colinmollenhour "colinmollenhour (5 commits)") ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/shipstream-fedex-rest-sdk/health.svg) ``` [![Health](https://phpackages.com/badges/shipstream-fedex-rest-sdk/health.svg)](https://phpackages.com/packages/shipstream-fedex-rest-sdk) ``` ### Alternatives [skagarwal/google-places-api Google Places Api 1913.0M8](/packages/skagarwal-google-places-api)[saloonphp/laravel-plugin The official Laravel plugin for Saloon 805.7M125](/packages/saloonphp-laravel-plugin)[saloonphp/rate-limit-plugin Handle rate limits beautifully in your Saloon API integrations or SDKs 201.3M44](/packages/saloonphp-rate-limit-plugin)[myoutdeskllc/salesforce-php salesforce library for php8+ 1560.8k](/packages/myoutdeskllc-salesforce-php)[sandorian/moneybird-api-php Moneybird API client for PHP 127.3k](/packages/sandorian-moneybird-api-php)[codebar-ag/laravel-docuware DocuWare integration with Laravel 1221.1k](/packages/codebar-ag-laravel-docuware) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)