From 7d45d39ae84db7b829b0fcf65ac36c2857b5afc2 Mon Sep 17 00:00:00 2001 From: Justintime50 <39606064+Justintime50@users.noreply.github.com> Date: Thu, 30 Nov 2023 14:08:40 -0700 Subject: [PATCH 1/3] chore: prepare v7.0.0 for release --- CHANGELOG.md | 5 +- UPGRADE_GUIDE.md | 62 +++++++++++++++---- composer.json | 2 +- lib/EasyPost/Constant/Constants.php | 2 +- .../Service/ReferralCustomerService.php | 6 +- 5 files changed, 56 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f306913..e53de731 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,15 +1,16 @@ # CHANGELOG -## Next Major Release +## v7.0.0 (2023-12-01) - Drops support for PHP 7.4 - Adds support for PHP 8.3 - Persists the HTTP client inside of the `EasyPostClient` via the `httpClient` property to reduce memory consumption on consecutive requests -- Adds type hints for parameters and return values throughout the library, corrects docstring hints where necessary +- Adds type declarations for parameters and return values throughout the library, corrects docstrings to match - Removed `withCarbonOffset` parameter from `create`, `buy`, and `regenerateRates` functions of the Shipment service as EasyPost now offers Carbon Neutral shipments by default for free - Fixes a bug where the original filtering criteria of `all` calls wasn't passed along to `getNextPage` calls. Now, these are persisted via a `_params` key on response objects locally - Removes the undocumented `createAndBuy` function from the `Batch` service. The proper usage is to create a batch first and buy it separately - Renames `primaryOrSecondary` to `priority` to match the API name for the parameter +- Corrects the order of the `userId` and `email` parameters in the `updateEmail` function of the ReferralCustomer service to match the rest of the library where IDs are always the first parameter - Fix various bugs throughout the library ## v6.9.1 (2023-11-20) diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index e3035ac6..493aad0d 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -2,12 +2,48 @@ 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-6x-to-70) - [Upgrading from 5.x to 6.0](#upgrading-from-5x-to-60) - [Upgrading from 4.x to 5.0](#upgrading-from-4x-to-50) - [Upgrading from 3.x to 4.0](#upgrading-from-3x-to-40) +## Upgrading from 6.x to 7.0 + +### 7.0 High Impact Changes + +- [Drop Support for PHP 7.4](#70-drop-support-for-php-74) +- [Type Declarations Added](#70-type-declarations-added) +- [Carbon Offset Removed](#70-carbon-offset-removed) + +### 7.0 Low Impact Changes + +- [createAndBuy Batch Function Removed](#70-createandbuy-batch-function-removed) +- [updateEmail Parameter Order Corrected](#70-updateemail-parameter-order-corrected) + +### 7.0 Drop Support for PHP 7.4 + +With the introduction of PHP 8.3, support for PHP 7.4 has been dropped. This library now requires PHP 8.0 or greater. + +### 7.0 Type Declarations Added + +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 `TypeError`s 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. + +### 7.0 Carbon Offset Removed + +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. + +### 7.0 createAndBuy Batch Function 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. + +### 7.0 updateEmail Parameter Order Corrected + +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. + ## Upgrading from 5.x to 6.0 +**NOTICE:** v6 is deprecated. + ### 6.0 High Impact Changes - [Drop Support for PHP 7.3](#60-drop-support-for-php-73) @@ -20,11 +56,11 @@ Use the following guide to assist in the upgrade process of the `easypost-php` l - [Changed Function Return Types](#60-changed-function-return-types) - [Moved Functions](#60-moved-functions) -## 6.0 Drop Support for PHP 7.3 +### 6.0 Drop Support for PHP 7.3 With the introduction of PHP 8.2, support for PHP 7.3 has been dropped. This library now requires PHP 7.4 or greater. -## 6.0 New EasyPostClient Object +### 6.0 New EasyPostClient Object 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: @@ -44,7 +80,7 @@ Previously used `->save()` instance methods are now static `update()` functions 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. -## 6.0 Corrected Naming Conventions +### 6.0 Corrected Naming Conventions 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. @@ -52,7 +88,7 @@ The `Referral` class is now called `ReferralCustomer` to match our documentation Occurances of `smartrate` are now `smartRate` and `Smartrate` are now `SmartRate` to match the documentation and API expectations. -## 6.0 Improved Exceptions +### 6.0 Improved Exceptions Introduced ~2 dozen new exception types that extend from either `ApiException` or `EasyPostException`. @@ -89,13 +125,13 @@ ApiExceptions will behave like the previous EasyPostException class did. They wi The `ecode` property of an `ApiException` is now just `code` -## 6.0 Changed Function Return Types +### 6.0 Changed Function Return Types 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) -## 6.0 Moved Functions +### 6.0 Moved Functions 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. @@ -121,7 +157,7 @@ The `receive` function previously in the namespace of `Event` is now called `rec - [Removal of all Method from the Parcel Object](#50-removal-of-all-method-from-the-parcel-object) -## 5.0 Updating Dependencies +### 5.0 Updating Dependencies Likelihood of Impact: High @@ -133,7 +169,7 @@ easypost-php now requires PHP 7.3 or greater. All dependencies had minor version bumps. -## 5.0 Default Timeouts for HTTP Requests +### 5.0 Default Timeouts for HTTP Requests Likelihood of Impact: Medium @@ -145,19 +181,19 @@ EasyPost::setConnectTimeout(30000); EasyPost::setResponseTimeout(60000); ``` -## 5.0 Removal of all() Method from the Order, CustomsInfo, and CustomsItem Objects +### 5.0 Removal of all() Method from the Order, CustomsInfo, and CustomsItem Objects 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. -## 5.0 Removal of get_rates() Shipment Method +### 5.0 Removal of get_rates() Shipment Method 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. -## 5.0 Removal of all() Method from the Parcel Object +### 5.0 Removal of all() Method from the Parcel Object Likelihood of Impact: Low @@ -175,13 +211,13 @@ There is no `/all` endpoint for the Parcel object. This function was removed as - [Updating Dependencies](#40-updating-dependencies) -## 4.0 JSON Encoded Bodies +### 4.0 JSON Encoded Bodies 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. -## 4.0 Updating Dependencies +### 4.0 Updating Dependencies Likelihood of Impact: Low diff --git a/composer.json b/composer.json index da5178a8..0e6e00c7 100644 --- a/composer.json +++ b/composer.json @@ -1,7 +1,7 @@ { "name": "easypost/easypost-php", "description": "EasyPost Shipping API Client Library for PHP", - "version": "6.9.1", + "version": "7.0.0", "keywords": [ "shipping", "api", diff --git a/lib/EasyPost/Constant/Constants.php b/lib/EasyPost/Constant/Constants.php index d79d18c4..dab7c916 100644 --- a/lib/EasyPost/Constant/Constants.php +++ b/lib/EasyPost/Constant/Constants.php @@ -11,7 +11,7 @@ abstract class Constants const BETA_API_VERSION = 'beta'; // Library constants - const LIBRARY_VERSION = '6.9.1'; + const LIBRARY_VERSION = '7.0.0'; const SUPPORT_EMAIL = 'support@easypost.com'; // Validation diff --git a/lib/EasyPost/Service/ReferralCustomerService.php b/lib/EasyPost/Service/ReferralCustomerService.php index 22d047a0..98c7dffe 100644 --- a/lib/EasyPost/Service/ReferralCustomerService.php +++ b/lib/EasyPost/Service/ReferralCustomerService.php @@ -59,14 +59,12 @@ public function create(mixed $params = null): mixed /** * Update an referral email. * - * @param string $email * @param string $userId + * @param string $email * @return void */ - public function updateEmail(string $email, string $userId): void + public function updateEmail(string $userId, string $email): void { - // TODO: Swap the order of these params so ID comes first to match all other functions - // this will be a breaking change and must be done when the next major release happens $wrappedParams = [ 'user' => [ 'email' => $email From 25e53840bf1f4c6f1f36da1e75cfbb3a980e85f3 Mon Sep 17 00:00:00 2001 From: Justintime50 <39606064+Justintime50@users.noreply.github.com> Date: Thu, 30 Nov 2023 14:09:57 -0700 Subject: [PATCH 2/3] docs: add links to upgrade guide in CHANGELOG --- CHANGELOG.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index e53de731..cfcfa237 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## v7.0.0 (2023-12-01) +Upgrading major versions of this project? Refer to the [Upgrade Guide](UPGRADE_GUIDE.md). + - Drops support for PHP 7.4 - Adds support for PHP 8.3 - Persists the HTTP client inside of the `EasyPostClient` via the `httpClient` property to reduce memory consumption on consecutive requests @@ -75,6 +77,8 @@ ## v6.0.0 (2023-01-05) +Upgrading major versions of this project? Refer to the [Upgrade Guide](UPGRADE_GUIDE.md). + - Release final version of v6 that contains all the changes in the `v6.0.0-rc1` below ## v6.0.0-rc1 (2022-12-15) From be97c0b5b2f8f7d409fedfc0d27a6f7371b5fef4 Mon Sep 17 00:00:00 2001 From: Justintime50 <39606064+Justintime50@users.noreply.github.com> Date: Thu, 30 Nov 2023 14:10:44 -0700 Subject: [PATCH 3/3] fix: test --- test/EasyPost/ReferralCustomerTest.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/EasyPost/ReferralCustomerTest.php b/test/EasyPost/ReferralCustomerTest.php index 2d9d83be..7411675a 100644 --- a/test/EasyPost/ReferralCustomerTest.php +++ b/test/EasyPost/ReferralCustomerTest.php @@ -105,8 +105,8 @@ public function testUpdateEmail(): void try { self::$client->referralCustomer->updateEmail( + $referralUsers['referral_customers'][0]['id'], 'email@example.com', - $referralUsers['referral_customers'][0]['id'] ); $this->assertTrue(true); } catch (\Exception $exception) {