README

The Zipmark PHP Client library is used to interact with Zipmark's API.

安装

下载和安装 Zipmark PHP 客户端最简单的方式是使用 git

git clone git://github.com/zipmark/zipmark-php.git /path/to/zipmark/client

要求

此库依赖于 PHP 5.3.6（或更高版本）以及带有 OpenSSL 支持的 libcurl。phpinfo(); 应显示以下信息

curl

cURL support => enabled
cURL Information => 7.21.4
Age => 3
Features
AsynchDNS => Yes
Debug => No
GSS-Negotiate => Yes
IDN => No
IPv6 => Yes
Largefile => Yes
NTLM => Yes
SPNEGO => No
SSL => Yes
SSPI => No
krb4 => No
libz => Yes
CharConv => No
Protocols => dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, pop3s, rtsp, smtp, smtps, telnet, tftp
Host => universal-apple-darwin11.0
SSL Version => OpenSSL/0.9.8r
ZLib Version => 1.2.5

openssl

OpenSSL support => enabled
OpenSSL Library Version => OpenSSL 0.9.8r 8 Feb 2011
OpenSSL Header Version => OpenSSL 0.9.8r 8 Feb 2011

初始化

Zipmark PHP 客户端支持全局和本地客户端凭据。客户端通过单个文件加载

require_once('./lib/zipmark.php');

使用示例

Zipmark PHP 客户端支持对象和对象列表。

实例化客户端

$client = new Zipmark_Client("Application Identifier", "Application Secret");

应用标识符和应用密钥应替换为 Zipmark 提供的供应商应用程序标识符和密钥。

生产模式

Zipmark PHP 客户端默认将访问 Zipmark 的沙盒环境。要将流量直接发送到 Zipmark 的生产环境，请使用以下方法启用生产模式

$client->setProduction(true);

根据已知的账单 ID 加载账单

$bill = $client->bills->get("Bill ID");

发现可用资源

$resources = $client->resources();

资源将包含所有可用资源的数组。

创建新的账单

创建账单对象，设置所需属性，将其发送到 Zipmark

$bill_data = array(
  'identifier'       => 'abc123',           // Unique Bill Identifier
  'amount_cents'     => 100,                // Bill amount in cents
  'bill_template_id' => 'UUID',             // UUID of Bill Template from Zipmark
  'memo'             => 'Memo to customer', // Text memo shown to customer
  'date'             => 'YYYY-MM-DD',       // Date of Bill issuance
  'content'          => '{}',               // JSON String with Bill content - rendered with template
);

$bill = $client->bills->create($bill_data);

作为替代，可以在保存之前首先构建对象

$bill_data = array(
  'identifier'       => 'abc123',           // Unique Bill Identifier
  'amount_cents'     => 100,                // Bill amount in cents
  'bill_template_id' => 'UUID',             // UUID of Bill Template from Zipmark
  'memo'             => 'Memo to customer', // Text memo shown to customer
  'date'             => 'YYYY-MM-DD',       // Date of Bill issuance
  'content'          => '{}',               // JSON String with Bill content - rendered with template
);

$bill = $client->bills->build($bill_data);

$bill->save();

更新现有账单

获取账单，进行更改，将其发送回 Zipmark

$bill = $client->bills->get("Bill ID");

$bill->memo = "Please pay with Zipmark";

$bill->save();

检索所有账单的列表

检索所有账单的列表。

$bills = $client->bills->getAll();

获取对象数量。

$bills->count();

基本迭代器

Zipmark_Iterator 类理解 Zipmark 的分页系统。它一次加载一页的对象，并在迭代对象时根据需要检索更多对象。

$bills = $client->bills->getAll();
$iterator = new Zipmark_Iterator($bills);

获取当前对象（如果迭代器已通过列表的任一端，则返回 null）

$bill = $iterator->current();

获取下一个/上一个对象（如果下一个/上一个对象将通过列表的任一端，则返回 null）

$bill = $iterator->next();
$bill = $iterator->prev();

迭代所有账单的列表

可以使用 Zipmark_Iterator 遍历给定资源类型的所有对象。

$iterator = new Zipmark_Iterator($client->bills->getAll());

foreach ($iterator as $bill) {
  print "Bill " . $iterator->key() . " is ID ";
  print $bill->id . " for " . $bill->amount_cents . " cents.\n";
}

这将产生类似以下输出

Bill 0 is ID 3cf1290adc08b28899dd7c7e263cca4dc9a2 for 1234 cents
Bill 1 is ID 3cf1b7bc6cfbaeb6b8b2a6001037d284c918 for 100 cents
Bill 2 is ID 3cea3cab019984233228c2eaff0edcbbb733 for 3456 cents
Bill 3 is ID 3ceaf09259f883159622aa4401ab7d06d45a for 2345 cents
Bill 4 is ID 3cea079b288120ffb129dfb62ae18de3dfee for 1234 cents
Bill 5 is ID 3ce95db62b1069e59e122c515eb191c70987 for 12345 cents
Bill 6 is ID 3ce627f7559478bee1129dae3203e373f0df for 1030 cents
Bill 7 is ID 3ce69e91d68417d1e9892ca903eba8c66a2e for 1030 cents
Bill 8 is ID 3ce6eb4a5b433f3e9b073d15a5ff725dec46 for 1020 cents
Bill 9 is ID 3ce66b0e9a510f90fb26906dd0da04df6de0 for 101 cents

回调处理

客户端能够处理、验证并从 Zipmark 服务收到的回调中提取数据。

加载回调响应

必须使用 Zipmark_Client 对象和 HTTP 回调内容（标头和正文）初始化 Zipmark_Callback 对象

在回调 POST 中发送的 HTTP 标头数组应包含在 $_SERVER 变量中。回调 POST 的正文应通过 call_file_get_contents('php://input'); 访问

$callback = new Zipmark_Callback($client, $httpHeaders, $httpBody);

验证回调

$callbackValid = $callback->isValid();

$callbackValid 将包含 true 或 false 值。

检索回调数据

有效的回调包含事件、对象类型和对象。以下函数将返回相应的值/对象，或如果回调无效，则返回 null。

$callbackEvent      = $callback->event();
$callbackObjectType = $callback->objectType();
$callbackObject     = $callback->object();

API 文档

请参阅Zipmark API或通过电子邮件或聊天联系 Zipmark 支持以获取更多信息。

单元/接受测试

Zipmark PHP 客户端库包括单元测试以验证所有实现的功能。单元测试使用SimpleTest构建，并可以从命令行运行

$ /path/to/zipmark/php/client/test/all_tests.php

zipmark / zipmark-php

维护者

详细信息