vanilo/cloud-sdk

Vanilo Cloud API 的 SDK

0.6.0 2024-08-26 14:36 UTC

This package is auto-updated.

Last update: 2024-09-19 09:57:06 UTC


README

Tests Packagist version Packagist downloads StyleCI MIT Software License

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

Vanilo Cloud PHP Code Sample

安装

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

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

composer require vanilo/cloud-sdk

使用方法

身份验证

要连接到 Vanilo Cloud API,您需要商店的 URL、client_idclient_secret

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

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

在底层,SDK 将从 API 中获取身份验证令牌,以最大限度地减少在网络上发送 client_idclient_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 响应,则需要调用 rawGetrawPost 等方法

$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