README

快速开始使用Snipcart的API的最简单、最快的方法。

第一步

• 注册一个账户并获取API密钥
• Snipcart开发者文档

安装

通过Composer安装

composer require mtownsend/snipcart-api

此包可以与任何PHP 7.0+应用程序一起使用，但特别支持Laravel。

注册服务提供者（Laravel用户）

对于Laravel 5.4及以下版本，请在您的config/app.php中添加以下行：

/*
 * Package Service Providers...
 */
Mtownsend\SnipcartApi\Providers\SnipcartApiServiceProvider::class,

对于Laravel 5.5及以上版本，包将自动为您注册提供者。

使用Lumen

要注册服务提供者，请将以下行添加到app/bootstrap/app.php中：

$app->register(Mtownsend\SnipcartApi\Providers\SnipcartApiServiceProvider::class);

发布配置文件（Laravel用户）

php artisan vendor:publish --provider="Mtownsend\SnipcartApi\Providers\SnipcartApiServiceProvider"

一旦您的snipcart.php已发布到您的配置文件夹，请添加从Snipcart获取的API密钥。如果您使用Laravel并将Snipcart API密钥放入配置文件中，Laravel将自动设置您的API密钥，每次通过助手或外观实例化类时都会设置。

快速入门

使用类

use Mtownsend\SnipcartApi\SnipcartApi;

$orders = (new SnipcartApi($apiKey))->get()->from('/orders')->send();

HTTP方法

此包支持RESTful HTTP方法，包括GET（默认）、POST、PUT、PATCH和DELETE。

GET示例

// Get a list of orders with a query string of ?limit=10&offset=5&status=Processed
$orders = (new SnipcartApi($apiKey))->get()->from('/orders')->payload([
	'limit' => 10,
	'offset' => 5,
	'status' => 'Processed'
])->send();

POST示例

// Post a refund
$refund = (new SnipcartApi($apiKey))->post()->payload([
	'token' => '6dc8e374-7e30-4dc5-9b68-2d605819e7f0',
	'amount' => 5.00,
	'comment' => "We're refunding $5 for your order."
])->to('/orders/6dc8e374-7e30-4dc5-9b68-2d605819e7f0/refunds')->send();

PUT示例

// Update a product
$product = (new SnipcartApi($apiKey))->put()->payload([
	'stock' => 200,
	'allowOutOfStockPurchases' => false
])->to('/products/3932ecd1-6508-4209-a7c6-8da4cc75590d')->send();

DELETE示例

// Delete an allowed domain from your Snipcart account
$domain = (new SnipcartApi($apiKey))->delete()->payload([
	[
		[
			'domain' => 'subdomain.my-website.com',
			'protocol' => 'https'
		],
	]
])->from('/settings/alloweddomains')->send();

类方法

->to(string '/url') 或 ->from(string '/url')

to 或 from 方法是相同的，仅存在是为了使您的语法更具语义意义（get()->from() 或 post()->to()）。这些方法期望接收一个相对URL路径，该路径是您尝试与其通信的Snipcart端点。例如，如果您要从https://app.snipcart.com/api/orders获取订单列表，您将使用您选择的方法并传递一个参数为/orders的参数。

注意：无论您是在前面、后面、两边都添加斜杠，还是都不添加，该包都会优雅地处理您对相对URL的前面和后面斜杠的使用。以下任何示例都是可接受的参数：/orders/、/orders、orders/ 或 orders。

->payload(array ['key' => 'value']) 或 ->payload('key', 'value')

payload 方法允许您通过请求传递数据。

如果请求是GET操作，则payload将转换为有效的查询字符串。例如，['from' => '2018-05-05', 'to' => '2019-05-05']将生成?from=2018-05-05&to=2019-05-05并自动附加到您的请求URL。

或者，如果您更喜欢手动包含查询字符串以进行GET请求，您可以完全省略payload方法，并将查询字符串附加到to/from方法。例如，->get()->from('/orders?limit=10&offset=5')->send()。

如果请求是POST、PUT、PATCH或DELETE操作，则payload将自动转换为json并作为请求正文发送。

->send()

send 方法触发了API调用被发送，并返回响应。

->addHeader(string 'key', string 'value')

addHeader 方法接受两个参数。第一个是头键，第二个是头值。默认情况下，此包会为您设置Accept和Content-Type。

->addHeaders(array ['key' => 'value'])

addHeaders 方法接受一个键值对的关联数组，用于设置 API 请求的头信息。

->responseCode()

responseCode 方法返回服务器为请求返回的 HTTP 状态码。注意：此方法仅应在将 API 调用拆分为多个变量时使用。

->successful()

successful 方法解析从服务器接收的 HTTP 状态码，并检查是否有任何 2XX 状态码，然后返回一个布尔值。注意：此方法仅应在将 API 调用拆分为多个变量时使用。

检查失败的 API 调用

Snipcart 的 API 在许多情况下都提供了优雅的错误处理。如果你对一个端点（如 /does-not-exist）进行 API 调用，响应将会是 null。在尝试执行任何逻辑之前，你可以使用简单的 if 语句轻松检查请求对象的值。

$response = (new SnipcartApi($apiKey))->get()->from('/does-not-exist')->send();
if (!$response) {
	// api call failed
}
// else: do something with the response data...

或者，如果你更喜欢将 API 调用拆分为多个变量，SnipcartApi 类提供了一个 successful 方法。

$call = (new SnipcartApi($apiKey))->get()->from('/does-not-exist');
$response = $call->send();
if (!$call->successful()) {
	// api call failed
}
// else: do something with the response data...

使用全局助手（Laravel 用户）

如果你正在使用 Laravel，此包提供了一个全局可访问的便捷助手函数。包会自动从你的 config/snipcart.php 文件设置你的 API 密钥。

snipcart()->get()->from('/orders')->send();

使用外观（Laravel 用户）

如果你正在使用 Laravel，此包提供了一个外观。要将外观注册到应用程序中，请将以下行添加到 config/app.php 中的 aliases 键下。包会自动从你的 config/snipcart.php 文件设置你的 API 密钥。

'Snipcart' => Mtownsend\SnipcartApi\Facades\SnipcartApi::class,

use Snipcart;

Snipcart::get()->from('/orders')->send();

致谢

• Mark Townsend
• 所有贡献者

测试

测试即将推出...

你可以使用以下命令运行测试

./vendor/bin/phpunit

许可证

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件。