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属性，每个属性都有其getter和setter方法）
• 更新example.php文件以演示新方法的用法
• 测试代码（一旦feature/tests分支合并，提供单元测试）
• 提交和合并

这种更改必须放入Freshdesk\Rest的适当子类中的原因有两个。尽管这些方法只需要很少的其他信息（例如，票务ID，在assignTicket的情况下，还需要responderId），但这种方法强制用户使用数据模型。这反过来又使得类型提示变得更容易，从而便于调试并确保值正确。另一个优点是对象以引用的形式传递，这意味着将对象传递给方法意味着所有变量（无论作用域如何），都将引用该对象的最新实例，因此，数据更可能是准确的。

下面是一个简短的例子，以示完整，并为了说服怀疑者。

    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调用，因为每个属性和/或变量都引用单个实例。