README

php-sdk

PortaText API 的官方 PHP 客户端。

文档

• 本源代码的自动生成文档可以在 doc 目录中找到。
• 端点测试（endpoint tests）也应该是使用 API 的良好文档。
• PortaText 的一般文档（包括 REST API）可以在 PortaText wiki 中找到。

安装

将此库添加到您的 Composer 配置中。在 composer.json 中

  "require": {
    "portatext/php-sdk": "1.*"
  }

基本使用

获取客户端实例

首先，获取一个 Client 实例，例如 Curl 实现

use PortaText\Client\Curl as Client;
$portatext = new Client();

（可选）设置您的日志记录器

您可以可选地设置一个 PSR-3 兼容的日志记录器

$portatext->setLogger($logger);

默认情况下，客户端将使用 NullLogger。

认证

您可以使用您的 API 密钥 或用户名/密码来认证端点。这相当于执行以下操作

$client->setApiKey($apiKey);

或者这个

$client->setCredentials($username, $password);

当您指定 用户名和密码 而不是 API 密钥时，SDK 将自动登录并在需要时获取 会话令牌。

使用端点

所有 API 命令都可以在 Command/Api 目录中找到。客户端提供了一种通过仅按其名称调用它们来实例化它们的方法。

快速示例

例如，要创建一个模板，您将这样做

$result = $client
  ->templates()                       // Get an instance of the Templates endpoint.
  ->text("The text of my template")
  ->description("My first template")
  ->name("template1")
  ->post();                           // Call the Templates endpoint with a POST.

要按 ID 获取模板

$result = $client->templates()->id(45)->get();

或，获取所有模板

$result = $client->templates()->get();

结果

调用端点后，可能会发生以下两种情况之一

• 抛出了一个 PortaText 异常。
• 返回了一个 Result 实例。

此外，如果可能的话，您的 PortaText 异常将包含一个可以通过在异常上调用 getResult() 来获取的 Result 对象。这通常对 ClientError 异常很有用，您将能够看到字段是否缺失或与预期不同。

成功测试

if ($result->success) {
    ...
}

从服务器获取错误字符串

if (!is_null($result->errors)) {
    foreach ($result->errors as $error) {
        ...
  }
}

从服务器获取数据

if ($result->success) {
    $data = $result->data;
}

开发者

此项目使用 phing。当前任务包括

• test: 运行 PHPUnit。
• cs: 运行 CodeSniffer。
• doc: 运行 PhpDocumentor。
• md: 运行 PHPMD。
• build: 这是默认任务，将运行所有其他任务。

运行 phing 任务

要运行一个任务，只需这样做

vendor/bin/phing build

贡献

要贡献

• 确保您打开一个 简洁 和 简短 的 pull request。
• 添加任何必要的单元测试以适应新代码或涉及的更改。
• 运行 phing 并确保在提交 pull request 之前一切正常（让 phpmd 和 CodeSniffer 满意，还要确保 phpDocumentor 不抛出任何警告，因为所有我们的文档都是自动生成的）。
• 您的代码必须符合 PSR-2，CodeSniffer 应该会处理这一点。
• 如果您的代码被接受，它将属于 PortaText，并将在 Apache2 许可证下发布。

许可

源代码在 Apache 2 许可证下发布。

查看 LICENSE 文件以获取更多信息。