- Notifications
You must be signed in to change notification settings - Fork183
A simple PHP Redmine API client, Object Oriented
License
kbsali/php-redmine-api
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
A simple PHP Object Oriented wrapper for Redmine API.
UsesRedmine API.
- Follows PSR-4 conventions and coding standard: autoload friendly
- Choose between using native
cURLfunction or anyPSR-18 HTTP client implementationlikeGuzzle 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"}}', ),);
We support (and run tests against) thelatest supported Redmine versionsthat receive security updates.
- Redmine 6.0.x
- Redmine 5.1.x
- Redmine 5.0.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 tocreate an issue.
- PHP ^7.4 || ^8.0
- The PHPSimpleXML extension
- The PHPJSON 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 yourAPI access key in your profile page:
/my/account - (or use yourusername & password; not recommended)
- Go to Administration -> Settings -> Api (
- The PHPcURL extension if you want to use the native
cURLfunctions. - PHPUnit >= 9.0 (optional) to run the test suite
- Tracking of Redmine API feature support in#305
- Check header's response code (especially for POST/PUT/DELETE requests)
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
By usingComposer you can simply run:
$ php composer.phar require kbsali/redmine-api
at the root of your projects. To utilize the library, includeComposer'svendor/autoload.php in the scripts that will use theRedmine classes.
For example,
<?php// This file is generated by Composerrequire_once'vendor/autoload.php';$client =new \Redmine\Client\NativeCurlClient('https://redmine.example.com','0ef19567656532f8dd43a4dbfeda787f01f3e659');
For a manual installation please follow thisinstruction.
You can run test suite to make sure the library will work properly on your system. Simply runvendor/bin/phpunit in the project's directory :
$ vendor/bin/phpunitPHPUnit 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 MBOK (432 tests, 1098 assertions)Create your project e.g. in theindex.php by require thevendor/autoload.php file.
+<?php++require_once 'vendor/autoload.php';
You can choose between:
- a native curl client or
- the PSR-18 compatible client.
💡 This client was introduced in
php-redmine-apiv1.8.0. If you areusing the oldRedmine\Clientpleasesee this migration guide for help toupgrade your code.
You will need a URL to your Redmine instance and either a valid Apikey...
<?phprequire_once 'vendor/autoload.php';++// Instantiate with ApiKey+$client = new \Redmine\Client\NativeCurlClient('https://redmine.example.com', '1234567890abcdfgh');
... or valid username/password.
<?phprequire_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.
After you instantiate a client you can set some optionalcURL settings.
<?phprequire_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']);💡 This client was introduced in
v1.7.0of this library. If you are using the oldRedmine\Clientpleasefollow this migration guide.
ThePsr18Client requires
- a
Psr\Http\Client\ClientInterfaceimplementation (like guzzlehttp/guzzle),see - a
Psr\Http\Message\RequestFactoryInterfaceimplementation (like guzzlehttp/psr7),see - a
Psr\Http\Message\StreamFactoryInterfaceimplementation (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.
<?phprequire_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'+);
Because thePsr18Client is agnostic about the HTTP client implementation every configuration specific to the transport has to be set to thePsr\Http\Client\ClientInterface implementation.
This means that if you want to set anycURL settings toGuzzle you have multiple ways to set them:
- UsingGuzzle environment variables
- Usingrequest options inside a
Psr\Http\Client\ClientInterfacewrapper:
<?phprequire_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 allows youto impersonate another user. This can be done using the methodsstartImpersonateUser() andstopImpersonateUser().
$client->startImpersonateUser('kim');// all requests will now impersonate the user `kim`// To stop impersonation$client->stopImpersonateUser();
You can now use thegetApi() 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 toThomas Spycher for the 1st version of the class.
- Thanks toThibault Duplessis aka. ornicar for the php-github-api library, great source of inspiration!
- And all thecontributors
- speciallyJanMalte for his impressive contribution to the test coverage! :)
About
A simple PHP Redmine API client, Object Oriented