README

API 客户端版本

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

API 版本支持

此客户端仅支持 Zendesk 的 API v2。请参阅我们的 API 文档以获取更多信息。

需求

PHP 5.5+

安装

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

Composer

要安装，请运行 composer require gjuric/zendesk_api_client_php

从 V1 升级到 V2

如果您正在从客户端的 v1 版本升级，我们编写了一份升级指南，突出了一些关键差异。

配置

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

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

use Zendesk\API\HttpClient as ZendeskAPI;

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

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

使用

基本操作

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

// Get all tickets regarding a specific user.
$tickets = $client->users($requesterId)->tickets()->requested();
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);

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

附件

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

将文件附加到评论中

$ticket = $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.', 
        'uploads'   => [$attachment->upload->token]                 
    ]                                           
]);

侧加载

侧加载允许您在单个请求中检索相关记录。请参阅 [文档] 以获取更多信息。 (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

重试请求

在您的 GuzzleHttp\Client 实例的 HandlerStack 上添加 RetryHandler 中间件。默认情况下，Zendesk\Api\HttpClient 重试

超时请求
那些抛出 Psr\Http\Message\RequestInterface\ConnectException:class
以及那些抛出 Psr\Http\Message\RequestInterface\RequestException:class 且被识别为 ssl 问题的。

可用选项

选项作为值数组传递给 RetryHandler。

max = 2 重试限制
interval = 300 重试间隔的基础延迟（毫秒）
max_interval = 20000 最大延迟值
backoff_factor = 1 退避因子
exceptions = [ConnectException::class] 不检查 retry_if 的异常重试
retry_if = null 可调用函数，可以决定是否重试请求

贡献

欢迎提交拉取请求，但在您发送一个之前，请阅读我们的贡献指南。这将加快处理速度，并确保每个人都遵循社区标准。

调试

为了帮助愿意贡献的人，我们增加了一个REPL工具。这是一个对psysh和symfony控制台的一个简单包装。在你的终端上，运行bin/console <子域名> <邮箱> <API令牌>。这将在$client变量上自动创建一个Zendesk\API\HttpClient实例。之后，你就可以输入任何有效的PHP语句。这个工具的目的是加快开发者对代码库进行实验的过程。

版权和许可

本软件遵循Apache License 2.0（以下简称“许可证”）；除非符合许可证规定或书面同意，否则不得使用本文件。您可以在以下网址获取许可证副本：

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

除非适用法律要求或书面同意，否则在许可证下分发的软件按“现状”基础分发，不提供任何形式的保证或条件，无论是明示的还是暗示的。请参阅许可证以了解具体规定权限和限制的语言。

gjuric / zendesk_api_client_php

维护者

详细信息