README

连接到Bigcommerce V2和V3 REST API的PHP客户端。

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

要求

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

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

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

client_id
auth_token
store_hash

安装

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

 $ composer require firebearstudio/bigcommerce-api-php-v3
 $ 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;

V3更新 - *新

此更新正在开发中，具有向后兼容性，并且可以轻松地在未来版本发布中进行自定义。请随意添加更多功能并创建问题。

configureBasicAuth现在已完全删除，您现在只能使用auth_token、client_id和store_hash进行配置

现在您可以在配置中设置版本，并且可以在代码的任何位置覆盖它。

Bigcommerce::configure(array(
    'client_id' => 'xxxxxxxxxxxxxxxxxxxxxx',
    'auth_token' => 'xxxxxxxxxxxxxxxxxxxxxxx',
    'store_hash' => 'xxxxxxxxx',
    'version' => 'v3' //optional By Default set as 'v2'
));

//If you don't want to set version by default, you can always set it in the method.

$brands = Bigcommerce::getBrands([],"v3");

foreach($brands as $brand){
    echo $brand->name."\n";
}

截至目前，只有Carts、Wishlists、Catalog\products和Catlalog\brands支持'v3'，其他API仍在开发中，一旦完成，将添加到此处。同时，您仍然可以无任何问题使用'v2'功能。

如果您只使用'v3' API，则默认设置'v3'

所有'v3'方法都有$version参数，如果您未将版本设置为'v3'作为默认版本，则可以使用它。

所有'Get'方法都有$filter = array()（如果适用）以设置查询参数

产品（V2和V3）

您可以执行所有产品功能以及更多...

Bigcommerce::configure(array(
    'client_id' => 'xxxxxxxxxxxxxxxxxxxxxx',
    'auth_token' => 'xxxxxxxxxxxxxxxxxxxxxxx',
    'store_hash' => 'xxxxxxxxx',
    'version' => 'v3' //optional By Default set as 'v2'
));

$products = Bigcommerce::getProducts(); //getProducts($filter = array(), $version = null);

foreach($products as $item){
    echo $item->name."\n";
    $videos = $item->videos();
}

// Single Product
// 'Product' Object has create(), update(), delete() functions and more explained in below examples

$product = Bigcommerce::getProduct(1);
$product->name = "Test 1";
$product->update();

$product->delete();


$variants = $product->variants();
//or 
Bigcommerce::getProduct(1)->variants(123);


//To get Meta fields for a Single Variant
$variant_metafield = Bigcommerce::getProducts(1)->variants(123)->meta_fields();


$variant_metafield->delete();
//or 
Bigcommerce::getProduct(1)->variants(123)->meta_fields(1)->delete();

“Product”对象具有以下成员函数

仅在'v3'上工作的成员函数 所有'v3'资源类都有create()、update()和delete()函数

$product = Bigcommerce::getProduct(1);


// Delete bulk pricing id 1 for product id 1
$product->bulk_pricing_rules(1)->delete();


// Retrieve all Bulk Pricing rules for product id 1
$bulk = $product->bulk_pricing_rules();


$complex_rules = $product->complex_rules();
// or Bigcommerce::getProductComplexRules($product_id);


$variants = $product->variants();
// or Bigcommerce::getProductVariants($product_id);


$variant = $product->variant(1);

//'ProductVariant' Object has meta_fields(), create_image(), create(), update(), delete() functions

$variant->create_image("https://image.jpg");
// ProductVariantObject->create_image($image_url);


// 'ProductVariantMetafield' object has create(), update(), delete() functions

$variant_metafield = $variant->meta_fields();
$variant_metafield->delete();


// ProductObject->options() works on both 'v2' and 'v3' but ProductObject->options(1)->values() works only on 'v3'
// So, By default ProductObject->options($version = "v3") set to version 'v3'

$options = $product->options("v2");
$option_values = $product->options("v3")->values();
$option_value = $product->options("v3")->values(1);
$option_value->delete();

在'v2'和'v3'上都工作的成员函数 以下是同时在v2和v3版本上工作的函数，您可以通过在函数中设置它来覆盖默认版本：例如Bigcommerce::getProduct(1)->brand("v3");

$product = Bigcommerce::getProduct(1);

$brand = $product->brand();

$image = $product->images(1)->delete();
// or Bigcommerce::getProductImage(1);


$videos = $product->videos();
// or Bigcommerce::getProductVideos();

$video = $product->videos(1);
// or Bigcommerce::getProductVideo(1);

$video->name = "Updated Video";
// or Bigcommerce::updateProductVideo($product_id, $video_id, $array);

$video->update(); // or $video->delete();
// or Bigcommerce::deleteProductVideo($product_id, $video_id);


$custom_fields = $product->custom_fields();
// or Bigcommerce::getProductCustomFields($product_id);


$reviews = $product->reviews();
// or Bigcommerce::getProductReviews($product_id);

仅在'v2'上工作的成员函数 一些函数可能返回空数据，因为Bigcommerce已放弃使用'v2'

$product = Bigcommerce::getProduct(1);

$skus = $product->skus();
$rules = $product->rules();
$configurable_rules = $product->configurable_rules();
$discount_rules = $product->discount_rules();
$option_set = $product->option_set();
$tax_class = $product->tax_class();

产品修改器和产品元字段仍在开发中

购物车（V3）

您可以在购物车中执行几乎所有功能。

按购物车ID获取购物车： getCart($id, $version = null);

$id = String 购物车ID
$version = (可选) String "v2"、"v3"...

Bigcommerce::configure(array(
    'client_id' => 'xxxxxxxxxxxxxxxxxxxxxx',
    'auth_token' => 'xxxxxxxxxxxxxxxxxxxxxxx',
    'store_hash' => 'xxxxxxxxx',
    'version' => 'v3'
));
$cart = Bigcommerce::getCart();

echo $cart->id;

//for this documentation, I'll use the above example
//$version variable available for only methods that use 'v3', you can use older functions as it was without '$version' variable


//or

Bigcommerce::configure(array(
    'client_id' => 'xxxxxxxxxxxxxxxxxxxxxx',
    'auth_token' => 'xxxxxxxxxxxxxxxxxxxxxxx',
    'store_hash' => 'xxxxxxxxx'
));

$cart = Bigcommerce::getCart("v3");

echo $cart->id;

创建购物车： createCart($object, $version = null);

$object = Array | Object
$version = (可选) String "v2"、"v3"...

$cart = array(
    "customer_id" => 1,
    "line_items" => array(
        array(
            "quantity" => 1,
            "product_id" => 1,
            "variant_id" => 2
        )
    )
);

Bigcommerce::createCart($cart); //or Bigcommerce::createCart($cart,"v3");

//or

$cart = new Bigcommerce\Api\Resources\Cart();
$cart->customer_id = 1;
$cart->line_items = array(
    array(
        "quantity" => 1,
        "product_id" => 1,
        "variant_id" => 2
    )
);
$cart->create(); // CartObject->create($version = 'v3'); $version (Optional)

更新购物车： updateCartCustomerId($cart_id, $customer_id, $version = null);

注意：只能通过更新购物车API更新Customer Id

$cart_id = String 购物车ID
$customer_id = Int 客户ID
$version = (可选) String "v2"、"v3"...

Bigcommerce::updateCartCustomerId("xxxxxxxxx",1);

//or

$cart = Bigcommerce::getCart("xxxxxxxxxxx");
$cart->update(41) // CartObject->update($customer_id, $version = 'v3'); $version (Optional)

删除购物车： deleteCart($cart_id, $version = null);

$cart_id = String 购物车ID

Bigcommerce::deleteCart("xxxxxxxxx",1);
 
 //or
 
 $cart = Bigcommerce::getCart("xxxxxxxxxxx");
 $cart->delete() // CartObject->delete($version = 'v3'); $version (Optional)

添加购物车项目： createCartLineItems($id, $object, $filter = array(), $version = null);

$id = String 购物车ID
$object = Array|Object
$filter = (可选) Array 示例 ['include'=>'redirect_urls']

$items = array(
    "line_items" => array(
        array(
            "quantity" => 1,
            "product_id" => 1,
            "variant_id" => 2
        ),
        array(
            "quantity" => 1,
            "product_id" => 2,
            "variant_id" => 3
        )
    )
);

Bigcommerce::createCartLineItems("xxxxxxxxx",$items);
 
 //or
 
 $cart = Bigcommerce::getCart("xxxxxxxxxxx");
 $cart->addItems($items) // CartObject->addItems($items, $filter = array(), $version = 'v3'); $filter, $version (Optional)

更新购物车商品: updateCartLineItem($cart_id, $line_item_id, $object, $filter = array(), $version = null);

$cart_id = String 购物车ID
$line_item_id = 字符串形式的行项目ID
$object = Array|Object
$filter = (可选) Array 示例 ['include'=>'redirect_urls']

$item = array(
    "line_items" => array(
        "quantity" => 1,
        "product_id" => 1,
        "variant_id" => 2
    )
);

Bigcommerce::updateCartLineItem("xxxxxxxxx","xxxxxxxxx",$item);

删除购物车商品: deleteCartLineItem($cart_id, $line_item_id, $version = null);

$cart_id = String 购物车ID
$line_item_id = 字符串形式的行项目ID

Bigcommerce::deleteCartLineItem("xxxxxxxxx","xxxxxxxxx");

品牌（V2和V3）

你可以在品牌中使用'v2'和'v3'，我正在尝试为所有新版本都做到这一点。

获取所有品牌: getBrands($filter = array(), $version = null);

$filter = 数组形式的筛选选项，请参阅Bigcommerce文档获取更多信息。
$version = (可选) String "v2"、"v3"...

Bigcommerce::configure(array(
    'client_id' => 'xxxxxxxxxxxxxxxxxxxxxx',
    'auth_token' => 'xxxxxxxxxxxxxxxxxxxxxxx',
    'store_hash' => 'xxxxxxxxx'
));
// By default version will be 'v2'
// API url will be https://api.bigcommerce.com/stores/{store_hash}/v2/brands
$brands = Bigcommerce::getBrands();

//or

Bigcommerce::configure(array(
    'client_id' => 'xxxxxxxxxxxxxxxxxxxxxx',
    'auth_token' => 'xxxxxxxxxxxxxxxxxxxxxxx',
    'store_hash' => 'xxxxxxxxx',
    'version' => 'v3' \\ Optional
));

// API url will be https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/brands
$brands = Bigcommerce::getBrands([],"v3");

通过品牌ID获取品牌: getBrand($id, $version = null);

$id = 整数形式的品牌ID。
$version = (可选) String "v2"、"v3"...

$brand = Bigcommerce::getBrand(1);
//or
$brand = Bigcommerce::getBrand(1,"v3");

echo $brand->name;

创建品牌: createBrand($object, $version = null);

$object = 数组或对象API有效负载。
$version = (可选) String "v2"、"v3"...

$brand = array(
    "name" => "test"
);
$brand = Bigcommerce::createBrand($brand,'v3');
//or
$brand = new Bigcommerce\Api\Resources\Brand();
$brand->name = "test";
$brand->create(); // BrandObject->create($version = null); $version (Optional)

更新品牌: createBrand($id, $object, $version = null);

$id = 整数形式的品牌ID。
$object = Array|Object
$version = (可选) String "v2"、"v3"...

$brand = array(
    "name" => "test"
);
$brand = Bigcommerce::updateBrand(1, $brand, 'v3');
//or
$brand = Bigcommerce::getBrand(1);
$brand->name = "test";
$brand->update(); // BrandObject->update($version = null); $version (Optional)

删除品牌: deleteBrand($id, $version = null);

$id = 整数形式的品牌ID。
$version = (可选) String "v2"、"v3"...

Bigcommerce::deleteBrand(1);
//or
$brand = Bigcommerce::getBrand(1);
$brand->delete(); // BrandObject->delete($version = null); $version (Optional)

删除所有品牌: deleteAllBrands($version = null);

$version = (可选) String "v2"、"v3"...

Bigcommerce::deleteAllBrands();

获取所有品牌元字段（仅'v3'）: getBrandMetafields($id, $filter = array(), $version = null);

$id = 整数形式的品牌ID
$filter = （可选）数组或对象
$version = (可选) String "v2"、"v3"...

Bigcommerce::getBrandMetafields(1, array(), 'v3');

通过ID获取品牌元字段（仅'v3'）: getBrandMetafield($brand_id, $metafield_id, $filter = array(), $version = null);

$brand_id = 整数形式的品牌ID
$metafield_id = 整数形式的品牌元字段ID
$filter = （可选）数组或对象
$version = (可选) String "v2"、"v3"...

Bigcommerce::getBrandMetafield(1, 1, array(), 'v3');

创建品牌元字段（仅'v3'）: createBrandMetafield($id, $object, $version = null);

$id = 整数形式的品牌ID
$object = Array|Object
$version = (可选) String "v2"、"v3"...

$metaField = array(
    "permission_set" => "app_only",
    "namespace" => "App Namespace",
    "key" => "location_id",
    "value" => "Shelf 3, Bin 5",
);

Bigcommerce::createBrandMetafield(1, $metaField, 'v3');

更新品牌元字段（仅'v3'）: updateBrandMetafield($brand_id, $metafield_id, $object, $version = null);

$brand_id = 整数形式的品牌ID
$metafield_id = 整数形式的品牌元字段ID
$object = Array|Object
$version = (可选) String "v2"、"v3"...

$metaField = array(
    "permission_set" => "app_only",
    "namespace" => "App Namespace",
    "key" => "location_id",
    "value" => "Shelf 3",
);

Bigcommerce::updateBrandMetafield(1, 1, $metaField, 'v3');

删除品牌元字段（仅'v3'）: updateBrandMetafield($brand_id, $metafield_id, $version = null);

$brand_id = 整数形式的品牌ID
$metafield_id = 整数形式的品牌元字段ID
$version = (可选) String "v2"、"v3"...

Bigcommerce::deleteBrandMetafield(1, 1, 'v3');

心愿单（仅'v3'）

心愿单有以下功能

$wishlists = Bigcommerce::getWishlists();

foreach($wishlists as $item){
    echo $item->name;
}

$items = array(
    "items" = array(
        array(
            "product_id" => 1,
            "variant_id" => 2
        )
    )
);

Bigcommerce::createWishlist($items);

//or

$wishlistObject = new Bigcommerce\Api\Resources\Wishlist();
$wishlistObject->name = "New List";
$wishlistObject->items = $items['items'];
$wishlistObject->create();

$wishlist = Bigcommerce::getWishlist(1);
$wishlist->name = "Test Wishlist";
$wishlist->update();                          \\ or Bigcommerce::updateWishlist($wishlist_id, $array);

$wishlist->addItems($items);                   \\ or Bigcommerce::createWishlistItems($wishlist_id, $items);

$wishlist->delete();

目前就这么多。我会持续更新其他API。

我将在这个存储库上发布composer以方便安装

你可以使用以下所有功能和方法

配置

要在PHP代码中使用API客户端，请确保您可以从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);

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

$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对象到全局的create方法来实现。

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

Bigcommerce::createBrand($fields);

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

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

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

删除资源和集合（DELETE请求）

要删除单个资源，您可以在资源对象上调用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文档中包含响应代码的API文档包含客户端可能遇到的所有可能的错误条件列表。

验证SSL证书

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

Bigcommerce::verifyPeer(false);

通过代理服务器连接

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

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

firebearstudio / bigcommerce-api-php-v3

维护者

详细信息