Migration guide for v4

PHP Version Requirement

chargebee-php now requires PHP >= 8.1.

Namespace Changes

• The namespace ChargeBee has been renamed to Chargebee.
• Models now follow the namespace use Chargebee\Resources\*; instead of use ChargeBee\ChargeBee\Models\*;.

Client Initialization Changes

The way to initialize the Chargebee client has changed.

Before:

use ChargeBee\ChargeBee\Models\Environment;  
Environment::configure("{site}", "{site_api_key}"); 

Now:

use Chargebee\ChargebeeClient;
$chargebee = new ChargebeeClient([
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);

Method Binding in ChargebeeClient

Users no longer need to import individual classes for operations.

Before:

use ChargeBee\ChargeBee\Environment;
use ChargeBee\ChargeBee\Models\Customer;
Environment::configure("{site}", "{site_api_key}");
$result = Customer::retrieve("{customer-id}");

Now:

use Chargebee\ChargebeeClient;
$chargebee = new ChargebeeClient([
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$response = $chargebee->customer()->retrieve("{customer-id}");

Response Changes

The response will no longer return a global Result class; instead, it returns a specific response class for each action.

Before:

$customerResponse     = Customer::retrieve("{customer-id}"); 
$subscriptionResponse = Subscription::retrieve("{customer-id}");

echo get_class($customerResponse) . "\n";
echo get_class($subscriptionResponse) . "\n";

Output:

ChargeBee\ChargeBee\Result
ChargeBee\ChargeBee\Result

Now:

$customerResponse     = $chargebee->customer()->retrieve("{customer-id}"); 
$subscriptionResponse = $chargebee->subscription()->retrieve("{subs-id}");

echo get_class($customerResponse) . "\n";
echo get_class($subscriptionResponse) . "\n";

Output:

Chargebee\Responses\CustomerResponse\RetrieveCustomerResponse
Chargebee\Responses\SubscriptionResponse\RetrieveSubscriptionResponse

Previously, response properties in Chargebee were accessed using method calls (e.g., $customer = $response->customer();). In the updated version, response properties are now accessed directly as object properties (e.g., $customer = $response->customer;).

Input Parameter Changes

Input parameters have changed from camelCase to snake_case.

Before:

$result = Subscription::createWithItems("{customer-id}", array(
    "subscriptionItems" => array(
        array(
            "itemPriceId" => "day-pass-USD",
            "unitPrice" => 100
        ),
        array(
            "itemPriceId" => "basic-USD",
            "billingCycles" => 2,
            "quantity" => 1
        )
    )
));

Now:

$result = $chargebee->subscription()->createWithItems("{customer-id}", [
    "subscription_items" => [
        [
            "item_price_id" => "day-pass-USD",
            "unit_price" => 100
        ],
        [
            "item_price_id" => "basic-USD",
            "billing_cycles" => 2,
            "quantity" => 1
        ]
    ]
]);

Model class properties changes:

Properties of the model class have been changed from camelCase to snake_case.

Before:

$result = Customer::retrieve("{customer-id}");
$customer = $result->customer();
$firstName = $customer->firstName();

Now:

$result = $chargebee->customer()->retrieve("{customer-id}");
$customer = $result->customer;
$firstName = $customer->first_name;

List API Filters Changes:

The way to pass filters in list APIs has been updated.

Before:

$result = Subscription::all([
    "status[in]" => ["cancelled"],
    "limit" => 2,
]);

Now:

$result = $chargebeeClient->subscription()->all([
    "status" => ["in" => ["cancelled"]],
    "limit" => 2,
]);

Before:

$result = Subscription::all([
    "id[is]" => "{subscription-id}"
]);

Now:

$result = $chargebee->subscription()->all([
    "id" => ["is" => "{subscription-id}"]
]);