README

Miva JSON Api PHP 库

PHP 库，用于与 Miva JSON API 进行交互。

安装

通过 Composer 安装。

$ composer require pdeans/miva-api

配置 Api 客户端

使用库与 API 交互是通过 Client 类实现的。该 Client 类接受一个数组，其中包含键/值格式的 Api 和 HTTP 客户端（cURL）配置选项。

客户端配置选项

示例

use pdeans\Miva\Api\Client;

$api = new Client([
    'url'          => 'https://www.domain.com/mm5/json.mvc',
    'store_code'   => 'PS',
    'access_token' => '0f90f77b58ca98836eba3d50f526f523',
    'private_key'  => '12345privatekey',
]);

// Example with Basic Authentication header and curl options
$api = new Client([
    'url'          => 'https://www.domain.com/mm5/json.mvc',
    'store_code'   => 'PS',
    'access_token' => '0f90f77b58ca98836eba3d50f526f523',
    'private_key'  => '12345privatekey',
    'http_headers' => [
        'Authorization' => 'Basic ' . base64_encode('username:password'),
        'Connection'    => 'close',
        'Cache-Control' => 'no-cache',
    ],
    'http_client' => [
        CURLOPT_SSL_VERIFYPEER => 0,
        CURLOPT_SSL_VERIFYHOST => 0,
    ],
]);

身份验证

Miva Api 授权头将根据传递给 Client 对象的配置设置自动生成，并随每个 Api 请求一起发送。配置设置应与给定 Api 令牌的 Miva 商店设置相匹配。

JSON 请求格式

所需的 Miva_Request_Timestamp 和 Store_Code 属性将根据传递给 Client 对象的配置设置自动生成，并将其添加到每个 Api 请求的 JSON 主体中。对于每个请求，还将自动添加 Function 属性。为 Function 属性生成的 JSON 数据将根据提供的请求函数列表而变化。

函数构建器

使用 func 方法生成 Api 请求函数。该方法接受请求函数名称作为其唯一参数。

使用 add 方法“发布”函数并将其附加到请求函数列表。

注意：所有函数构建器方法都是可链的。

$api->func('OrderCustomFieldList_Load')->add();

函数请求参数

本节展示了如何构建和添加函数参数。

常见过滤列表参数

每个针对 xxxList_Load_Query 函数的常见过滤列表参数都有一个相应的辅助方法来无缝设置参数值。下面的示例显示了每个方法的作用。

$api->func('OrderList_Load_Query')
    ->count(10)   // Limit number of records to return
    ->offset(5)   // Set offset of first record to return
    ->sort('id')  // Column sorting value
    // ->sort('-id')    // Column sorting value -descending
    // ->sortDesc('id') // Column sorting value with explicit descending
    ->filter('Customer_ID', 1850) // Add a filter
    ->add();

函数请求过滤器

大多数函数搜索/显示过滤器都有一个相关的辅助方法，用作简写或工厂来创建相应的过滤器。对于没有链接辅助方法的任何过滤器，必须使用 filter 方法，如上例所示。此方法也可以用于创建以下所述的每个过滤器。该方法接受两个参数，第一个参数始终是过滤器名称。第二个参数接受过滤器值，它将因过滤器类型而异。

以下将介绍可用的搜索/显示辅助方法。

搜索

可以使用 search 方法将搜索过滤器附加到函数的过滤器列表中。对 search 的最基本调用需要三个参数。第一个参数是搜索字段列。第二个参数是搜索运算符，可以是任何受支持的 Api 搜索运算符。最后，第三个参数是要与搜索列进行比较的值。

以下是一个为特定产品代码发出搜索过滤器的示例

$api->func('ProductList_Load_Query')
    ->search('code', 'EQ', 'test-product')
    ->add();

为了方便，如果您想验证一个列是否等于（'EQ'）给定的值，您可以直接将值作为 search 方法的第二个参数传递。以下与上述第一个示例的结果相同

$api->func('ProductList_Load_Query')
    ->search('code', 'test-product')
    ->add();

当然，在编写 search 过滤器时，您可以使用各种其他受支持的运算符

$api->func('ProductList_Load_Query')
    ->search('active', 'FALSE')
    ->add();

$api->func('ProductList_Load_Query')
    ->search('price', 'GE', 2.20)
    ->add();

$api->func('ProductList_Load_Query')
    ->search('Category', 'IN', '13707,13708')
    ->add();

可以多次发出 search 方法以执行 AND 搜索

$api->func('ProductList_Load_Query')
    ->search('Category', 'IN', '13707')
    ->search('price', 'GT', 19.86)
    ->add();

通过将数组传递给 search 方法作为第一个和唯一参数，可以执行 OR 搜索和括号内的比较。数组应按所需搜索值输出进行建模，并根据需要嵌套值

// OR search
$api->func('OrderList_Load_Query')
    ->search([
        [
            'field'    => 'ship_lname',
            'operator' => 'EQ',
            'value'    => 'Griffin',
        ],
        [
            'field'    => 'ship_lname',
            'operator' => 'EQ',
            'value'    => 'Star',
        ],
    ])
    ->add();

// Parenthetical search
$api->func('OrderList_Load_Query')
    ->search([
        [
            'field'    => 'ship_lname',
            'operator' => 'EQ',
            'value'    => 'Griffin',
        ],
        [
            'field'    => 'search_OR',
            'operator' => 'SUBWHERE',
            'value'    => [
                [
                    'field'    => 'ship_fname',
                    'operator' => 'EQ',
                    'value'    => 'Patrick',
                ],
                [
                    'field'    => 'ship_lname',
                    'operator' => 'EQ',
                    'value'    => 'Star',
                ],
            ],
        ],
    ])
    ->add();

按需列

使用 ondemandcolumns 方法，您可以指定要返回的显式列。该方法接受一个参数，即要选择的按需列列表

$api->func('ProductList_Load_Query')
    ->ondemandcolumns(['catcount', 'productinventorysettings'])
    ->add();

为了方便，可以使用 odc 方法作为 ondemandcolumns 方法的别名

$api->func('ProductList_Load_Query')
    ->odc(['catcount', 'productinventorysettings'])
    ->add();

显示

可以使用 show 方法创建 "显示" 过滤器。该方法接受一个参数，即显示过滤器值，它将因每个 xxxList_Load_Query 函数而异。请注意，此过滤器目前仅适用于以下函数

CategoryList_Load_Query
CategoryProductList_Load_Query
ProductList_Load_Query

示例

$api->func('ProductList_Load_Query')->show('Active')->add();

函数请求输入参数

密码短语

使用 passphrase 方法设置密码参数。该方法接受一个参数，即解密密码。

$api->func('OrderList_Load_Query')
    ->odc(['payment_data', 'customer', 'items', 'charges'])
    ->passphrase('helloworldhelloworld@123')
    ->add();

附加输入参数

使用 params 方法设置所有其他输入参数。此方法的示例用例包括 Xx_Create / Xx_Insert / Xx_Update / Xx_Delete 函数的请求体参数，Module 级别函数以及几乎所有需要特定输入参数以执行操作的其他函数。该函数接受一个键/值数组，该数组映射到输入参数键/值，作为其唯一参数。

示例

// Example: Create A New Product
$api->func('Product_Insert')
    ->params([
        'product_code' => 'new-product',
        'product_name' => 'New Product',
    ])
    ->add();

// Example: Update Product Inventory
$api->func('Product_Update')
    ->params([
        'product_code'      => 'new-product',
        'product_inventory' => 250,
    ])
    ->add();

// Example: Load An Order Queue
$api->func('Module')
    ->params([
        'Module_Code'     => 'orderworkflow',
        'Module_Function' => 'QueueOrderList_Load_Query',
        'Queue_Code'      => 'new_updated_orders',
    ])
    ->add();

// Example: Acknowledge An Order
$api->func('Module')
    ->params([
        'Module_Code'     => 'orderworkflow',
        'Module_Function' => 'OrderList_Acknowledge',
        'Order_Ids'       => [1000, 10001, 10002],
    ])
    ->add();

// Example: Create A Shipment
$api->func('OrderItemList_CreateShipment')
    ->params([
        'Order_Id' => '200103',
        'line_ids' => [100, 101],
    ])
    ->add();

// Example: Update Shipments
$api->func('OrderShipmentList_Update')
    ->params([
        'Shipment_Updates' => [
            [
                'shpmnt_id'    => 1,
                'mark_shipped' => true,
                'tracknum'     => '1234567890',
                'tracktype'    => 'UPS',
                'cost'         => 5,
            ], [
                'shpmnt_id'    => 2,
                'mark_shipped' => true,
                'tracknum'     => '0987654321',
                'tracktype'    => 'USPS',
            ],
        ],
    ])
    ->add();

API 请求

本节涵盖了配置和发出 Api 请求。

HTTP 头部

您可以使用 addHeader 和 addHeaders 方法指定附加到所有 Api 请求的 HTTP 头。请注意，库会自动创建并附加 Content-Type: application/json 和 X-Miva-API-Authorization 头到每个 Api 请求中。

// Add single header at a time
$api->addHeader('Custom-Header-Name', 'custom-header-value');
$api->addHeader('Cache-Control', 'no-cache');

// Add multiple headers in one swoop
$api->addHeaders([
    'Custom-Header-Name'=> 'custom-header-value',
    'Cache-Control'=> 'no-cache',
]);

发送请求

send 方法将发出 Api 请求，并将结果返回为库的 Response 对象。如果您想绕过此对象并返回 Api 的原始 JSON 响应，请将 true 值作为 send 方法的第一个参数传递。

示例请求

// First add functions to request function list
$api->func('ProductList_Load_Query')
    ->search('code', 'prod1')
    ->add();

$api->func('CategoryList_Load_Query')
    ->sortDesc('id')
    ->count(5)
    ->filter('Category_Show', 'Active')
    ->add();

// Issue Api request - returns \pdeans\Miva\Api\Response object
$response = $api->send();

// Alternatively - returns raw JSON response
$response = $api->send(true);

您可以使用 getRequestBody 方法在任何时候在发送请求之前预览当前请求体。这对于调试请求很有帮助。

echo '<pre>', $api->getRequestBody(), '</pre>';

API 响应

默认情况下，Api 响应将返回一个 pdeans\Miva\Api\Response 类实例。该 Response 对象包含许多用于与 Api 响应交互的辅助方法。

检查请求错误

可以使用 getErrors 方法检查 Api 请求中可能发生的错误。该方法将返回一个包含错误代码和错误消息的 stdClass 对象。该 isSuccess 方法返回一个布尔值，可以用作标志以确定是否发生了请求错误

$response = $api->func('ProductList_Load_Query')->add()->send();
var_dump($response->getErrors());

if (!$response->isSuccess()) {
   echo 'Error: ', $response->getErrors()->message;
}

响应体

任何时候都可以使用 getBody 方法检索原始 JSON 响应体

// Print raw JSON Api response
$response = $api->func('ProductList_Load_Query')->add()->send();
echo '<pre>', $response->getBody(), '</pre>';

要获取Api响应的可迭代形式，请调用getResponse方法。这将返回一个对象数组，数组的键映射到传递给Api请求函数列表的函数名。项目按与Api请求函数列表相同的顺序排序。每个项目或“函数”包含其自己的函数请求结果的数组。这些数组项与请求中发送的每个函数的迭代相对应。项目按请求中发布的顺序排序。使用getFunctions方法获取可用函数列表。

可以使用getFunction方法显式返回特定函数名的响应结果。这也可以通过将函数名作为第一个参数传递给getResponse方法来实现。

getData方法返回特定函数名的响应data属性。默认情况下，返回提供的函数名的第一个迭代索引的data属性。但是，可以提供一个可选的第二个参数，以返回给定函数名的特定迭代索引的data属性。

示例

// Add functions to request function list
$api->func('ProductList_Load_Query')->add();
$api->func('OrderCustomFieldList_Load')->add();
$response = $api->send();

// Full response array
$results = $response->getResponse();
var_dump($results);

// Access function key on response array
var_dump($results['OrderCustomFieldList_Load']);

// Results are also iterable (same for result items)
foreach ($results as $result) {
    var_dump($result);
}

// Return list of available functions in the response
var_dump($response->getFunctions());

// Isolate and return responses for specific function
var_dump($response->getFunction('ProductList_Load_Query'));
var_dump($response->getResponse('OrderCustomFieldList_Load'));

// Add functions to request function list
$api->func('ProductList_Load_Query')->add();
$api->func('ProductList_Load_Query')->count(5)->add();
$api->func('ProductList_Load_Query')->count(10)->add();
$response = $api->send();

/**
 * Get the response "data" property for specific function.
 * Defaults to the first iteration index result for the given function.
 */
var_dump($response->getData('ProductList_Load_Query'));
/**
 * Use the optional second parameter to return the "data" property for
 * a specific iteration index. The example below will return the "data"
 * property for the 3rd iteration result on the given function.
 */
var_dump($response->getData('ProductList_Load_Query', 2));

辅助工具

本节介绍了库辅助方法。

处理 API 请求和响应的故障排除

为了帮助解决Api请求和响应的问题，可以使用getPreviousRequest和getPreviousResponse方法分别获取PSR-7请求和PSR-7响应对象，这些方法在发出Api请求后调用。

// Add functions to request function list
$api->func('ProductList_Load_Query')->add();
$api->func('OrderCustomFieldList_Load')->add();
$response = $api->send();

// Output Api request authentication header value
echo $api->getPreviousRequest()->getHeader('X-Miva-API-Authorization')[0];

// Output the response HTTP status line
$prevResponse = $api->getPreviousResponse();
echo $prevResponse->getStatusCode(), ' ', $prevResponse->getReasonPhrase();

此外，可以使用getUrl、getHeaders和getFunctionList方法来检查和解决在发送到Api之前的请求。

// Output Api endpoint url
echo $api->getUrl();

// Output request header list
$api->addHeader('Custom-Header-Name', 'custom-header-value');
var_dump($api->getHeaders());

// Output request function list
$api->func('ProductList_Load_Query')->add();
$api->func('OrderCustomFieldList_Load')->add();
var_dump($api->getFunctionList());

进一步阅读

在开始使用库之前，了解Miva JSON Api的配置和模式非常有帮助。

pdeans / miva-api

维护者

详细信息