Merge pull request #326 from EasyPost/v7.0.0

chore: prepare v7.0.0 for release

CHANGELOG.md

@@ -1,15 +1,18 @@
 # CHANGELOG
 
-## Next Major Release
+## 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
-- 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)
@@ -74,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)

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,15 +80,15 @@ 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.
 
 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.
 
-## 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
 

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",

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 = '[email protected]';
 
     // Validation

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

test/EasyPost/ReferralCustomerTest.php

@@ -105,8 +105,8 @@ public function testUpdateEmail(): void
 
         try {
             self::$client->referralCustomer->updateEmail(
+                $referralUsers['referral_customers'][0]['id'],
                 '[email protected]',
-                $referralUsers['referral_customers'][0]['id']
             );
             $this->assertTrue(true);
         } catch (\Exception $exception) {