README

简介

这是一个易于使用的 BigCommerce API 客户端。

安装

使用 composer 从 Packagist 安装 aligent/bigcommerce-api-client: composer require aligent/bigcommerce-api-client.

使用示例

更新产品名称的简单示例

$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()}";
}

获取所有可见产品（所有产品页面）

$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();

更新产品变体的示例

$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()}";
}

创建产品变体的示例

$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 设计

库中有三个组件

• BigCommerce/Api - 代表 API 端点，并试图模仿文档的布局。

• BigCommerce/ResourceModels - 代表发送到 API 和从 API 收到的资源，例如 Product 或 Order。

• BigCommerce/ResponseModels - 代表 BigCommerce API 的响应。

有关更多信息，请参阅 代码文档。

API 类

要与 API 交互，请始终从 BigCommerce\ApiV3\Client 类开始。所有 API 都可以通过两种方式访问：带 ID 和不带 ID。

如果您正在查询特定资源实例（例如产品 5），则应使用单数端点（->catalog()->product(5)），否则您应使用复数端点（即 ->catalog()->products()）。

例如，假设我们想要找到品牌 ID 为 123 的所有元字段。我们的查询是对一个 特定 品牌的任何元字段，所以调用看起来像

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

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

假设现在我们要删除品牌 123 上的元字段 456。现在我们的查询是对一个 特定 品牌和一个 特定 元字段的。

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

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

资源模型类

资源模型代表我们提供给 API 和我们接收的响应。

要创建新的资源，只需实例化正确的资源模型的新对象，然后将其发送到创建端点。例如，如果我们想创建一个新的品牌

$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);

响应模型类

API 的响应都使用类似响应类以确保一致性。通常有两种类型：单数响应和复数响应。单数响应将有一个名为 get<resource>() 的方法，例如 (ProductResponse::getProduct())。复数响应将有两个方法，一个 getPagination() 和一个 get<resources>()（例如 ProductsResponse::getProducts()）。

请注意，当调用动作时发送 API 请求，并返回响应。

$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();

开发

• 运行测试：composer run-script test
• 检查 PHP 风格规则：composer run-script check-style
• 自动修复代码风格规则：composer run-script fix-style

如果您没有安装 composer，可以使用 docker 版本：docker run --rm -it -v $PWD:/app composer run-script check-style

编写测试

所有测试都位于命名空间 BigCommerce\Tests 下的 tests 文件夹中。命名空间应与后续要测试的类匹配，例如测试 BigCommerce\ApiV3\Api\Carts\CartsApi 时使用 BigCommerce\Tests\Api\Carts。

可以使用 BigCommerceApiTest::setReturnData() 函数来模拟响应，然后您可以使用 BigCommerceApiTest::getLastRequest() 检查所发出的请求。响应 JSON 文件存储在 tests/BigCommerce/responses 中。

完整文档

如果您想查看完整的类文档，请运行以下命令：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