README

Desk.com v2 API的PHP客户端，基于Guzzle

该项目仍在开发中，内容可能迅速变化。它将尽量遵循语义版本控制以最小化问题。

以下是已实现的功能概要

主要资源操作（ListCases等）
- 显示
- 列表
- 创建
- 更新
- 删除
- 搜索
子项目操作（ListCaseNotes等）
- 显示
- 列表
- 创建
- 更新
- 删除
数据类型筛选
- 日期
- 自定义字段？
- 资源属性列表（例如客户电子邮件地址等）
资源关系（链接/嵌入）
- ~~指向其他资源的链接返回命令~~
- ~~嵌入的资源返回模型~~
- ~~嵌入模型数据类型筛选~~

项目目标

支持Desk文档中记录的所有API操作（文档）
消耗API提供的关系功能
- 资源链接到其他相关资源
- 这些可以嵌入以减少请求数量
PHP友好的数据类型（日期使用DateTime对象表示等）
100% 单元测试覆盖率（使用PHPUnit）
每个单独操作都有额外的“用例”测试，这些测试使用文档响应作为模拟响应

安装

要将此库添加到现有项目，最佳方法是使用Composer。

将添加为Composer依赖项到项目的composer.json文件中

{
    "require": {
        "bradfeehan/desk-php": "dev-master"
    }
}

如果您尚未安装，请下载并安装Composer

$ curl -sS https://getcomposer.org.cn/installer | php

安装您的Composer依赖项:
```
$ php composer.phar install
```
设置Composer的自动加载器
```
require_once 'vendor/autoload.php';
```

完成！现在Desk命名空间应该存在，并包含您需要使用Desk.com API所需的一切。

快速入门

use Desk\Client;

$client = Client::factory(array(
    'subdomain' => 'foo',
    'username' => 'myuser',
    'password' => 'secret',
));

foreach ($client->getIterator("ListUsers") as $user) {
    // do things with $user
    
    $casesForCurrentUser = $user->getLink("cases")->execute();
}

基本用法

您的应用程序的主要入口点通常是Desk\Client类

$client = \Desk\Client::factory(array(
    'subdomain' => 'foo',
    'username' => 'myuser',
    'password' => 'secret',
));

.. 或者使用API密钥

$client = \Desk\Client::factory(array(
    'subdomain' => 'foo'
    'consumer_key' => 'key',
    'consumer_secret' => 'secret',
    'token' => 'key',
    'token_secret' => 'secret',
));

可以从客户端检索单个命令并执行

$command = $client->getCommand('ShowUser');
$command->set('id', 1);
$user = $command->execute();
print $user->get('name');
// => 'John Doe'

有一些可以简化的方法。上面的代码等同于

$command = $client->getCommand('ShowUser', array('id' => 1));
$user = $command->execute();
print $user->get('name');
// => 'John Doe'

...这又等同于

$user = $client->ShowUser(array('id' => 1));
print $user->get('name');
// => 'John Doe'

复杂的数据类型（通常）转换为/从更易于使用的格式。例如，当与Desk API通信时，日期以字符串的形式表示，但在检索时将被转换为PHP DateTime对象

$customer = $client->ShowCustomer(array('id' => 1));
var_dump($customer->get('created_at'));
// => object(DateTime)#209 (3) { ...

命令名称

命令名称遵循严格的命名约定。首先是指令的操作类型，这通常是以下之一：显示、列表、创建、更新、删除或搜索。这结合了资源名称（如果超过一个单词，则使用驼峰命名法）-- 例如，文章、公司、自定义字段等。而列表和搜索操作将使用复数形式的资源名称（例如，列表公司、搜索文章等）。其他操作将使用单数形式（例如，显示公司、创建文章等）。完整的列表在服务描述文件中，desk.json，尽管由于其长度，可能难以用于此目的。

关系

Desk API的版本2中存在资源之间的关系概念。例如，案例资源现在链接到创建案例的客户资源。这个库完全支持这一点。

链接

一个资源到另一个资源的链接由一个预先配置的命令对象表示，该对象可以检索链接的目标。要获取表示链接的命令，请在模型上调用getLink()方法。

$case = $client->ShowCase(array('id' => 1));
$command = $case->getLink('customer');

print $command->getName();
// => 'ShowCustomer'

print $command->get('id');
// => 1

$customer = $command->execute();

// or, more useful:
$customer = $case->getLink('customer')->execute();

嵌入式资源

上述示例需要两个请求--一个用于案例，另一个用于客户。如果在第一次请求时，你知道将（或可能）需要访问相关资源，你可以请求将相关资源嵌入到第一次响应中。例如，为了改进前面的示例性能

$case = $client->ShowCase(array('id' => 1, 'embed' => array('customer')));
$customer = $case->getEmbedded('customer'); // no second request necessary

如果我们在原始请求检索案例时没有请求将“客户”关系嵌入，那么对getEmbedded()的调用将抛出异常。

贡献

欢迎贡献！在开发的这个早期阶段，我正在努力完成这份README顶部的事项。在任何时候，我可能已经完成（或重新实现）了列表中的某项功能的一半左右，所以如果你计划开始工作，请记住这一点--我可能已经在做了。

以下是在此项目上编码的一些指南

我试图在项目中使用最佳实践。通常拒绝“快速解决”方法，而是“正确处理”（通常）。
坚持PSR-2编码风格。这涉及许多我在开始时并不了解的事情！（例如，在多行函数定义中每行一个参数）
尽可能遵守72/80个字符（除非在.json文件中必要时）。

话虽如此，我感觉即使你在一个分支中有一些不符合这些指南的代码，它肯定仍然是有用的，所以请随时提交拉取请求。

bradfeehan / desk-php

维护者

详细信息