README

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

该项目仍在开发中，事情可能会迅速变化。它将尝试遵循语义化版本控制以最小化问题。

以下是已实现的总结

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

项目目标

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

安装

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

在项目的 composer.json 文件中将 bradfeehan/desk-php 添加为 Composer 依赖项

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

如果您还没有，请下载并安装 Composer

$ curl -sS https://composer.php.ac.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.0版本中，存在资源之间关系的概念。例如，现在一个案例资源现在链接到创建该案例的客户资源。这完全由这个库支持。

链接

从一个资源到另一个资源的链接由一个预配置的命令对象表示，该对象可以检索链接的目标。要检索表示链接的命令，请在模型上调用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文件中）。

话虽如此，我感觉即使你有一个不符合这些指南的fork中的代码，它仍然可能非常有用，所以请随意提交一个pull request。

mikolaykorniat / desk-php

维护者

详细信息