Use the following guide to assist in the upgrade process of the easypost-php library between major versions.
- Upgrading from 6.x to 7.0
- Upgrading from 5.x to 6.0
- Upgrading from 4.x to 5.0
- Upgrading from 3.x to 4.0
With the introduction of PHP 8.3, support for PHP 7.4 has been dropped. This library now requires PHP 8.0 or greater.
The library previously had type hints available via docstrings. With PHP 8.0+ support, the library now has type declarations for every function parameter and return value. You will want to double check that the types passed to each function match the expectations to avoid TypeErrors being thrown at runtime. Docstrings have been updated to match and assist IDEs in this process. You may notice some changes in what was expected before and the corrected types now. We've made every attempt to retain where possible the previous values or loose possible options to allow for the maximum backwards compatibility.
EasyPost now offers Carbon Neutral shipments by default for free! Because of this, there is no longer a need to specify if you want to offset the carbon footprint of a shipment. The withCarbonOffset parameter of the create, buy, and regenerateRates shipment functions have been removed as a result. This is a high-impact change for those using EndShippers as the function interfaces have changed. You will need to inspect the callsites to create and buy shipments to ensure that the EndShipper parameter is being passed in the correct place now that the withCarbonOffset parameter has been removed.
The create_and_buy Batch endpoint has been deprecated and has thus been removed from the library. The proper flow is to create a batch first and buy it separately with two API calls.
The updateEmail function of the ReferralCustomer service mistakenly had the email parameter first when it should have had userId first. This change has been made to ensure that every function that accepts an ID always has the ID come first. If you use this function, you will simply need to swap the order of the two parameters.
NOTICE: v6 is deprecated.
With the introduction of PHP 8.2, support for PHP 7.3 has been dropped. This library now requires PHP 7.4 or greater.
This library is now thread-safe with the introduction of a new EasyPostClient object. Instead of defining a global API key that all requests use, you create an EasyPostClient object and pass your API key to it. You then call your desired functions against a "service" which coincide with EasyPost objects:
// Old method
\EasyPost\EasyPost::setApiKey($_ENV['EASYPOST_API_KEY']);
$shipment = \EasyPost\Shipment::create(['data' => 'here']);
// New method
$client = new EasyPostClient(getenv('EASYPOST_API_KEY'));
$shipment = $client->shipment->create(['data' => 'here']);All instance methods are now static with the exception of lowestRate as these make API calls and require the client object (EasyPost objects do not contain an API key to make API calls with).
Previously used ->save() instance methods are now static update() functions where you specify first the ID of the object you are updating and second, the parameters that need updating.
Functions no longer accept an API key as an optional parameter. If you need per-function API key changes, create a new Client object and call the function on the new client that uses the API key you need.
We previously had a mix of camelCase and snake_case function and parameter names in this library. These have all been corrected to only use camelCase. Things like lowestRate, allApiKeys, etc have changed.
The Referral class is now called ReferralCustomer to match our documentation and API.
Occurances of smartrate are now smartRate and Smartrate are now SmartRate to match the documentation and API expectations.
Introduced ~2 dozen new exception types that extend from either ApiException or EasyPostException.
New ApiExceptions (extends EasyPostException):
EasyPost/Exception/Api/ApiExceptionEasyPost/Exception/Api/EncodingExceptionEasyPost/Exception/Api/ExternalApiExceptionEasyPost/Exception/Api/ForbiddenExceptionEasyPost/Exception/Api/GatewayTimeoutExceptionEasyPost/Exception/Api/HttpExceptionEasyPost/Exception/Api/InternalServerExceptionEasyPost/Exception/Api/InvalidRequestExceptionEasyPost/Exception/Api/JsonExceptionEasyPost/Exception/Api/MethodNotAllowedExceptionEasyPost/Exception/Api/NotFoundExceptionEasyPost/Exception/Api/PaymentExceptionEasyPost/Exception/Api/RateLimitExceptionEasyPost/Exception/Api/RedirectExceptionEasyPost/Exception/Api/ServiceUnavailableExceptionEasyPost/Exception/Api/TimeoutExceptionEasyPost/Exception/Api/UnauthorizedExceptionEasyPost/Exception/Api/UnknownApiException
New EasyPostExceptions (extends \Exception):
/EasyPost/Exception/General/FilteringException/EasyPost/Exception/General/InvalidObjectException/EasyPost/Exception/General/InvalidParameterException/EasyPost/Exception/General/MissingParameterException/EasyPost/Exception/General/SignatureVerificationException
ApiExceptions will behave like the previous EasyPostException class did. They will include a message, errors, code, httpStatus and httpBody. This class extends the more generic EasyPostException which only contains a message, used for exceptions thrown directly from this library
The ecode property of an ApiException is now just code
Functions that previously returned true now return void as there is no response body from the API (eg: fundWallet, deletePaymentMethod, updateEmail, createList)
The results of calling allApiKeys is no longer double wrapped with the mode of the API key (these are still accessible inside of each object)
The validateWebhook, getLowestSmartRate, and receive functions are now under EasyPost\Util\Util as they do not make any API calls and do not need the associated client object.
The receive function previously in the namespace of Event is now called receiveEvent since it has been relocated to the generic Util namespace.
NOTICE: v5 is deprecated.
- Default Timeouts for HTTP Requests
- Removal of
allmethod from theOrder,CustomsInfo, andCustomsItemObjects - Removal of
get_ratesShipment Method
Likelihood of Impact: High
PHP 7.3 Required
easypost-php now requires PHP 7.3 or greater.
Dependencies
All dependencies had minor version bumps.
Likelihood of Impact: Medium
Default timeouts for all HTTP requests are now set to 30 seconds for connection and 60 seconds for requests. If you require longer timeouts, you can set them by overriding the defaults:
// Timeouts are in milliseconds
EasyPost::setConnectTimeout(30000);
EasyPost::setResponseTimeout(60000);Likelihood of Impact: Medium
The /all endpoint for the Order, CustomsInfo, and CustomsItem objects are not paginated and have therefore been removed from the library.
Likelihood of Impact: Medium
The HTTP method used for the get_rates endpoint at the API level has changed from POST to GET and will only retrieve rates for a shipment instead of regenerating them. A new /rerate endpoint has been introduced to replace this functionality; In this library, you can now call the Shipment::regenerate_rates method to regenerate rates. Due to the logic change, the get_rates method has been removed since a Shipment inherently already has rates associated.
Likelihood of Impact: Low
There is no /all endpoint for the Parcel object. This function was removed as it was unusable.
NOTICE: v4 is deprecated.
Likelihood of Impact: High
All POST and PUT request bodies are now JSON encoded instead of form-encoded. You may see subtle inconsistencies to how certain data types were previously sent to the API. We have taken steps to mitigate and test against these edge cases.
Likelihood of Impact: Low
Dependencies
All dependencies had their patch versions bumped.