Skip to content

Commit

Permalink
Merge pull request #326 from EasyPost/v7.0.0
Browse files Browse the repository at this point in the history
chore: prepare v7.0.0 for release
  • Loading branch information
Justintime50 authored Dec 1, 2023
2 parents 6a08b4a + be97c0b commit e45d11f
Show file tree
Hide file tree
Showing 6 changed files with 61 additions and 22 deletions.
9 changes: 7 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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)
Expand Down Expand Up @@ -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)
Expand Down
62 changes: 49 additions & 13 deletions UPGRADE_GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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:

Expand All @@ -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`.

Expand Down Expand Up @@ -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.

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand All @@ -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

Expand Down
2 changes: 1 addition & 1 deletion composer.json
Original file line number Diff line number Diff line change
@@ -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",
Expand Down
2 changes: 1 addition & 1 deletion lib/EasyPost/Constant/Constants.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 2 additions & 4 deletions lib/EasyPost/Service/ReferralCustomerService.php
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion test/EasyPost/ReferralCustomerTest.php
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand Down

0 comments on commit e45d11f

Please sign in to comment.