README

FreshDesk.com PHP API 封装器

"composer-aware edition"。

亮点

显然，Composer，除此之外，这个功能分支还提供

• 命名空间支持
• 一个可轻松扩展的 "Rest" 类
• 将变成 100% 面向对象（不再传递大量字符串数据）
• 易于与像 Zend、Symfony2 这样的 MVC 框架集成

改进方法

1. 仍在进行中：关注点分离需要大量的工作（目前正在 feature/beta 分支中处理）
2. 更好的文档 + 如何贡献的 WIKI
3. 开箱即用的过滤器、状态等支持（通过类常量）
4. 已添加测试，但仍可改进

使用方法

将此仓库添加到您的 composer.json 文件中，以将此仓库用作直接依赖项。

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/EVODelavega/freshdesk-rest.git"
        }
    ],
    "require": {
        "EVODelavega/freshdesk-rest": "dev-master"
    }
}

此软件包也已添加到 Packagist。Packagist 只接受小写包名，因此只需添加以下内容即可

{
    "require": {
        "evodelavega/freshdesk-rest": "dev-master"
    }
}

如果您打算使用此封装器在 Freshdesk 中创建新工单，您可以使用 postUpdate/postInstall 脚本来设置 Freshdesk\Model\Ticket 类中的 cc-email 常量。要自动配置此常量，请将以下内容添加到 composer.json 文件中的 scripts 部分（注意：此功能已弃用）

"scripts": {
    "post-install-cmd": [
        "Freshdesk\\Config\\Composer::postUpdate"
    ],
    "post-update-cmd": [
        "Freshdesk\\Config\\Composer::postUpdate"
    ]
}

示例用法（从 example.php 文件中获取）

<?php
use Freshdesk\Config\Connection,
    Freshdesk\Rest;// for backwards compatibility with existing code, use alias: use Freshdesk\Rest as FreshdeskRest;
$fd = new Rest(
    new Connection(
        'https://<user>:<password>@<domain>'
    )
);
$apiExample = new Rest(
    new Connection(
        'http://<API_KEY>:X@<domain>'
    )
);

注意

此代码遵循 PHP-FIG 制定的编码标准，并添加了一些 Symfony2 风格。例如，异常的消息由 sprintf 和 vsprintf 函数返回。

然而，我给自己带来了一些罪恶的乐趣：整个代码库都使用了 Allman 风格缩进。

## 贡献当然，任何贡献都将受到极大的欢迎。如果您想贡献，请记住以下几点

1. 通过向适当的 Freshdesk\Rest 的 子 类中添加相应的方法来添加对某些当前缺失的 API 调用的支持
2. 在整个代码中使用的编码标准应该得到尊重。不符合标准的拉取请求将不会合并
3. 报告问题而没有补丁或 PR 是可以接受的，也是受欢迎的，但请完整地描述问题以及/或建议的解决方案
4. 尽可能多地记录代码。我们目前的代码需要更多的文档，添加未记录的代码只会增加问题...
5. 尽可能使用数据模型（Freshdesk\Model 命名空间）。此 API 的目标是提供一个 清晰且安全 的接口，类型提示是此接口的重要组成部分。

作为一个例子：最初，此封装器不支持删除和分配工单。用户必须自己扩展 Freshdesk\Ticket 类，或者创建一个 Freshdesk\Rest 的新子类，并编写自己的方法。这个问题已经按以下方式解决

• 创建一个 feature/delete-ticket 分支
• 向 Freshdesk\Ticket 中添加方法，因为删除、恢复和分配工单显然是 Ticket API 类的事务
• 相应地修改 Freshdesk\Model\Ticket 类（添加 responderId 和 deleted 属性，每个属性都有自己的获取器和设置器方法）
• 更新 example.php 文件以展示新方法的用法
• 测试代码（一旦合并到feature/tests分支，提供单元测试）
• 提交并合并

这种更改必须进入Freshdesk\Rest适当子目录的原因有两个。尽管这些方法需要的只是票据ID（在assignTicket的情况下，还需要响应者ID），但这种方法强制用户使用数据模型。这反过来又使得类型提示更容易调试和保证值检查。另一个优点是对象作为引用传递，这意味着将对象传递给方法意味着所有变量，无论作用域如何，都将引用对象的最新实例，因此数据更可能是准确的。

为了完整性，以及为了说服怀疑者，下面是一个快速示例

    public function someMethod()
	{
		$db = new PDO($dsn, $usr, $pass, $options);
		$stmt = $db->prepare('SELECT ticketId FROM helpdesk.tickets WHERE clientId = :cid AND status = :status');
		$stmt->execute([':cid' => 1, ':status' => \Freshdesk\Model\Ticket::STATUS_PENDING]);
		$row = $stmt->fetch(PDO::FETCH_OBJ);
		$ticket = new \Freshdesk\Model\Ticket(['displayId' => $row->ticketId]);//create instance
		//...more code
		$anotherObject->setTicket($ticket);
		//...some more calls, possibly in another method:
		$api = new \Freshdesk\Ticket(
			new \Freshdesk\Config\Connection(
				'https://<api-key>:X@<domain>'
			)
		);
		//complete the ticket via the API
		$api->getFullTicket($ticket);
		//...more code
		$anotherObject->getTicket();//<-- returns the updated ticket model
	}

在这种情况下，票据实例被用于多个地方。因为整个API使用数据模型，我们可以节省昂贵的API调用，因为每个属性和/或变量都引用单个实例。