README

Redmine API的一个简单的PHP面向对象封装。

使用Redmine API。

功能

• 遵循PSR-4约定和编码标准：自动加载友好
• 选择使用原生cURL函数或任何PSR-18 HTTP客户端实现（如Guzzle）来处理HTTP连接
• 中级别API例如。

  $client->getApi('issue')->create(['project_id' => 1, 'subject' => 'issue title']);

• 低级别API例如。

  $client->requestPost('/issues.json', '{"issue":{"project_id":1,"subject":"issue title"}}');

支持的Redmine版本

我们支持（并对以下版本进行测试）接收安全更新的最新支持的Redmine版本。

• Redmine 5.1.x
• Redmine 5.0.x
• Redmine 4.2.x

尽管如此，您也可以使用此库的所有旧版Redmine。但是，请注意，您的Redmine服务器可能不支持某些功能。

如果新的Redmine版本启用了此库尚不支持的新功能，您可以通过创建问题。

要求

• PHP ^7.4 || ^8.0
• PHP SimpleXML 扩展
• PHP JSON 扩展
• 在您的Redmine服务器上启用了REST web服务
  • 转到管理 -> 设置 -> Api (/settings/edit?tab=api) 并勾选“启用REST web服务”框
  • 在您的个人资料页面中获取您的API访问密钥：/my/account
  • （或使用您的用户名 & 密码；不推荐）

可选

• 如果需要使用原生的cURL函数，则需PHP cURL 扩展。
• 为运行测试套件PHPUnit >= 9.0（可选）

待办事项

• 在#305中跟踪Redmine API功能支持
• 检查响应头中的状态码（特别是对于POST/PUT/DELETE请求）
  • 请参阅https://stackoverflow.com/questions/9183178/php-curl-retrieving-response-headers-and-body-in-a-single-request/9183272#9183272

局限性 / 缺失的Redmine-API

Redmine缺少一些API，无法完全远程管理数据

• 活动列表 & 角色列表：https://redmine.ruby-lang.org.cn/issues/11464
• 由于缺少Redmine API而导致的开放问题

安装

使用Composer，您可以在项目根目录中简单地运行

$ php composer.phar require kbsali/redmine-api

要使用此库，请将Composer的vendor/autoload.php包含到将使用Redmine类的脚本中。

例如，

<?php
// This file is generated by Composer
require_once 'vendor/autoload.php';

$client = new \Redmine\Client\NativeCurlClient('https://redmine.example.com', '0ef19567656532f8dd43a4dbfeda787f01f3e659');

请按照以下说明进行手动安装：说明链接。

运行测试套件

您可以通过运行项目目录下的vendor/bin/phpunit来运行测试套件，以确保库在您的系统上可以正常工作。

$ vendor/bin/phpunit
PHPUnit 9.5.4 by Sebastian Bergmann and contributors.

Warning:       No code coverage driver available

...............................................................  63 / 432 ( 14%)
............................................................... 126 / 432 ( 29%)
............................................................... 189 / 432 ( 43%)
............................................................... 252 / 432 ( 58%)
............................................................... 315 / 432 ( 72%)
............................................................... 378 / 432 ( 87%)
......................................................          432 / 432 (100%)

Time: 00:00.149, Memory: 14.00 MB

OK (432 tests, 1098 assertions)

php-redmine-api客户端的基本用法

开始您的项目

创建您的项目，例如在index.php中通过引入vendor/autoload.php文件来实现。

+<?php
+
+require_once 'vendor/autoload.php';

实例化Redmine客户端

您可以选择以下之一：

1. 本机curl客户端或
2. PSR-18兼容客户端。

1. 本机curl客户端 Redmine\Client\NativeCurlClient

💡 该客户端自php-redmine-api v1.8.0版引入。如果您正在使用旧的Redmine\Client，请参阅此迁移指南以帮助升级您的代码。

您需要一个指向您的Redmine实例的URL以及一个有效的Apikey...

<?php

require_once 'vendor/autoload.php';
+
+// Instantiate with ApiKey
+$client = new \Redmine\Client\NativeCurlClient('https://redmine.example.com', '1234567890abcdfgh');

... 或者有效的用户名/密码。

<?php

require_once 'vendor/autoload.php';
+
+// Instantiate with Username/Password (not recommended)
+$client = new \Redmine\Client\NativeCurlClient('https://redmine.example.com', 'username', 'password');

💡 由于安全原因，建议您使用ApiKey而不是用户名/密码。

cURL配置

实例化客户端后，您可以设置一些可选的cURL设置。

<?php

require_once 'vendor/autoload.php';

// Instantiate with ApiKey
$client = new Redmine\Client\NativeCurlClient('https://redmine.example.com', '1234567890abcdfgh');
+
+// [OPTIONAL] if you want to check the servers' SSL certificate on Curl call
+$client->setCurlOption(CURLOPT_SSL_VERIFYPEER, true);
+
+// [OPTIONAL] set the port (it will try to guess it from the url)
+$client->setCurlOption(CURLOPT_PORT, 8080);
+
+// [OPTIONAL] set a custom host
+$client->setCurlOption(CURLOPT_HTTPHEADER, ['Host: https://custom.example.com']);

2. PSR-18兼容客户端 Redmine\Client\Psr18Client

💡 该客户端自该库的v1.7.0版引入。如果您正在使用旧的Redmine\Client，请遵循此迁移指南。

Psr18Client需要

• 一个Psr\Http\Client\ClientInterface实现（如guzzlehttp/guzzle），查看
• 一个Psr\Http\Message\RequestFactoryInterface实现（如guzzlehttp/psr7），查看
• 一个Psr\Http\Message\StreamFactoryInterface实现（如guzzlehttp/psr7），查看
• 指向您的Redmine实例的URL
• 一个Apikey或用户名
• 以及可选的密码（如果您想使用用户名/密码）。

💡 由于安全原因，建议您使用ApiKey而不是用户名/密码。

<?php

require_once 'vendor/autoload.php';
+
+$guzzle = new \GuzzleHttp\Client();
+$psr17Factory = new \GuzzleHttp\Psr7\HttpFactory();
+
+// Instantiate with ApiKey
+$client = new \Redmine\Client\Psr18Client(
+    $guzzle,
+    $psr17Factory,
+    $psr17Factory,
+    'https://redmine.example.com',
+    '1234567890abcdfgh'
+);
+// ...or Instantiate with Username/Password (not recommended)
+$client = new \Redmine\Client\Psr18Client(
+    $guzzle,
+    $psr17Factory,
+    $psr17Factory,
+    'https://redmine.example.com',
+    'username',
+    'password'
+);

Guzzle配置

由于Psr18Client对HTTP客户端实现是中立的，因此针对传输的特定配置必须设置到Psr\Http\Client\ClientInterface实现中。

这意味着，如果您想将任何cURL设置设置到Guzzle，您有多种方式可以设置它们

1. 使用Guzzle环境变量
2. 使用请求选项在Psr\Http\Client\ClientInterface包装器内

<?php

require_once 'vendor/autoload.php';

+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
$guzzle = \GuzzleHttp\Client();
$psr17Factory = new \Nyholm\Psr7\Factory\Psr17Factory();

+$guzzleWrapper = new class(\GuzzleHttp\Client $guzzle) implements ClientInterface
+{
+    private $guzzle;
+
+    public function __construct(\GuzzleHttp\Client $guzzle)
+    {
+        $this->guzzle = $guzzle;
+    }
+
+    public function sendRequest(RequestInterface $request): ResponseInterface
+    {
+        return $this->guzzle->send($request, [
+            // Set the options for every request here
+            'auth' => ['username', 'password', 'digest'],
+            'cert' => ['/path/server.pem', 'password'],
+            'connect_timeout' => 3.14,
+            // Set specific CURL options, see https://docs.guzzlephp.org/en/stable/faq.html#how-can-i-add-custom-curl-options
+            'curl' => [
+                CURLOPT_SSL_VERIFYPEER => 1,
+                CURLOPT_SSL_VERIFYHOST => 2,
+                CURLOPT_SSLVERSION => CURL_SSLVERSION_TLSv1_2,
+            ],
+        ]);
+    }
+};
+
// Instantiate with ApiKey
$client = new \Redmine\Client\Psr18Client(
-    $guzzle,
+    $guzzleWrapper,
    $psr17Factory,
    $psr17Factory,
    'https://redmine.example.com',
    '1234567890abcdfgh'
);

内置的Redmine功能

模拟用户

Redmine允许您使用startImpersonateUser()和stopImpersonateUser()方法模拟其他用户。这可以通过使用以下方法来完成：

$client->startImpersonateUser('kim');
// all requests will now impersonate the user `kim`

// To stop impersonation
$client->stopImpersonateUser();

API使用

您现在可以使用getApi()方法创建和获取特定的Redmine API。

<?php

$client->getApi('user')->list();
$client->getApi('user')->listLogins();

$client->getApi('issue')->create([
    'project_id'  => 'test',
    'subject'     => 'some subject',
    'description' => 'a long description blablabla',
    'assigned_to_id' => 123, // or 'assigned_to' => 'user1' OR 'groupXX'
]);
$client->getApi('issue')->list([
    'limit' => 1000
]);

请参阅更多示例并在文档中了解更多关于使用的信息.

感谢！

• 感谢Thomas Spycher为类的第一个版本做出贡献。
• 感谢Thibault Duplessis aka. ornicar为php-github-api库做出贡献，这是一个灵感之源！
• 以及所有贡献者
• 特别感谢JanMalte对测试覆盖率的巨大贡献！ :)