README

1. 简介

这是一个为 Zendesk 提供的 PHP 客户端库。完整的 API 文档可在 http://developer.zendesk.com/documentation/rest_api/introduction.html 找到。

此库使用 Guzzle 并提供了预配置的 Guzzel 客户端，用于与 Zendesk Web 服务进行通信。使用此客户端足以以与使用 PHP Curl 相同的方式处理所有资源，以低级 JSON 数据格式进行操作。

然而，该库旨在通过提供资源映射对象来提供更高层次的抽象。

此库仍在开发中。以下资源的高级（对象）支持可用：

• 工单 ✓
• 审核
• 用户
• 组
• 组成员
• 组织
• 查看执行/预览
• 主题
• 主题评论
• 请求

欢迎贡献和功能请求。

2. 安装

使用 composer，将其添加到您的 composer.json 中

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

如果您是 composer 的新手，以下是您需要采取的一些简单步骤。

1. 从上述链接下载 composer.phar
2. 创建一个名为 composer.json 的 json 文件，其中只包含上述 "require" 块
3. 将 composer.phar 和 composer.json 放在一起，您可以运行以下命令

php ./composer.phar install

1. composer 将创建一个名为 vendor 的目录，并将所有必需的库下载到其中。

2. 在 vendor 目录中，还有一个名为 autoload.php 的文件。这是库内部 PHP 自动加载器。您可能需要将其注册到现有的自动加载器中，或手动包含它。

3. 使用低级 API 客户端

此库包含一个配置好的 Guzzel 客户端，用于与 Zendesk 的 Web 服务通信。您不需要了解 Guzzel 就可以使用此客户端对象。

使用客户端意味着您正在使用低级 JSON 格式原始数据。您可以使用 Zendesk API 暴露的所有资源。但是，您可能会发现自己经常需要查阅 Zendesk 的文档以获取正确的资源 URL 端点和数据格式。

实例化客户端实例

// You will need to include this autoload script manually
// if you don't have any autoloader setup.
include "../path/to/vendor/autoload.php";

// one needs to declear the namespace for each class used
use Dlin\Zendesk\ZendeskApi

//Your Zendesk account email
$accountEmail = 'account.email@example.com';

//Your zendesk api token
$apiToken = 'c6EFbHZ7YsdggbIMSvOqiq3HduO';

//replace with your subdomain with zendesk
$apiUrl = 'https://[your-subdomain].zendesk.com/api/v2/';


//Instantiate the client class for later use
$client = new ZendeskApi($accountEmail, apiToken,$apiUrl);

...

查询资源

//Get tickets
$response = $api->get('tickets.json')->send()->json();

变量 $response 是一个数组，映射到服务器响应的 JSON 数据

{
  "tickets": [
    {
      "id":      35436,
      "subject": "Help I need somebody!",
      ...
    },
    {
      "id":      20057623,
      "subject": "Not just anybody!",
      ...
    },
  ]
}

这与 Zendesk 的 文档 页面中给出的示例完全相同。

以下是一些其他示例

//Get organization tickets
$response = $api->get('organizations/123/tickets.json')->send()->json();

//Get recent tickets
$response = $api->get('tickets/recent.json')->send()->json();

//Get one ticket (id = 123)
$response = $api->get('tickets/123.json')->send()->json();

要查询工单，需要正确的 API 端点 URL。

创建资源

创建资源也很简单。数据格式与 Zendesk 的 文档 页面中给出的完全相同。

//JSON encoded ticket string
$newTicket = '{"ticket":{"subject":"My printer is on fire!", "comment": { "body": "The smoke is very colorful." }}}';

//WebService URL endpoint
$endPoint = 'tickets.json';

//No need
$extraHttpHeader = null;

//Sent the request
$response = $api->post($endPoint, $extraHttpHeader, $ticket)->sent()->json();

响应将看起来像

{
  "ticket": {
    {
      "id":      35436,
      "subject": "My printer is on fire!",
      ...
    }
  }
}

更新资源

更新资源与创建资源非常相似。唯一的区别是应使用 PUT 方法而不是 POST

$updateData = '{"ticket":{"status":"solved",   \
       "comment":{"public":true, "body": "Thanks, this is now solved!"}}}';


//WebService URL endpoint
$endPoint = 'tickets/123.json'; //e.g. ticket id 123

//No need
$extraHttpHeader = null;

//Sent the request
$response = $api->put($endPoint, $extraHttpHeader, $ticket)->sent()->json();

响应数据

{
  "ticket": {
     "id":      35436,
     "subject": "My printer is on fire!",
     "status":  "solved",
     ...
  },
  "audit": {
     "events": [...],
     ...
  }
}

删除资源

要删除资源，请使用 DELETE 方法

//Specify the endpoint with the ID of the resource to be deleted
$endPoint = "tickets/{id}.json";

//delete
$response = $this->api->delete($end_point)->send();

//the response is empty but you can confirm the deletion by looking the response code
echo $response->getStatusCode(); // == 200;

4. 使用高级对象映射客户端

虽然低级的Guzzle客户端提供了与Zendesk API通信的全支持，但这个库提供的真正价值在于其高级资源客户端类。

资源客户端是上述低级客户端的包装类，为与主题资源交互提供了一个简单的接口（例如CRUD、搜索等）。

工单资源

1. 实例化一个工单资源客户端。

// You will need to include this autoload script manually
// if you don't have any autoloader setup.
include "../path/to/vendor/autoload.php";

// one needs to declear the namespace for each class used
use Dlin\Zendesk\ZendeskApi
use Dlin\Zendesk\Client\TicketClient;

//Your Zendesk account email
$accountEmail = 'account.email@example.com';

//Your zendesk api token
$apiToken = 'c6EFbHZ7YsdggbIMSvOqiq3HduO';

//replace with your subdomain with zendesk
$apiUrl = 'https://[your-subdomain].zendesk.com/api/v2/';


//Instantiate the client class for later use
$api = new ZendeskApi($accountEmail, apiToken,$apiUrl);

//Instantiate the Ticket Client
$ticketClient = new TicketClient($api);

#####2. 查询工单

在查询工单时，预期的返回结果可以是单个工单或工单集合。

当查询单个工单时，如果目标资源存在，则返回值是类型为Dlin\Zendesk\Entity\Ticket的实体，否则返回null。

然而，当查询工单集合时，Zendesk的API只能返回每请求100条工单的分页结果。此库使用类型Dlin\Zendesk\Result\PaginatedResult来封装返回的工单和其他有关分页的信息（例如，工单总数、当前页和每页工单数）

//Query a ticket by ID
$ticket = $ticketClient->getOneById(123);
echo $ticket->getId(); //123
echo $ticket->getSubject(); //Ticket subject



//Query tickets by an array of IDs
$paginatedResult = $ticketClient->getByIds(array(123, 124, 125));
//Get the tickets (array) from the result object
$tickets = $paginatedResult->getItems();


//Query all tickets
$paginatedResult = $ticketClient->getAll();
//Get the result tickets
$tickets=$paginatedResult->getItems();
//Get the total number of tickets
$count = $paginatedResult->getCount();
//Get current page of the pagination
echo $paginatedResult->getCurrentPage(); //1
//Get per page count of the pagination
echo $paginatedResult->getPerPage(); //100 (default)


/* =================================
 * Other supported quering methods
 * ================================= */


//Get recent tickets
$paginatedResult=$ticketClient->getRecent();

//Get tickets associated with a given organization (e.g. id:34)
$paginatedResult = $ticketClient->getOrganizationTickets(34);

//Get tickets requested by a given user (e.g. id:234)
$paginatedResult = $ticketClient->getUserRequestedTickets(234);

//Get CCD tickets by a given user (e.g. id:234)
$paginatedResult = $ticketClient->getUserCcdTickets(234);

#####3. 更多关于PaginatedResult类型的信息

大多数集合查询方法接受用于当前页和每页项目设置的可选参数。例如

//get page 2, 50 tickets per page
$paginatedResult = $ticketClient->getAll(1, 50);

//Same for other methods
$paginatedResult = $ticketClient->getRecent(1, 50);
$paginatedResult = $ticketClient->getOrganizationTickets(34, 1, 50);
$paginatedResult = $ticketClient->getUserRequestedTickets(234, 1, 50);
$paginatedResult = $ticketClient->getUserCcdTickets(234, 1, 50);

获取特定页的结果后，通常需要请求下一页或前一页的工单。PaginatedResult类型提供了两个处理方法来完成此操作

$paginatedResult = $ticketClient->getRecent(1, 50);
$nextPageResult = $paginatedResult->getNextResult();  //if no next page, null
$prevPageResult = $paginatedResult->getPreviousResult(); //this is null, no prev page

返回的结果又是同一类型 \Dlin\Zendesk\Result\PaginatedResult。这意味着您可以克服每请求100条工单的限制，并通过以下方式获取所有工单

//get the first 100 tickets
$paginatedResult = $ticketClient->getAll(1, 100);

$allTickets = $paginatedResult->getItems();

//get all the rest
while($result = $paginatedResult->getNextResult()){
	$allTickets = array_merge($allTickets, $result->getItems();
}

此外，\Dlin\Zendesk\Result\PaginatedResult实现了ArrayAccess和ICountable接口，这意味着您可以像访问数组一样访问结果对象中的工单

$paginatedResult = $ticketClient->getAll(1, 100);

echo count($paginatedResult); // 100;
echo count($paginatedResult->getItems()); //100;

foreach($paginatedResult as $ticket){
	echo $ticket->getId(); //e.g. 123
	...
}

#####3. 搜索工单

要搜索工单，必须提供一个类型为 \Dlin\Zendesk\Search\TicketFilter 的对象

$filter = new TicketFilter();
$filter->setSubject('Test Ticket Subject');

$searchResult = $ticketClient->search($filter);

同样，返回结果限制为100条工单。幸运的是，$searchResult是类型为 \Dlin\Zendesk\Result\PaginatedResult 的对象。可以使用getCoun、getItems和getNextResult方法来访问所有匹配的工单。

使用Zendesk API进行搜索是一个大话题。建议进行一些阅读。[链接](https://support.zendesk.com/entries/20239737)。特别是，如果想要找到多个单词的精确匹配，单词需要用双引号括起来。

$filter->setSubject('"My Subject"'); //the will do exact match against 'My Subject'

默认情况下，匹配是'：'（等于）匹配。对于匹配日期、数值和一些状态类型，也可以使用'>'和'<'进行匹配。

所有TicketFilter类的setter方法都接受数组值。这允许匹配范围

$criteria  = array();
$criteria['>'] = '2011-08-01';
$criteria['<'] = '2011-08-05';

$filter->setCreated($criteria); //searching tickets from 1st Aug to 5th Aug 2011

请注意，只支持'：'、'>'和'<'键。

#####4. 创建工单

创建工单很简单，只需创建一个Dlin\Zendesk\Entity\Ticket类型的对象，并调用客户端的save方法

$comment = new TicketComment();
$comment->setBody('TEST Ticket Comment');

$ticket = new Ticket();
$ticket->setComment($comment);
$ticket->setSubject('Test Ticket Subject By David Lin 1');
$ticket->setTags(array('test'));

//Optionally, you can specify a requester when creating ticket
$requester = new TicketRequester();
$requester->setName('Test Requester');
$requester->setEmail('test@email.com);

$result = $ticketClient->save($ticket, $requester); //more later for the $result

$result是一个类型为Dlin\Zendesk\Result\ChangeResult的对象，允许访问Audit对象和更新的工单。

$savedTicket = $result->getItem();
$audit = $result->getAudit();

请注意，在创建新工单时，原始工单对象不会被更新。它仅作为新工单的模板使用。您可以再次调用save方法来创建另一个工单或之后忽略它。

#####4. 更新工单创建工单的save方法也可以用来更新工单。结果格式与创建工单时相同，即ChangeResult实例。

$ticket = $ticketClient->getOneById(123);
$ticket->setSubject('Updated new subject');

//Updating using TicketClient::save()
$result = $ticketClient->save($ticket);

//Or you can do this
$ticket->save();

在更新工单时，库只提交上次更新/创建以来更新的/修改的字段到Zendesk服务器。

如果通过TicketClient对象检索工单，则称它由TicketClient“管理”，然后您可以调用Ticket对象本身的save方法来更新工单。在这种情况下，$ticket对象将加载更新后的数据（例如，最后更新时间戳）。Ticket::save()方法的返回结果是Dlin\Zendesk\Entity\TicketAudit类的实例，提供有关Audit资源的数据。

上述示例在更新之前请求获取票证。如果您知道您正在更新的票证ID，您也可以这样做

$ticket = new Ticket(123);
$tickets->setSubject('Updated subject') ;

//Updating using TicketClient::save()
$result = $ticketClient->save($ticket);


//Or manually manage the ticket
$ticketClient->manage($ticket);
$ticket->save();

您可以使用 manage 方法手动将票证对象添加到由票证客户端对象管理的对象中。

#####5. 删除票证

票证客户端类提供了两种删除票证的方法。

//delete one ticket
$ticketClient->deleteTicket(new Ticket(123));

//delete multiple tickets
$toDelete = array();
$toDelete[] = new Ticket(123);
$toDelete[] = new Ticket(124);
$ticketClient->deleteTickets($toDelete);


//OR using Ticket::delete() method
$ticket = new Ticket(123);
$ticketClient->manage($ticket);
$ticket->delete();

如果一个票证被票证客户端“管理”，无论是通过票证客户端获取还是由票证客户端手动管理，您可以调用 Ticket::delete() 方法来删除一个票证。

所有三个删除方法在成功时返回 true，失败时返回 false。

以下是一个示例，用于删除主题中包含“测试主题”的所有票证

$filter = new TicketFilter();
$filter->setSubject('test subject');

$searchResult = $ticketClient->search($filter);

$ticketClient->deleteTickets($searchResult->getItems());

5. 辅助类

为了便于使用资源类，有一些有用的辅助类可供使用。

枚举类

为了帮助避免拼写错误并便于查找值，有一些以有意义的名称分组常量类可供使用。您可以从类名中轻松地找出它们适合的位置

• SatisfactionRatingScore
• TicketPriority
• TicketStatus
• TicketType
• ...

枚举类扩展了 EnumBase 类，该类提供了两个有用的静态方法 keys() 和 values()

keys()

返回类的常量名称数组

values()

返回一个关联数组，其中常量名称作为键，其值作为值

6. 许可证

这个库是免费的。请参阅根目录中的许可证文件以获取详细的许可证信息。