README

此客户端可用于通过 PHP 访问开源帮助台 Zammad 的 API。

Zammad 版本支持

此客户端支持 Zammad 3.4.1 及更高版本。

安装

要求

API 客户端需要 composer。有关安装，请参阅其文档。此外，API 客户端需要 PHP 7.2 或更高版本。

集成到您的项目中

将以下内容添加到您的项目 composer.json 文件的 "require" 部分

"zammad/zammad-api-client-php": "^2.0"

安装 API 客户端的依赖项

使用 composer 更新您的项目依赖项以获取 API 客户端的代码及其依赖项

$ composer update

安装完成后，您需要将生成的 autoload.php 包含到您的项目代码中

require_once dirname(__DIR__).'/vendor/autoload.php';

如何使用 API 客户端

示例代码

您可以在 examples 目录中找到示例代码。

客户端对象

您的起点是 Client 对象

use ZammadAPIClient\Client;
$client = new Client([
    'url'           => 'https://myzammad.com', // URL to your Zammad installation
    'username'      => 'myuser@myzammad.com',  // Username to use for authentication
    'password'      => 'mypassword',           // Password to use for authentication
    // 'timeout'       => 15,                  // Sets timeout for requests, defaults to 5 seconds, 0: no timeout
    // 'debug'         => true,                // Enables debug output
    // 'verify'        => true,                // Enabled SSL verification. You can also give a path to a CA bundle file. Default is true.
]);

除了使用 username 和 password 的组合外，您还可以提供 http_token 或 oauth2_token。 重要：您必须在 Zammad 中激活 API 访问。

通过 ID 获取单个资源对象

要通过 ID 获取 Resource 对象，例如 ID 为 34 的票据，请使用 Client 对象

use ZammadAPIClient\ResourceType;
$ticket = $client->resource( ResourceType::TICKET )->get(34);

$ticket 现在是一个 Resource 对象，它包含票据的数据并提供了设置/获取特定值（如票据标题）和将更改的值发送到 Zammad 以更新票据的所有方法。

注意：一旦您在 Resource 对象上成功调用了 get，则不能再调用它，相反，您必须使用 resource 创建一个新的对象。

访问资源对象的值

您可以通过资源对象的 'value' 方法访问其值。

$ticket->setValue( 'title', 'My ticket title' );
$title = $ticket->getValue('title');
$all_values = $ticket->getValues();

请注意，API 客户端既不提供对资源对象可用的字段的检查，也不知道这些字段。如果您设置或获取了不存在字段的值或设置了无效值，Zammad 将忽略它或返回错误。

那么，您如何知道哪些字段可用呢？只需获取一个现有的 Resource 对象并查看返回的字段。一个全新的 Zammad 系统总是为每种资源类型包含一个 ID 为 1 的对象。

此外，您还可以查看 Zammad 的 REST 接口文档

REST 接口简介

获取票据的文章

如果您已经有一个票据对象，您可以轻松地获取其文章

$ticket_articles = $ticket->getTicketArticles();

获取票据文章附件的内容

您可以使用票据文章资源对象的 getAttachmentContent() 调用来获取票据文章附件的内容

$attachment_content = $ticket_article->getAttachmentContent(23);

在上面的示例中，23 是附件的 ID。此 ID 可在票据文章数据的 attachments 数组中找到。通常您想遍历此数组以获取所有附件的内容。

更新资源对象

如果您获取了一个 Resource 对象并更改了一些值，您必须将更改发送到 Zammad。您可以通过简单的调用来完成此操作

$ticket->save();

save() 将自行检查，但如果您需要知道一个 Resource 对象是否有未保存的更改，可以使用以下方式进行检查

if ( $ticket->isDirty() ) {...}

注意：某些资源类型不支持更新某些字段的值。请参阅API文档（见上方链接）。

创建资源对象

要创建一个新的 Resource 对象，请使用以下代码（示例）

use ZammadAPIClient\ResourceType;

$ticket = $client->resource( ResourceType::TICKET );
$ticket->setValue( 'title', 'My new ticket' );
// ...
// Set additional values
// ...
$ticket->save(); // Will create a new ticket object in Zammad

搜索资源对象

某些类型的资源可以进行搜索，支持分页。

use ZammadAPIClient\ResourceType;

// Fulltext search
$tickets = $client->resource( ResourceType::TICKET )->search('some text');

// Field specific search
$tickets = $client->resource( ResourceType::TICKET )->search('title:My Title');

// Field specific search with more than one field
$tickets = $client->resource( ResourceType::TICKET )->search('title:My Title AND priority_id:1');

// Pagination: Page 1, 25 entries per page
$tickets = $client->resource( ResourceType::TICKET )->search( 'some text', 1, 25 );

请注意，服务器端对返回的对象数量有一个可配置的限制（例如500）。此限制也适用于每页的条目数。如果您以每页1000条条目的方式调用 search()，而服务器端限制设置为500，则将应用服务器端限制。

成功的搜索（可能没有结果）将返回一个对象数组（或一个空数组）。如果结果是原始调用者对象，则表示发生了错误（请参阅下面的错误处理）。因此，搜索的代码应如下所示

use ZammadAPIClient\ResourceType;

$tickets = $client->resource( ResourceType::TICKET )->search('some text');
if ( !is_array($tickets) ) {
    // Error handling
    print $tickets->getError();
}
else {
    // Do something with $tickets array
}

注意：您不能使用包含数据的 Resource 对象（通过 get、search、all 或在新的对象上设置值）来执行搜索。请使用新的 Resource 对象。

获取所有资源对象

对于某些类型的资源，可以获取所有可用的对象，支持分页。

use ZammadAPIClient\ResourceType;

// Fetch all tickets (keep in mind the server-side limit, see 'Searching Resource objects')
$tickets = $client->resource( ResourceType::TICKET )->all();

// Fetch all tickets with pagination (keep in mind the server-side limit, see 'Searching Resource objects'), page 4, 50 entries per page
$tickets = $client->resource( ResourceType::TICKET )->all( 4, 50 );

成功的 all 调用（可能没有结果）将返回一个对象数组（或一个空数组）。如果结果是原始调用者对象，则表示发生了错误（请参阅下面的错误处理）。因此，使用 all 的代码应如下所示

use ZammadAPIClient\ResourceType;

$tickets = $client->resource( ResourceType::TICKET )->all( 4, 50 ); // pagination
if ( !is_array($tickets) ) {
    // Error handling
    print $tickets->getError();
}
else {
    // Do something with $tickets array
}

注意：您不能使用包含数据的 Resource 对象（通过 get、search、all 或在新的对象上设置值）来执行 all。请使用新的 Resource 对象。

删除资源对象

要能够删除存在于 Zammad 中的 Resource 对象，您必须首先通过 get、all 或 search 从 Zammad 获取它。您还可以删除尚未发送到 Zammad 的新创建的 Resource 对象。但这种情况很少有必要，因为您可以通过 Client 对象简单地创建一个新的 Resource 对象。要删除 Resource 对象，只需在其上调用 delete 即可

$ticket->delete();

这将清除对象中的所有数据，并在可能的情况下将其从 Zammad 中删除。PHP 对象本身仍然存在。您可以将其用于另一个 Resource 对象或简单地丢弃它。

使用标签

向对象添加标签

Zammad 可以将标签分配给对象。目前这仅支持工单对象。

use ZammadAPIClient\ResourceType;

// The third parameter 'Ticket' is the object type for which the ID will be given as first parameter.
$client->resource( ResourceType::TAG )->add( $ticket_id, 'tag 1', 'Ticket' );

从对象中移除标签

use ZammadAPIClient\ResourceType;

$client->resource( ResourceType::TAG )->remove( $ticket_id, 'tag 1', 'Ticket' );

获取分配给对象的全部标签

use ZammadAPIClient\ResourceType;

// The second parameter 'Ticket' is the object type for which the ID will be given as first parameter.
$tag = $client->resource( ResourceType::TAG )->get( $ticket_id, 'Ticket' );

// [ 'tag 1', 'tag 2' ]
$tags = $tag->getValue('tags')

搜索标签

use ZammadAPIClient\ResourceType;

$tags = $client->resource( ResourceType::TAG )->search('my tag');

对象导入

除了为对象提供的常规方法外，还可以通过 CSV 导入这些方法。例如，文本模块 CSV 导入的示例

use ZammadAPIClient\ResourceType;

$text_modules_csv_string = file_get_contents('text_modules.csv');

$client->resource( ResourceType::TEXT_MODULE )->import($text_modules_csv_string);

有关支持 CSV 导入的资源类型及其访问方法，请参阅下方的 可用资源类型及其访问方法。

处理 Zammad 错误

当您访问 Zammad 时，您总是将获得一个 Resource 对象（或一个此类对象的数组）作为返回，无论 Zammad 是否返回数据或执行了您的请求。在发生错误的情况下（例如，上面提到的ID为34的工单在 Zammad 中不存在），您将获得一个设置有错误的 Resource 对象，可以使用以下代码进行检查

if ( $ticket->hasError() ) {
    print $ticket->getError();
}

如果您还需要更多有关连接/请求错误的详细信息，可以访问 Client 对象的 Response 对象。它包含最后做出的请求的响应。

$last_response = $client->getLastResponse();

使用此对象，您可以例如获取最后一个响应的 HTTP 状态码和正文。

代表另一个用户执行 API 调用

如果您想使用Zammad代表其他用户执行API调用，而不仅仅是您用于认证的用户，请在执行API调用之前使用以下代码：

$client->setOnBehalfOfUser('myuser');

上述代码之后的任何API调用都将使用此设置。如果您想回到使用用于认证的用户，请调用

$client->unsetOnBehalfOfUser();

在此设置之前，Zammad将忽略此设置。

可用的资源类型及其访问方法

要使用资源类型的“简短形式”，请将

use ZammadAPIClient\ResourceType;

添加到您的代码中。然后您可以像这样引用资源类型

$client->resource( ResourceType::TICKET );

发布

将发布添加到 CHANGELOG.md
提交、标记并推送。
作为已登录用户，使用 packagist.org 页面上的“更新”按钮来自动从git标记创建新版本。

贡献

欢迎在 GitHub 上提交错误报告和拉取请求。该项目旨在成为一个安全、友好的协作空间，并期望贡献者遵守贡献者公约行为准则。

zammad / zammad-api-client-php

维护者

详细信息