README

描述

此包用于与BigCommerce平台交互。该包可用于

1. 管理店铺/商家

   • 从BigCommerce获取店铺/商家信息

2. 管理产品

   • 从BigCommerce店铺导入产品完整列表（包括分类、变体和图片）
   • 将产品集合导出到BigCommerce店铺
   • 更新BigCommerce店铺上的现有产品
   • 从BigCommerce店铺删除产品

3. 管理订单

   • 从BigCommerce店铺导入所有订单
   • 导入两个日期之间的订单
   • 更新BigCommerce店铺上的订单状态

4. 管理客户

   • 从BigCommerce店铺导入客户
   • 将一个或多个客户添加到BigCommerce店铺
   • 更新BigCommerce店铺上的客户信息

5. 写入本地应用程序数据库

   • 将产品和相关信息写入应用程序数据库
   • 将订单和相关信息写入应用程序数据库
   • 将客户和相关信息写入应用程序数据库

该包包含个别实体（商家、分类、产品、订单、客户）的存储库。它还包含一个将所有其他存储库合并为一个的类。

需求

此包需要PHP版本7.1及以上。

安装

将以下代码添加到您的composer.json文件中，并更新它。

    composer require mavericks-lab/bigcommerce-integration

使用

初始化

<?php
use Maverickslab\Integration\BigCommerce\BigCommerceIntegrator;

$authToken = '';
$clientId = '';
$clientSecret = '';
$storeId = '';

$integrator = new BigCommerceIntegrator($authToken, $clientId, $clientSecret, $storeId);

获取店铺/商家信息

<?php 
$merchant = $integrator->merchant()->details();

$merchant是Maverickslab\Integration\BigCommerce\Store\Model\Merchant的一个实例。您现在可以按以下方式访问商家详细信息。

// Get store Id
echo $merchant->getId(), PHP_EOL;
    
// Get store plan name
echo $merchant->getPlanName(), PHP_EOL;
    
// Get store plan level
echo $merchant->getPlanLevel(), PHP_EOL;
    
// Get merchant/store name
echo $merchant->getName(), PHP_EOL;
    
// Get merchant first name
echo $merchant->getFirstName(), PHP_EOL;
    
// Get merchant last name
echo $merchant->getLastName(), PHP_EOL;
    
// Get store admin email
echo $merchant->getAdminEmail(), PHP_EOL;
    
// Get store address
echo $merchant->getAddress(), PHP_EOL;
    
// Get country name
echo $merchant->getCountry(), PHP_EOL;
    
// Get currency
echo $merchant->getCurrency(), PHP_EOL;

有关其他详细信息，请参阅Maverickslab\Integration\BigCommerce\Store\Model\Merchant。

导入所有产品分类

$categories = $integrator->category()->import();

$categories是分类数组，类型为Maverickslab\Integration\BigCommerce\Store\Model\Category[]。您可以按以下方式访问单个分类的详细信息。

 foreach ($categories as $category) {
     //Get id
    echo $category->getId(), PHP_EOL;
    //Get name
    echo $category->getName(), PHP_EOL;
    //Get description
    echo $category->getDescription(), PHP_EOL;
    //Get image url
    echo $category->getImageUrl(), PHP_EOL;
    //Get number of times a category has been views
    echo $category->getViews(), PHP_EOL;
}

有关如何访问分类的其他属性，请参阅Maverickslab\Integration\BigCommerce\Store\Model\Category。

创建分类

单个分类

$category = new Maverickslab\Integration\BigCommerce\Store\Model\Category();
$category->setName('Cloths');

$newCategories = $integrator->category()->export($category);

多个分类

 use Maverickslab\Integration\BigCommerce\Store\Model\Category;

$category1 = new Category();
$category1->setName('Cars');
$category1->setDescription('Description for cars');

$category2 = new Category();
$category2->setName('Planes');
$category2->setPageTitle('Page title for planes');

$category3 = new Category();
$category3->setName('Phones');
//Assign a parent to this category
$category3->setParentId(1);

$newCategories = $integrator->category()->export($category1, $category2, $category3);

在创建单个和多个分类时，$newCategories都是一个分类数组，类型为Maverickslab\Integration\BigCommerce\Store\Model\Category[]。

更新现有分类

注意：只有ID非零的分类才会被发送到BigCommerce进行更新

$categoryToUpdate = new Category();
$categoryToUpdate->setId(2); //REQUIRED
$categoryToUpdate->setName('Aeroplanes');

$updatedCategories = $integrator->category()->exportUpdate($categoryToUpdate);

提示：您可以传递尽可能多的分类。它们都将被更新并返回。

删除分类

按ID删除

//Single deletion
$deleteCounts = $integrator->category()->deleteByIds(1);

//Multiple deletion
$deleteCounts = $integrator->category()->deleteByIds(1, 2, 3, 4, 5);

//OR

$ids = [1, 2, 3, 4, 5];
$deleteCounts = $integrator->category()->deleteByIds(...$ids);

按实例删除

注意：只有ID非零的分类才会被发送到BigCommerce进行删除

 $categories = [new Category(), new Category(), new Category()];

 $deleteCounts = $integrator->category()->delete(...$categories);

导入产品

所有产品

$allProducts = $integrator->product()->import();

$allProducts是一个产品数组，类型为Maverickslab\Integration\BigCommerce\Store\Model\Product[]，包含店铺中的所有产品。

匹配一组筛选条件的产品

$filters = array(
    'type' => 'physical' //Import only physical products
);

$filteredProducts = $integrator->product()->import($filters);

$filteredProducts是一个产品数组，类型为Maverickslab\Integration\BigCommerce\Store\Model\Product[]，匹配指定的筛选条件。

按ID导入单个产品

 $id = 90;
 $product = $integrator->product()->importById($id);

导出产品

新产品可以逐个导入或作为集合导入。

单个产品

 use Maverickslab\Integration\BigCommerce\Store\Model\Product;
 
$newProduct = new Product();
$newProduct->setName('Google pixel 2');
$newProduct->setCondition(Product::CONDITION_NEW);
$newProduct->setSKU('GOOPIX2');
$newProduct->setPrice(880.50);
$newProduct->setCategoryIds(1, 3);
$newProduct->setWeight(2.4);
$newProduct->setType(Product::TYPE_PHYSICAL);

 $exportedProducts = $integrator->product()->export($newProduct);

多个产品

use Maverickslab\Integration\BigCommerce\Store\Model\Product;
$product1 = new Product();
$product1->setName('Google pixel 2');
$product1->setSKU('GOOPIX2');
$product1->setPrice(880.50);
$product1->setCategoryIds(1, 3);
$product1->setWeight(2.4);
$product1->setType(Product::TYPE_PHYSICAL);

$product2 = new Product();
$product2->setName('Google Nexus 5');
$product2->setPrice(580);
$product2->setCategoryIds(3);
$product2->setWeight(4);
$product2->setType(Product::TYPE_PHYSICAL);

$product3 = new Product();
$product3->setName('McAFEE Antivirus Plus');
$product3->setPrice(80.50);
$product3->setCategoryIds(1);
$product3->setWeight(1.4);
$product3->setType(Product::TYPE_DIGITAL);

$exportedProducts = $integrator->product()->export($product1, $product2, $product3);

具有变体的产品

use Maverickslab\Integration\BigCommerce\Store\Model\{Product, ProductVariant, ProductOptionValue);

//Create product
$product = new Product();
$product->setName('Google pixel 3');
$product->setSKU('GOOPIX2');
$product->setPrice(880.50);
$product->setCategoryIds(1, 3);
$product->setWeight(2.4);
$product->setType(Product::TYPE_PHYSICAL);

//Create variant
$variant = new ProductVariant();
$variant->setSKU('GOOPIX2-PLUS');
$variant->setPrice(890);

//Create option values for variant
$optionValue = new ProductOptionValue();
$optionValue->setOptionDisplayName('Colour');
$optionValue->setLabel('Red');

//Add option value to variant
$variant->addOptionValues($optionValue);//You can add more than option value

//Add variant to product
$product->addVariants($variant); //You can add more than one variant

//Export the product
$createdProducts = $integrator->product()->export($product);

更新BigCommerce上的现有产品

注意：只有ID非零的产品才会被发送到BigCommerce进行更新。

$products = [
    new Product(),
    new Product(),
    new Product()
];

$updatedProducts = $integrator->product()->exportUpdate(...$products);

删除产品

按ID删除

$productIds = [2, 3, 5];
$deleteCounts = $integrator->product()->deleteByIds(...$productIds);

按实例删除

注意：没有有效ID的产品将被忽略

$products = [new Product(), new Product(), new Product()];

$deleteCounts = $integrator->product()->delete(...$products);

通过过滤器删除

$filters = ['type' => 'digital', 'condition' => 'used'];

$integrator->product()->deleteByFilter($filters);1

导入订单

导入所有订单

$orders = $integrator->order()->import();

foreach($orders as $order) {
    //Get ordered products
    //Each ordered product is an instances of Maverickslab\Integration\BigCommerce\Store\Model\OrderedProduct
    foreach($order->getProducts() as $orderedProduct) {
        //Get product name
        $orderedProduct->getName();

        //Get quantity
        $orderedProduct->getQuantity();
    }

    //Get customer information
    //A customer is an instances of Maverickslab\Integration\BigCommerce\Store\Model\Customer
    $order->getCustomer();

    //Get billing address
    //A billing address is an instance of Maverickslab\Integration\BigCommerce\Store\Model\BillingAddress
    $order->getBillingAddress();

    //Get shipping addresses
    //Each shipping address is an instance of Maverickslab\Integration\BigCommerce\Store\Model\ShippingAddress
    $order->getShippingAddresses();

    //Get total items in order
    $order->getItemsTotal();

    //Get total cost of order excluding tax
    $order->getTotalExcludingTax();

    //Get total cost of order including tax
    $order->getTotalIncludingTax();
}

有关如何访问订单其他属性的更多信息，请参阅Maverickslab\Integration\BigCommerce\Store\Model\Order。

您还可以通过将过滤器数组传递给import()方法来过滤订单，如下所示。

//Import orders that are pending
$filters = ['status_id' => 1];

$orders = $integrator->order()->import($filters);

导入两个日期之间的订单

以下代码将导入30天前创建的所有订单。

$startDateTime = new DateTime('30 days ago');
$endDateTime = new DateTime();
$orders = $integrator->order()->importBetweenDates($startDateTime, $endDateTime);

//OR
//If the second parameter is omitted, the current date and time will be used
$orders = $integrator->order()->importBetweenDates($startDateTime);

提示：您还可以将过滤器数组作为importBetweenDates()方法的第三个参数传递。

导入订单状态

$statuses = $integrator->order()->importStatuses();

foreach($statuses as $status) {
    //Get status Id
    $status->getId();

    //Get status name
    $status->getName();

    //Get status description
    $status->getSystemDescription();

    //Get custom label 
    $status->getCustomLabel();
}

每个订单状态都是Maverickslab\Integration\BigCommerce\Store\Model\OrderStatus的一个实例。

更新订单状态

注意：更新订单状态所需唯一的属性是Id和状态Id。

$order1 = new Order();
$order1->setId(1);
$order1->setStatusId(0);//Incomplete

$order2 = new Order();
$order2->setId(1);
$order2->setStatusId(10); //Completed

$order3 = new Order();
$order3->setId(3);
$order3->setStatusId(11); //Awaiting Fulfillment

$numberOfOrdersUpdate = $integrator->order()->exportUpdateOrderStatus($order1, $order2, $order3);

导入客户

//Import all customers
$customers = $integrator->customer()->import();

//Read customer properties
foreach($customers as $customer) {
    //Get customer Id
    $customer->getId();

    //Get customer first name
    $customer->getFirstName();

    //Get customer last name
    $customer->getLastName();

    //Get customer's compoany
    $customer->getCompany();

    //Get customer email address
    $customer->getEmail();

    //Get customer phone number
    $customer->getPhone();

    //Get customer store credit
    $customer->getStoreCredit();

    //Get customer group Id
    $customer->getGroupId();

    //Read customer's addresses
    foreach($customer->getAddresses() as $address) {
        //Get country
        $address->getCountry();

        //Get state
        $address->getState();

        //Get city
        $address->getCity();

        //Get streets
        $address->getStreetOne();
        $address->getStreetTwo();

        //Get address type
        $address->getType();
    }

}

有关如何访问客户其他属性的更多信息，请参阅Maverickslab\Integration\BigCommerce\Store\Model\Customer。

导出客户

use Maverickslab\Integration\BigCommerce\Store\Model\Customer;

$customer = new Customer();
$customer->setFirstName('George');
$customer->setLastName('Smith');
$customer->setEmail('smithgeorge@somedomain.com');
$customer->setPhone('+2337885788575');
//Add more properties

$exportedCustomers = $integrator->customer()->export($customer);

更新现有客户

注意：只有ID非零的客户才会发送到BigCommerce进行更新。

$customers = [new Customer(), new Customer(), new Customer()];

$updatedCustomers = $integrator->customer()->exportUpdate(...$customers);

删除现有客户

//Delete a single customer by Id
$id = 3;
$deleteCounts = $integrator->customer()->deleteByIds($id);

//Deleting multiple customers by Ids
$ids = [3, 4, 5, 1];
$deleteCounts = $integrator->customer()->deleteByIds(...$ids);

写入本地应用程序数据库

您不需要这个库来为您写入应用程序数据库。但是，如果您希望这样做，您必须实现或扩展一个实现Maverickslab\Integration\BigCommerce\Store\Repository\Writer\RepositoryWriterInterface接口的类。

为了使库更容易用于将模型写入本地数据库，提供了一个空的RepositoryWriterInterface实现，即Maverickslab\Integration\BigCommerce\Store\Repository\Writer\RepositoryWriter，您可以扩展并重写您需要与数据库一起工作的方法。以下是将产品写入本地数据库的示例。

use Maverickslab\Integration\BigCommerce\Store\Repository\Writer\RepositoryWriter;
use Maverickslab\Integration\BigCommerce\Store\Model\Product;

class SyncommerceRepositoryWriter extends RepositoryWriter {

    /**
     * 
     * {@inheritDoc}
     * @see \Maverickslab\Integration\BigCommerce\Store\Repository\Writer\RepositoryWriter::createProducts()
     */
    public function createProducts(Product ...$products): array {
        //Format product
        $formattedProductsArray = array_map(function(Product $product){
            return $product->toArray();
        }, $products);

        //Save products to database
        DB::table('products')->insert($formattedProductsArray);

        //Returns the saved products or an empty array
        return [];
    }
}

新创建的仓库编写器可以使用如下所示。

use Maverickslab\Integration\BigCommerce\BigCommerceIntegrator;

$authToken = '';
$clientId = '';
$clientSecret = '';
$storeId = '';
$repositoryWriter = new SyncommerceRepositoryWriter();

//Pass the repository writer as the fifth parameter
$integrator = new BigCommerceIntegrator($authToken, $clientId, $clientSecret, $storeId, $repositoryWriter);

//Import products from BigCommerce 
$importedProducts = $integrator->product()->import();

//Save imported products locally
$savedProducts = $integrator->product()->save(...$importedProducts);