README

本软件包提供了一组 PHP SDK，用于与 Vanilo Cloud REST API 交互。

安装

本软件包的最低要求为 PHP 8.1。

要在您的应用程序中安装此库，请使用 composer

composer require vanilo/cloud-sdk

使用方法

身份验证

要连接到 Vanilo Cloud API，您需要商店的 URL、client_id 和 client_secret。

以下代码返回一个 API 客户端实例

$api = VaniloCloud\ApiClient::for('https://your.v-shop.cloud')->withCredentials('client id', 'client secret');

在底层，SDK 将从 API 中获取身份验证令牌，以最大限度地减少在网络上发送 client_id 和 client_secret 的情况。

要连接到通用沙盒环境，请使用

$api = VaniloCloud\ApiClient::sandbox();

Vanilo Cloud 沙盒可在以下位置使用： https://sandbox.v-shop.cloud/
沙盒数据库每 30 分钟重置一次

HTTP 基本认证

如果您的 Vanilo Cloud 商店实例受基本身份验证保护，则使用 withBasicAuth('user', 'pass') 方法传递基本 HTTP 身份验证凭据

ApiClient::for('https://your.shop.url')
    ->withBasicAuth('user', 'pass') // <- Add this line
    ->withCredentials('client id', 'client secret');

令牌存储

为了有效地使用令牌身份验证并避免速率限制异常，强烈建议使用持久令牌存储。

如果已安装并启用了 APC 扩展，则无需进行任何操作，所有操作都在幕后为您处理。

如果您在 Laravel 应用程序中使用此库，则最佳做法是使用内置的 Laravel 缓存令牌存储，该存储利用配置的缓存来临时存储身份验证令牌

$api = VaniloCloud\ApiClient::for('https://your.v-shop.cloud')
    ->withCredentials('client id', 'client secret')
    ->useLaravelTokenStore();

检索原始响应

如果您需要从 API 获取原始 HTTP 响应，则需要调用 rawGet、rawPost 等方法

$api = VaniloCloud\ApiClient::sandbox();
$api->rawGet('/taxonomies');
//=> Illuminate\Http\Client\Response {#2743
//     +cookies: GuzzleHttp\Cookie\CookieJar {#2725},
//     +transferStats: GuzzleHttp\TransferStats {#2765},

要获取 API 调用的内容，请使用返回响应的 json() 方法

$response = $api->rawGet('/taxonomies');
foreach ($response->json('data') as $taxonomy) {
    echo $taxonomy['name'];
}
// Category

分类法

通过 ID 获取分类法

$api = VaniloCloud\ApiClient::sandbox();
$taxonomy = $api->taxonomy(1);
// => VaniloCloud\Models\Taxonomy
//     id: "1",
//     name: "Category",
//     slug: "category",
//     created_at: "2022-12-06T16:23:34+00:00",
//     updated_at: "2023-01-13T08:03:29+00:00"

产品

通过 SKU 获取产品

$api = VaniloCloud\ApiClient::sandbox();

$api->product('WBB-030');
// => VaniloCloud\Models\Product
//     name: "William Black Bookshelf"
//     slug: "william-black-bookshelf"
//     sku: "WBB-030"
//     ...

获取产品列表

$api = VaniloCloud\ApiClient::sandbox();

$api->products();
// Illuminate\Support\Collection {
//  #items: array:2 [▼
//    1 => VaniloCloud\Models\Product
//    ...
//  ]
// ...

创建产品

use VaniloCloud\Enums\ProductState;
use VaniloCloud\WriteModels\ProductCreate;

$api = VaniloCloud\ApiClient::sandbox();

$productCreate = new ProductCreate();
$productCreate
    ->setName('William Black Bookshelf')
    ->setSku('WBB-030')
    ->setState(ProductState::ACTIVE);
        
$api->createProduct($productCreate);
// "WBB-030"

通过 SKU 更新产品

use VaniloCloud\WriteModels\ProductUpdate;

$api = VaniloCloud\ApiClient::sandbox();

$productUpdate = new ProductUpdate();
$productUpdate
    ->setName('William Black Bookshelf 030')
    ->setStock(1337)
    ->setDescription('A black bookshelf.');

$api->updateProduct('WBB-030', $productUpdate);
// true

通过 SKU 删除产品

$api = VaniloCloud\ApiClient::sandbox();

$api->deleteProduct('WBB-030');
// true

主产品

通过 ID 获取主产品

$api = VaniloCloud\ApiClient::sandbox();

$api->masterProduct(1);
// => VaniloCloud\Models\MasterProduct
//     name: "My Master Product"
//     slug: "my-master-product"
//     price: 1
//     ...

获取主产品列表

$api = VaniloCloud\ApiClient::sandbox();

$api->masterProducts();
// Illuminate\Support\Collection {
//  #items: array:2 [▼
//    1 => VaniloCloud\Models\MasterProduct
//    ...
//  ]
// ...

创建主产品

use VaniloCloud\Enums\ProductState;
use VaniloCloud\WriteModels\MasterProductCreate;

$api = VaniloCloud\ApiClient::sandbox();

$masterProductCreate = new MasterProductCreate();
$masterProductCreate
    ->setName('My Master Product');
        
$api->createMasterProduct($masterProductCreate);
// "1"

通过 ID 更新主产品

use VaniloCloud\WriteModels\MasterProductUpdate;

$api = VaniloCloud\ApiClient::sandbox();

$masterProductUpdate = new MasterProductUpdate();
$masterProductUpdate
    ->setDescription('This is my Master Product.');

$api->updateMasterProduct(1, $masterProductUpdate);
// true

通过 ID 删除主产品

$api = VaniloCloud\ApiClient::sandbox();

$api->deleteMasterProduct(1);
// true

订单

通过 ID 获取订单

$api = VaniloCloud\ApiClient::sandbox();

$api->order(1);
// => VaniloCloud\Models\Order
//     number: "6YP-0K1A-BO06"
//     status:  VaniloCloud\Enums\OrderStatus { ...
//     fulfillment_status: VaniloCloud\Enums\FulfillmentStatus { ...
//     ...

获取订单列表

$api = VaniloCloud\ApiClient::sandbox();

$api->orders();
// Illuminate\Support\Collection {
//  #items: array:2 [▼
//    1 => VaniloCloud\Models\Order
//    ...
//  ]
// ...

创建订单

use VaniloCloud\Enums\ProductType;
use VaniloCloud\WriteModels\OrderCreate;
use VaniloCloud\WriteModels\BillpayerWrite;
use VaniloCloud\WriteModels\OrderItemWrite;

$api = VaniloCloud\ApiClient::sandbox();

$billpayerWrite = new BillpayerWrite();

$billpayerWrite
    ->setEmail('john@doe.com')
    ->setFirstName('John')
    ->setLastName('Doe')
    ->setCountry('GB')
    ->setCity('London')
    ->setAddress('Oxford Street');

$orderCreate = new OrderCreate();

$orderItem1 = new OrderItemWrite();
$orderItem1
    ->setName('Order item 1')
    ->setProductId(1)
    ->setProductType(ProductType::default())
    ->setPrice(4);

$orderItem2 = new OrderItemWrite();
$orderItem2
    ->setName('Order Item 2')
    ->setProductType(ProductType::default())
    ->setProductId(2)
    ->setPrice(2.4);

$orderItems = [$orderItem1, $orderItem2];

$orderCreate
    ->setBillpayer($billpayerWrite)
    ->setItems(...$orderItems);
        
$api->createOrder($orderCreate);
// "1"

通过 ID 更新订单

use VaniloCloud\WriteModels\OrderUpdate;
use VaniloCloud\Enums\OrderStatus;

$api = VaniloCloud\ApiClient::sandbox();

$orderUpdate = new OrderUpdate();
$orderUpdate
    ->setStatus(OrderStatus::PROCESSING);

$api->updateOrder(1, $orderUpdate);
// true

通过 ID 删除订单

$api = VaniloCloud\ApiClient::sandbox();

$api->deleteOrder(1);
// true