vanilo / cloud-sdk
Vanilo Cloud API 的 SDK
Requires
- php: ^8.1
- guzzlehttp/guzzle: ^7.4
- illuminate/collections: >8
- illuminate/http: ^8.83|^9.0|^10.0|^11.0
- nesbot/carbon: ^2.53.1
Requires (Dev)
- ext-apcu: *
- illuminate/cache: >8
- orchestra/testbench: ^6.8|^7.0|^8.0|^9.0
- phpunit/phpunit: ^9.5|^10.0
Suggests
- ext-apcu: Required to use the ApcTokenStore
- illuminate/cache: Required for the LaravelTokenStore ^8.0
This package is auto-updated.
Last update: 2024-09-19 09:57:06 UTC
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