kbsali / redmine-api
Redmine API client
Installs: 921 808
Dependents: 26
Suggesters: 0
Security: 0
Stars: 420
Watchers: 38
Forks: 183
Open Issues: 23
Requires
- php: ^7.4 || ^8.0
- ext-curl: *
- ext-json: *
- ext-simplexml: *
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
Requires (Dev)
- behat/behat: ^3.14
- friendsofphp/php-cs-fixer: ^3.45
- guzzlehttp/psr7: ^2
- php-mock/php-mock-phpunit: ^2.6
- phpstan/phpstan: ^1.10
- phpunit/phpunit: ^9.5 || ^10.5
- v2.x-dev
- v2.7.0
- v2.6.0
- v2.5.0
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.1
- v2.1.0
- v2.0.1
- v2.0.0
- v1.x-dev
- v1.8.1
- v1.8.0
- v1.7.0
- v1.6.0
- v1.5.22
- v1.5.21
- v1.5.20
- v1.5.19
- v1.5.18
- v1.5.16
- v1.5.15
- v1.5.14
- v1.5.13
- v1.5.12
- v1.5.11
- v1.5.10
- v1.5.9
- v1.5.8
- v1.5.7
- v1.5.6
- v1.5.5
- v1.5.4
- v1.5.3
- v1.5.2
- v1.5.1
- v1.5.0
- v1.4
- v1.3
- v1.2.1
- v1.2
- v1.1.3
- v1.1.2
- v1.1.1
- v1.1.0
- v1.0.10
- 1.0.9
- 1.0.8
- 1.0.7
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.2
- 1.0.0
- 0.4.11
- 0.4.10
- 0.4.9
- 0.4.8
- 0.4.7
- 0.4.6
- 0.4.5
- 0.4.4
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4.0
- 0.3.0
- 0.2.2
- 0.2.1
- 0.2
- 0.1
- dev-renovate/all
This package is auto-updated.
Last update: 2024-11-05 04:36:11 UTC
README
A simple PHP Object Oriented wrapper for Redmine API.
Uses Redmine API.
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.
$client->getApi('issue')->create(['project_id' => 1, 'subject' => 'issue title']); $response = $client->getApi('issue')->getLastResponse();
- low-level API e.g.
$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.
- 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.
If a new Redmine version enables new features that are not yet supported with this library, you are welcome to create an issue.
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)
- Go to Administration -> Settings -> Api (
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)
Limitations / Missing Redmine-API
Redmine is missing some APIs for a full remote management of the data:
- 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:
$ 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.
For example,
<?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.
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 :
$ 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.
+<?php + +require_once 'vendor/autoload.php';
Instantiate a Redmine Client
You can choose between:
- a native curl client or
- the PSR-18 compatible client.
1. Native curl Client Redmine\Client\NativeCurlClient
💡 This client was introduced in
php-redmine-api
v1.8.0. If you are using the oldRedmine\Client
please see this migration guide for help to upgrade your code.
You will need a URL to your Redmine instance and either a valid Apikey...
<?php require_once 'vendor/autoload.php'; + +// Instantiate with ApiKey +$client = new \Redmine\Client\NativeCurlClient('https://redmine.example.com', '1234567890abcdfgh');
... or valid username/password.
<?php require_once 'vendor/autoload.php'; + +// Instantiate with Username/Password (not recommended) +$client = new \Redmine\Client\NativeCurlClient('https://redmine.example.com', 'username', 'password');
💡 For security reason it is recommended that you use an ApiKey rather than your username/password.
cURL configuration
After you instantiate a client you can set some optional cURL
settings.
<?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
💡 This client was introduced in
v1.7.0
of this library. If you are using the oldRedmine\Client
please follow this migration guide.
The Psr18Client
requires
- 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.
💡 For security reason it is recommended that you use an ApiKey rather than your username/password.
<?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.
This means that if you want to set any cURL
settings to Guzzle
you have multiple ways to set them:
- 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()
.
$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.
<?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.
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! :)