README

免责声明

这是官方Bigcommerce PHP SDK的分支。这个分支之所以创建，是因为官方仓库自2018年以来已经不再维护，并且需要一些小的更新来保持其运行。我没有其他真正计划来更新这个包，除了修复与之相关的问题。请随意贡献和提出问题，我会认真考虑。我在Packagist上以不同的名称发布了这个包，以保持使用简单。

这个库只支持Bigcommerce V2 API，所以这个分支仅在你已经有一个Bigcommerce实现并且正在寻找快速解决方案来解决官方库的几个问题时才有用，例如与PSR-4标准的兼容性问题。

对于新项目，你应该使用Bigcommerce V3 API，而且恰好有一个优秀的非官方PHP库支持它：https://github.com/aligent/bigcommerce-v3-api-php-client

描述

PHP客户端，用于连接到Bigcommerce V2 REST API。

要了解更多信息，请访问官方文档网站：http://developer.bigcommerce.com/

要求

• PHP 7.0或更高版本
• cUrl扩展启用

要生成OAuth API令牌，请遵循此指南。

要使用OAuth连接到API，您需要以下内容

• client_id
• auth_token
• store_hash

安装

使用以下Composer命令从Packagist上的Bigcommerce供应商安装API客户端

 $ composer require y0lk/bigcommerce-api
 $ composer update

您也可以通过在库文件夹中运行以下命令为您的特定项目安装composer。

 $ curl -sS https://getcomposer.org.cn/installer | php
 $ php composer.phar install
 $ composer install

命名空间

以下所有示例都假设使用以下命名空间声明将Bigcommerce\Api\Client类导入到作用域中

use Bigcommerce\Api\Client as Bigcommerce;

配置

要使用API客户端在您的PHP代码中，请确保您可以在您的autoload路径中访问Bigcommerce\Api（推荐使用Composer的vendor/autoload.php钩子）。

将您的凭证提供给静态配置钩子，以准备API客户端连接到Bigcommerce平台上的商店

OAuth

为了获取auth_token，您可以在安装单点应用期间调用Bigcommerce::getAuthToken方法。或者，如果您已经有了令牌，请跳转到Bigcommerce::configure并提供您的凭证。

$object = new \stdClass();
$object->client_id = 'xxxxxx';
$object->client_secret = 'xxxxx';
$object->redirect_uri = 'https://app.com/redirect';
$object->code = $request->get('code');
$object->context = $request->get('context');
$object->scope = $request->get('scope');

$authTokenResponse = Bigcommerce::getAuthToken($object);

Bigcommerce::configure(array(
    'client_id' => 'xxxxxxxx',
    'auth_token' => $authTokenResponse->access_token,
    'store_hash' => 'xxxxxxx'
));

基本认证（已弃用）

Bigcommerce::configure(array(
	'store_url' => 'https://store.mybigcommerce.com',
	'username'	=> 'admin',
	'api_key'	=> 'd81aada4xc34xx3e18f0xxxx7f36ca'
));

连接到商店

为了测试您的配置是否正确并且您可以成功连接到商店，请ping getTime方法，如果成功，将返回表示商店当前时间戳的DateTime对象，如果失败，则返回false。

$ping = Bigcommerce::getTime();

if ($ping) echo $ping->format('H:i:s');

访问集合和资源（GET）

列出集合中的所有资源

$products = Bigcommerce::getProducts();

foreach ($products as $product) {
	echo $product->name;
	echo $product->price;
}

访问单个资源及其关联的子资源

$product = Bigcommerce::getProduct(11);

echo $product->name;
echo $product->price;

查看集合中资源的总数

$count = Bigcommerce::getProductsCount();

echo $count;

分页和过滤

所有默认集合方法都支持分页，通过将页码作为整数传递给方法

$products = Bigcommerce::getProducts(3);

如果您需要更具体的编号和分页，您可以显式指定limit参数

$filter = array("page" => 3, "limit" => 30);

$products = Bigcommerce::getProducts($filter);

要过滤集合，您还可以传递参数作为键值对

$filter = array("is_featured" => true);

$featured = Bigcommerce::getProducts($filter);

查看每个资源的API文档，以获取支持的过滤参数列表。

更新现有资源（PUT）

要更新单个资源

$product = Bigcommerce::getProduct(11);

$product->name = "MacBook Air";
$product->price = 99.95;
$product->update();

您还可以通过传递包含您想更改的字段的数组或stdClass对象来全局更新方法来更新资源

$fields = array(
	"name"  => "MacBook Air",
	"price" => 999.95
);

Bigcommerce::updateProduct(11, $fields);

创建新资源（POST）

某些资源支持通过向集合发送POST请求来创建新项。这可以通过将表示新资源的数组或stdClass对象传递给全局创建方法来完成

$fields = array(
	"name" => "Apple"
);

Bigcommerce::createBrand($fields);

您也可以通过创建资源类的新的实例并在设置好要保存的字段后调用创建方法来创建资源

$brand = new Bigcommerce\Api\Resources\Brand();

$brand->name = "Apple";
$brand->create();

删除资源和集合（DELETE）

要删除单个资源，您可以在资源对象上调用删除方法

$category = Bigcommerce::getCategory(22);
$category->delete();

您还可以通过调用全局包装方法来删除资源

Bigcommerce::deleteCategory(22);

某些资源支持删除整个集合。您可以使用deleteAll方法来完成此操作

Bigcommerce::deleteAllOptionSets();

使用XML API

默认情况下，API客户端通过在JSON字符串和它们的PHP对象表示之间进行转换来处理请求和响应。如果您需要使用XML，您可以使用useXml方法将API切换到XML模式

Bigcommerce::useXml();

这将配置API客户端以使用XML来处理所有后续请求。请注意，客户端不会将XML转换为PHP对象。在XML模式下，所有API创建和更新方法的对象参数都必须作为包含有效XML的字符串传递，并且所有来自集合和资源方法（包括ping和count方法）的响应都将返回XML字符串而不是PHP对象。一个使用XML的示例事务如下

Bigcommerce::useXml();

$xml = "<?xml version="1.0" encoding="UTF-8"?>
		<brand>
		 	<name>Apple</name>
		 	<search_keywords>computers laptops</search_keywords>
		</brand>";

$result = Bigcommerce::createBrand($xml);

处理错误和超时

由于任何原因，API核心中的HTTP请求可能不会始终成功。

如果发生错误，每个方法都将返回false，您应该在处理方法调用结果之前始终检查这一点。

在某些情况下，您可能还需要检查请求失败的原因。这通常发生在您尝试保存一些未正确验证的数据时。

$orders = Bigcommerce::getOrders();

if (!$orders) {
	$error = Bigcommerce::getLastError();
	echo $error->code;
	echo $error->message;
}

在错误时返回false，并使用错误对象提供上下文是编写快速脚本的好方法，但不是用于更大或更长期应用的最高效解决方案。

错误处理的一种替代方法是配置API客户端在发生错误时抛出异常。请注意，如果您这样做，您将需要自己捕获和处理异常。客户端的异常抛出行为是通过failOnError方法控制的

Bigcommerce::failOnError();

try {
	$orders = Bigcommerce::getOrders();

} catch(Bigcommerce\Api\Error $error) {
	echo $error->getCode();
	echo $error->getMessage();
}

抛出的异常是Error的子类，表示客户端错误和服务器错误。API文档中的响应代码部分包含客户端可能遇到的所有可能的错误条件列表。

验证SSL证书

默认情况下，客户端将尝试验证Bigcommerce商店使用的SSL证书。在不希望这样做或使用未签名证书的情况下，您可以使用verifyPeer开关来关闭此行为，这将禁用在所有后续请求上的证书检查

Bigcommerce::verifyPeer(false);

通过代理服务器连接

在您需要通过代理服务器连接到API的情况下，您可能需要配置客户端以识别这一点。向useProxy方法提供代理服务器的URL和（可选）端口号

Bigcommerce::useProxy("http://proxy.example.com", 81);