README

Introduction

This is an easy-to-use API client for BigCommerce.

Installation

Install aligent/bigcommerce-api-client from packagist using composer: composer require aligent/bigcommerce-api-client.

Usage Examples

Trivial example of updating a product name:

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

$product = $api->catalog()->product(123)->get()->getProduct();
$product->name = 'Updated product name';
try {
    $api->catalog()->product($product->id)->update($product);
} catch (\Psr\Http\Client\ClientExceptionInterface $exception) {
    echo "Unable to update product: {$exception->getMessage()}";
}

Fetching all visible products (all pages of products):

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

$productsResponse = $api->catalog()->products()->getAllPages(['is_visible' => true]);

echo "Found {$productsResponse->getPagination()->total} products";

$products = $productsResponse->getProducts();

Example of updating a product variant

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

$productVariant = $api->catalog()->product(123)->variant(456)->get()->getProductVariant();
$productVariant->price = '12';

try {
    $api->catalog()->product($productVariant->product_id)->variant($productVariant->id)->update($productVariant);
} catch (\Psr\Http\Client\ClientExceptionInterface $exception) {
    echo "Unable to update product variant: {$exception->getMessage()}";
}

Example of creating a product variant

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

$productVariant = new \BigCommerce\ApiV3\ResourceModels\Catalog\Product\ProductVariant();
$productVariant->product_id = 123;
$productVariant->sku = "SKU-123";
//...

try {
    $api->catalog()->product($productVariant->product_id)->variants()->create($productVariant);
} catch (\Psr\Http\Client\ClientExceptionInterface $exception) {
    echo "Unable to create product variant: {$exception->getMessage()}";
}

API Design

There are three components to the library:

BigCommerce/Api - which represent the API endpoints and tries to mimic the layout of the documentation.
BigCommerce/ResourceModels - which represent the resources that are sent to and received from the API, for example a Product or an Order.
BigCommerce/ResponseModels - which represent the responses from the BigCommerce API.

For additional documentation, see the code documentation.

API Classes

To interact with the API, always start with the BigCommerce\ApiV3\Client class. All APIs can be accessed in two ways: with and without an ID.

If you are querying about a specific resource instance (e.g. Product 5), then you would use singular endpoint ( ->catalog()->product(5)), otherwise you would use the plural endpoint (i.e. ->catalog()->products()).

For example, suppose we want to find all the metafields for a brand with and id of 123. Our query is for a specific brand, but any metafield, so the call would look like:

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

$metafieldsResponse = $api->catalog()->brand(123)->metafields()->getAll();
$metafields = $metafieldsResponse->getMetafields();

Suppose we now want to delete metafield 456 on brand 123. Now our query is for a specific brand and a specific metafield.

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

$api->catalog()->brand(123)->metafield(456)->delete();

Resource Model Classes

The resource models represent the resources we provided to the API and the responses we receive.

To create a new resource, simply instantiate a new object of the correct resource model and then send it to the create endpoint. For example, if we want to create a new brand:

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

$brand = new BigCommerce\ApiV3\ResourceModels\Catalog\Brand\Brand();
$brand->name = "My Brand";
$brand->meta_description = "My wonderful brand";

$api->catalog()->brands()->create($brand);

Response Model Classes

Responses from the API all use similar response classes for consistency. There are two types generally: singular responses, and plural responses. Singular responses will have a single method in the format get<resource>(), for example (ProductResponse::getProduct()). Plural responses will have two methods, a getPagination() and get<resources>() (e.g. ProductsResponse::getProducts()).

Note that the API request is sent when the action is called and the response is returned.

$api = new BigCommerce\ApiV3\Client($_ENV['hash'], $_ENV['CLIENT_ID'], $_ENV['ACCESS_TOKEN']);

// Singular Responses
$category = $api->catalog()->category(456)->get()->getCategory();
$brand    = $api->catalog()->brand(123)->get()->getBrand(); 

// Plural Responses
$categoryResponse = $api->catalog()->categories()->getAll(limit: 10);
$totalCategories  = $categoryResponse->getPagination()->total;
$categories       = $categoryResponse->getCategories();

$brands = $api->catalog()->brands()->getAll()->getBrands();

Development

Running tests: composer run-script test
Checking PHP style rules: composer run-script check-style
Auto fix code style rules: composer run-script fix-style

If you do not have composer installed, you can use the docker version: docker run --rm -it -v $PWD:/app composer run-script check-style

Writing Tests

All tests are located in the tests folder in the namespace BigCommerce\Tests. The namespace should match the class being tested after this, e.g. BigCommerce\Tests\Api\Carts for testing BigCommerce\ApiV3\Api\Carts\CartsApi.

Responses can be mocked using the BigCommerceApiTest::setReturnData() function then you can inspect the request that was made with BigCommerceApiTest::getLastRequest(). Response JSON files are stored in tests/BigCommerce/responses.

Full Documentation

If you would like to have full class documentation, run docker run --rm -v /path/to/vendor/aligent/bigcommerce-api:/data phpdoc/phpdoc:3 run -d /data/src -t /data/docs --defaultpackagename BigCommerce --visibility public

aligent / bigcommerce-api-client

Maintainers

Details