README

API 客户端版本

这是我们 PHP API 客户端的第二个版本。API 客户端的旧版本可以在 v1 分支 上找到。

API 版本支持

此客户端 仅 支持 Zendesk 的 API v2。有关更多信息，请参阅我们的 API 文档。

要求

• PHP 5.5+

安装

可以使用 Composer 安装 Zendesk PHP API 客户端。

Composer

在 composer.json 中指定以下内容

{
  "require": {
    "zendesk/zendesk_api_client_php": "dev-master"
  }
}

从 V1 升级到 V2

如果您正在从客户端的 v1 升级，我们已编写了一份 升级指南，以突出显示一些主要差异。

配置

配置是通过 Zendesk\API\HttpClient 的实例完成的。该代码块是强制性的，如果不传递，将抛出错误。

// load Composer
require 'vendor/autoload.php';

use Zendesk\API\HttpClient as ZendeskAPI;

$subdomain = "subdomain";
$username  = "email@company.com";
$token     = "6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv"; // replace this with your token

$client = new ZendeskAPI($subdomain, $username);
$client->setAuth('basic', ['username' => $username, 'token' => $token]);

使用方法

基本操作

// Get all tickets
$tickets = $client->tickets()->findAll();
print_r($tickets);

// Create a new ticket
$newTicket = $client->tickets()->create([
    'subject'  => 'The quick brown fox jumps over the lazy dog',
    'comment'  => [
        'body' => 'Lorem ipsum dolor sit amet, consectetur adipisicing elit, ' .
                  'sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.'
    ],
    'priority' => 'normal'
]);
print_r($newTicket);

// Update a ticket
$client->tickets()->update(123,[
    'priority' => 'high'
]);

// Delete a ticket
$client->tickets()->delete(123);

附件

$attachment = $client->attachments()->upload([
    'file' => getcwd().'/tests/assets/UK.png',
    'type' => 'image/png',
    'name' => 'UK.png' // Optional parameter, will default to filename.ext
]);

测试套件

测试套件通过 phpunit 运行。请注意，这些都是针对真实 Zendesk 实例的实时测试。凭证可以通过设置 phpunit.xml 中的环境变量来提供；在 phpunit.xml.dist 中提供了一个示例。

运行单元测试： vendor/bin/phpunit --testsuite "Zendesk API 单元测试套件"

运行实时测试： vendor/bin/phpunit --testsuite "Zendesk API 实时测试套件"

侧载

侧载允许您在单个请求中检索相关记录。有关更多信息，请参阅 [文档](https://developer.zendesk.com/rest_api/docs/core/side_loading)。 (https://developer.zendesk.com/rest_api/docs/core/side_loading)。

以下是一个使用客户端进行侧载的示例。

$tickets = $client->tickets()->sideload(['users', 'groups'])->findAll();

分页

Zendesk API 提供了一种获取请求的下一页的方法，并在 Zendesk 开发者文档 中进行了说明。

这样做的方法是将它作为选项传递给您的请求。

$tickets = $this->client->tickets()->findAll(['per_page' => 10, 'page' => 2]);

允许的选项有

• per_page
• page
• sort_order

编码标准

本项目严格遵循 PSR-2 编码标准。

PHP Codesniffer 用于验证是否遵循标准。

除了我们尽量遵循的 PSR-2 标准之外，我们还要遵循以下规则

PHPDoc

所有类、类方法和属性都应具有 docblocs。

类

类 docblocks 应包含

• 类的简短描述
• 通过魔法方法调用的任何方法及其返回值。

一个好的例子是

/**
 * Client class, base level access
 *
 * @method Debug debug()
 * @method Tickets ticket()
 * @method Views views()
 */

方法

方法 docblocks 应包含

• 方法的简短描述。
• 传递的参数及其类型。
• 参数的描述（可选，示例）。
• 返回值的类型。
• 方法可能抛出的所有可能的异常。

这个的一个好的例子是

/**
 * Find a specific ticket by id or series of ids
 *
 * @param integer|null $id
 * @param array        $queryParams
 *
 * @return Array
 *
 * @throws MissingParametersException
 * @throws \Exception
 */

属性

类属性 docblocs 应包含

• 属性的简短描述（可选）
• 变量类型

此属性的示例

/**
 * This contains the Auth object to be used for authenticating with the Client
 *
 * @var Zendesk\API\Utilities\Auth
 */

数组

推荐使用短表示法声明数组（[]），而不是较长的 array()。

将 => 与最长的键对齐，使数组更易于阅读。

[
    'findAll'             => "users/{userId}/{$this->resourceName}.json",
    'find'                => "users/{userId}/{$this->resourceName}/{id}.json",
    'update'              => "users/{userId}/{$this->resourceName}/{id}.json",
    'makePrimary'         => "users/{userId}/{$this->resourceName}/{id}/make_primary.json",
    'verify'              => "users/{userId}/{$this->resourceName}/{id}/verify.json",
    'requestVerification' => "users/{userId}/{$this->resourceName}/{id}/request_verification.json",
    'delete'              => "users/{userId}/{$this->resourceName}/{id}.json",
    'create'              => "users/{userId}/{$this->resourceName}.json",
    'createAsEndUser'     => "end_users/{userId}/{$this->resourceName}.json",
]

分组赋值语句

对分组赋值语句中的 = 进行对齐。

$headers             = 'sample';
$lastRequestBody     = 'example';
$lastResponseCode    = 'something';
$lastResponseHeaders = 'test';
$lastResponseError   = 'test2';

特性

声明

• 特性添加在类常量之后，并且在声明时按字母顺序排列。
• 通过在每组之后添加新行相应地分组特性。
• 分组顺序如下

1. 实例化器
2. 单个资源
3. 批量特性

资源特性

添加资源时，使用特性来定义可用的API调用。资源特性位于 Zendesk\API\Traits\Resource 命名空间下。

单个资源

• 创建
• 删除
• 查找
• 查找所有
• 更新
• 默认值 - 这将添加 查找、查找所有、创建、更新 和 删除

批量特性

• 创建多个
• 删除多个
• 查找多个
• 更新多个
• 创建或更新多个

实用特性

当您希望资源可链接到其他资源时，请使用 Zendesk\API\Traits\Utility\InstantiatorTrait。请参阅 Zendesk/API/Resources/Tickets.php。

$this->client->tickets()->comments()->findAll();

关于补丁/拉取请求的说明

1. 分支项目。
2. 添加您的功能或修复错误。
3. 为其添加测试。这很重要，这样我们就不可能在未来的版本中无意中破坏您的改进。
4. 请遵循上面描述的 编码标准。
5. 提交并不要更改版本或历史记录。（如果您想要自己的版本，那也可以，但是请将版本单独提交，这样我在拉取时可以忽略）
6. 发送拉取请求。对于主题分支有额外加分。

版权和许可

版权所有 2013-现在 Zendesk

根据 Apache 许可证版本 2.0（“许可证”）许可；除非根据适用法律或书面同意，否则不得使用此文件，除非符合许可证。您可以在以下位置获得许可证副本：

https://apache.ac.cn/licenses/LICENSE-2.0

除非适用法律要求或经书面同意，否则在许可证下分发的软件按“原样”提供，不提供任何明示或暗示的保证或条件。有关许可证的具体语言管辖权限和限制，请参阅许可证。