README

Shopiro PHP 客户端库是一个强大且易于使用的 PHP 客户端，用于与 Shopiro API 交互。这个全面的工具旨在简化与 Shopiro 的集成，成为希望在其应用程序中利用 Shopiro 功能的开发者的首选解决方案。

该库简化了向 Shopiro 平台发送请求、管理响应和处理错误的过程。它提供了一个直观的接口，使开发者能够专注于构建功能，无需担心底层网络通信的复杂性。通过抽象 HTTP 请求和响应的细节，Shopiro 客户端库使开发工作流程更快、更可靠。

除了基本请求处理之外，该库还提供了高级功能，如自动网络重试、请求排队和执行链式 API 请求，确保与 Shopiro API 的稳健和高效交互。其设计强调易用性和灵活性，能够适应从简单查询到复杂事务处理的多种用例。包含专用类，如 Listing 类和各种列表对象类型，进一步丰富了库的实用性，为 Shopiro 生态系统中的特定方面提供定制解决方案。这些类简化了列表创建、修改和检索等任务，为管理数据提供了一种结构化和可扩展的方法。凭借全面的文档、清晰的用法示例和遵循现代编码标准，Shopiro PHP 客户端库是希望充分发挥 Shopiro 全部潜能的开发者的不可或缺的工具。

要求

• PHP 8.0 或更高版本
• PHP 的 cURL 扩展
• PHP 的 mbstring 扩展

安装

通过 Composer

Composer 是一个 PHP 依赖关系管理工具，允许你声明项目依赖的库，它将为你管理（安装/更新）它们。

要在您的项目根目录中安装 Shopiro PHP 客户端库，请运行以下命令

composer require shopiro/shopiro-client

安装后，您需要要求 Composer 的自动加载器

<?php
require_once 'vendor/autoload.php';

此命令包含 Composer 自动加载器，它将自动加载 Shopiro PHP 客户端库类。

手动安装，无需 Composer

<?php
require_once '/path/to/Shopiro-PHP-Client/Init.php'; // Replace with the actual path

请确保您已下载库并指定了正确的 Init.php 路径。

用法

实例化

<?php
/*
Initialize Shopiro client
Replace 123456 with your application ID and 'your_private_key' with the private key obtained from Shopiro. These credentials, necessary for API authentication, can be acquired by registering your application at https://shopiro.ca/user/developer/applications
*/
$shopiro = new \Shopiro\ShopiroClient(123456, 'your_private_key');

低级别使用

以下是 ShopiroClient 的基本用法示例，请求可以以原始形式或使用特定范围的方

以下示例假设您已将 \Shopiro\ShopiroClient 初始化为 $shopiro，并拥有有效的凭证。

<?php
// Example: Create a request
$response = $shopiro->createRequest(
    ['request_type' => 'get', 'request_scope' => '', 'request_action' => 'listing']
);

// Handle response
if ($response['status'] === 'success') {
    // Process successful response
} elseif ($response['status'] === 'failed') {
    // Handle failure
}

使用 Listing 类及其方法

以下示例假设您已将 \Shopiro\ShopiroClient 初始化为 $shopiro，并拥有有效的凭证。

<?php
// Create a listing in a given platform segment using a type and data array or object
$response = $shopiro->Listing->create('type', []); // 'marketplace_low_volume' specifies the listing type, [] is the listing data

// Retrieve multiple listings with a specified count and offset for pagination
$allListings = $shopiro->Listing->getAll(10, 0); // Get 10 listings starting from the first one

// Retrieve a single listing using a Shopiro Listing ID (SLID)
$singleListing = $shopiro->Listing->get('SLID12345678901'); // SLID is a unique identifier for each listing

// Modify a listing using a data array or object including the SLID
$modifiedListing = $shopiro->Listing->modify(['slid' => 'SLID12345678901', 'new_data' => 'value']); // Modify specific listing details

// Delete a listing immediately using its SLID
$deletedListing = $shopiro->Listing->delete('SLID12345678901'); // Deletes the specified listing

// Create a new empty listing object for a given type
$listing = $shopiro->Listing->create("marketplace_low_volume"); // 'marketplace_low_volume' specifies the listing type

// Retrieve an existing listing as an object using its SLID
$listing = $shopiro->Listing->get('SLID12345678901');

// Set various properties of the listing using helper methods
$listing->setTitle('en', 'Example Product');
$listing->setDescription('en', 'This is a detailed description of the product.');
$listing->setShippingData(['weight' => 2, 'x_dimension' => 10, 'y_dimension' => 10]);

// Save the changes to the existing listing, or create a new one if it did not previously exist
$createdListing = $listing->save(); // Either updates the existing listing or creates a new one

使用 Address 类和对象

以下示例假设您已将 \Shopiro\ShopiroClient 初始化为 $shopiro，并拥有有效的凭证。

创建地址

<?php
// Create a new address using the specified type and data
$addressType = 'shipping'; // Example type
$addressData = [
    'first_name' => 'John',
    'last_name' => 'Doe',
    // ... other address data ...
];
$newAddress = $shopiro->Address->create($addressType, $addressData);

检索所有地址

<?php
// Retrieve multiple addresses with a specified count and offset for pagination
$allAddresses = $shopiro->Address->getAll(10, 0); // Get 10 addresses starting from the first one

检索单个地址

<?php
// Retrieve a single address by its ID
$singleAddress = $shopiro->Address->get(0123456789); // 0123456789 is an example address ID

修改地址

<?php
// Modify an existing address using address data
$addressData = [
    'addressid' => '0123456789', // Example address ID
    // ... other updated address data ...
];
$modifiedAddress = $shopiro->Address->modify($addressData);

设置地址为主地址

<?php
// Set a specific address as the primary address
$addressData = ['addressid' => '0123456789', 'type'=>'shipping']; // 0123456789 is an example address ID
$primaryAddress = $shopiro->Address->set_primary($addressData);

删除地址

<?php
// Delete an address immediately using its ID
$deletedAddress = $shopiro->Address->delete(0123456789); // 0123456789 is an example address ID

使用 AddressObject 进行详细操作

<?php
// Create a new AddressObject with initial details
$addressObject = $shopiro->Address->create([
    'type' => 'billing',
    'first_name' => 'Jane',
    'last_name' => 'Smith',
    // ... other address details ...
]);

// Modify or add additional details to the address
$addressObject->setCity('New York');
$addressObject->setCountry('US');
$addressObject->setSubdivision('US-AZ');
$addressObject->setAddressLine1('123 Example Blvd');
$addressObject->setAddressLine2('Unit 123');
$addressObject->setPostalCode('12345');
$addressObject->setPhoneNumber('12345');

// Override initial details or add new ones
$addressObject->setType('shipping');
$addressObject->setFirstName('John');
$addressObject->setLastName('Doe');

// Save the new or modified address
// This method either updates the existing address or creates a new one if it didn't previously exist
$savedAddress = $addressObject->save();

// Delete the address
// This method removes the address from the system
$result = $addressObject->delete();

特性

• 通过应用程序 ID 和私钥轻松初始化
• 支持 PHP 8.0 及以上版本
• 自动处理网络重试
• 请求排队和执行
• 最大链式 API 请求长度为 64
• 详细的错误处理和异常
• 通过 Listing 类和列表对象全面管理列表

API 参考

Shopiro API 文档可在 Shopiro API 文档 找到。

贡献

欢迎为Shopiro PHP客户端库做出贡献。请确保您的代码遵守我们现有的编码标准。

许可证

此库受MIT许可证的许可 - 有关详细信息，请参阅LICENSE文件。