kbsali/redmine-api

Redmine API client

Monday, November 13, 2017
by kbsali
Repository
41 Watchers
340 Stars
177,625 Installations

PHP
20 Dependents
0 Suggesters
153 Forks
16 Open issues
55 Versions
8 % Grown

The README.md

PHP Redmine API

, _(*1)

A simple PHP Object Oriented wrapper for Redmine API., _(*2)

Uses Redmine API., _(*3)

Features

Follows PSR-4 conventions and coding standard: autoload friendly
Choose between using native cURL function or any PSR-18 HTTP client implementation like Guzzle for handling http connections

mid-level API e.g., _(*4)

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

$response = $client->getApi('issue')->getLastResponse();

low-level API e.g. php $response = $client->request( HttpFactory::makeJsonRequest( 'POST', '/issues.json', '{"issue":{"project_id":1,"subject":"issue title"}}', ), );

Supported Redmine versions

We support (and run tests against) the latest supported Redmine versions that receive security updates., _(*5)

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

Nevertheless, you can also use this library for all older Redmine versions. In this case, however, be aware that some features might not be supported by your Redmine server., _(*6)

If a new Redmine version enables new features that are not yet supported with this library, you are welcome to create an issue., _(*7)

Requirements

PHP ^7.4 || ^8.0
The PHP SimpleXML extension
The PHP JSON extension
Enabled REST web service on your Redmine server
- Go to Administration -> Settings -> Api (/settings/edit?tab=api) and check the "Enable REST web service" box
- Obtain your API access key in your profile page: /my/account
- (or use your username & password; not recommended)

Optional

The PHP cURL extension if you want to use the native cURL functions.
PHPUnit >= 9.0 (optional) to run the test suite

Todo

Tracking of Redmine API feature support in #305
Check header's response code (especially for POST/PUT/DELETE requests)
- See https://stackoverflow.com/questions/9183178/php-curl-retrieving-response-headers-and-body-in-a-single-request/9183272#9183272

Limitations / Missing Redmine-API

Redmine is missing some APIs for a full remote management of the data:, _(*8)

List of activities & roles: https://www.redmine.org/issues/11464
Open issues because of missing Redmine API

Install

By using Composer you can simply run:, _(*9)

$ php composer.phar require kbsali/redmine-api

at the root of your projects. To utilize the library, include Composer's vendor/autoload.php in the scripts that will use the Redmine classes., _(*10)

For example,, _(*11)

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

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

For a manual installation please follow this instruction., _(*12)

Running the test suite

You can run test suite to make sure the library will work properly on your system. Simply run vendor/bin/phpunit in the project's directory :, _(*13)

$ 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)

Basic usage of `php-redmine-api` client

Start your project

Create your project e.g. in the index.php by require the vendor/autoload.php file., _(*14)

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

Instantiate a Redmine Client

You can choose between:, _(*15)

a native curl client or
the PSR-18 compatible client.

1. Native curl Client `Redmine\Client\NativeCurlClient`

:bulb: This client was introduced in php-redmine-api v1.8.0. If you are using the old Redmine\Client please see this migration guide for help to upgrade your code., _(*16)

You will need a URL to your Redmine instance and either a valid Apikey..., _(*17)

<?php

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

... or valid username/password., _(*18)

<?php

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

:bulb: For security reason it is recommended that you use an ApiKey rather than your username/password., _(*19)

cURL configuration

After you instantiate a client you can set some optional cURL settings., _(*20)

<?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 compatible Client `Redmine\Client\Psr18Client`

:bulb: This client was introduced in v1.7.0 of this library. If you are using the old Redmine\Client please follow this migration guide., _(*21)

The Psr18Client requires, _(*22)

a Psr\Http\Client\ClientInterface implementation (like guzzlehttp/guzzle), see
a Psr\Http\Message\RequestFactoryInterface implementation (like guzzlehttp/psr7), see
a Psr\Http\Message\StreamFactoryInterface implementation (like guzzlehttp/psr7), see
a URL to your Redmine instance
an Apikey or username
and optional a password if you want tu use username/password.

:bulb: For security reason it is recommended that you use an ApiKey rather than your username/password., _(*23)

<?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 configuration

Because the Psr18Client is agnostic about the HTTP client implementation every configuration specific to the transport has to be set to the Psr\Http\Client\ClientInterface implementation., _(*24)

This means that if you want to set any cURL settings to Guzzle you have multiple ways to set them:, _(*25)

Using Guzzle environment variables
Using request options inside a Psr\Http\Client\ClientInterface wrapper:

<?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'
);

Built-in Redmine features

Impersonate User

Redmine allows you to impersonate another user. This can be done using the methods startImpersonateUser() and stopImpersonateUser()., _(*26)

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

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

API usage

You can now use the getApi() method to create and get a specific Redmine API., _(*27)

<?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
]);

See further examples and read more about usage in the docs., _(*28)

Thanks!

Thanks to Thomas Spycher for the 1st version of the class.
Thanks to Thibault Duplessis aka. ornicar for the php-github-api library, great source of inspiration!
And all the contributors
specially JanMalte for his impressive contribution to the test coverage! :)

The Versions

13/11 2017

dev-master

9999999-dev https://github.com/kbsali/php-redmine-api

Redmine API client

library redmine-api

Redmine API client

kbsali/redmine-api

The README.md

PHP Redmine API

Features

Supported Redmine versions

Requirements

Optional

Todo

Limitations / Missing Redmine-API

Install

Running the test suite

Basic usage of php-redmine-api client

Start your project

Instantiate a Redmine Client

1. Native curl Client Redmine\Client\NativeCurlClient

cURL configuration

2. Psr-18 compatible Client Redmine\Client\Psr18Client

Guzzle configuration

Built-in Redmine features

Impersonate User

API usage

Thanks!

The Versions

dev-master

The Requires

The Development Requires

by Kevin Saliou

v1.5.16

The Requires

The Development Requires

by Kevin Saliou

v1.5.15

The Requires

The Development Requires

by Kevin Saliou

v1.5.14

The Requires

The Development Requires

by Kevin Saliou

v1.5.13

The Requires

The Development Requires

by Kevin Saliou

v1.5.12

The Requires

The Development Requires

by Kevin Saliou

v1.5.11

The Requires

The Development Requires

by Kevin Saliou

v1.5.10

The Requires

The Development Requires

by Kevin Saliou

dev-misc

The Requires

The Development Requires

by Kevin Saliou

v1.5.9

The Requires

The Development Requires

by Kevin Saliou

v1.5.8

The Requires

The Development Requires

by Kevin Saliou

v1.5.7

The Requires

The Development Requires

by Kevin Saliou

v1.5.6

The Requires

The Development Requires

by Kevin Saliou

v1.5.5

The Requires

The Development Requires

Basic usage of `php-redmine-api` client

1. Native curl Client `Redmine\Client\NativeCurlClient`

2. Psr-18 compatible Client `Redmine\Client\Psr18Client`