Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/kbsali/php-redmine-api
A simple PHP Redmine API client, Object Oriented
https://github.com/kbsali/php-redmine-api
api-client composer-package looking-for-maintainer maintainer-wanted php redmine
Last synced: 3 months ago
JSON representation
A simple PHP Redmine API client, Object Oriented
- Host: GitHub
- URL: https://github.com/kbsali/php-redmine-api
- Owner: kbsali
- License: mit
- Created: 2012-09-28T15:23:10.000Z (over 12 years ago)
- Default Branch: v2.x
- Last Pushed: 2024-04-09T08:18:07.000Z (10 months ago)
- Last Synced: 2024-04-17T09:24:35.753Z (10 months ago)
- Topics: api-client, composer-package, looking-for-maintainer, maintainer-wanted, php, redmine
- Language: PHP
- Homepage:
- Size: 1.44 MB
- Stars: 419
- Watchers: 38
- Forks: 220
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-redmine - php-redmine-api - A simple PHP Redmine API client, Object Oriented. (API wrapper / Commercial Themes)
README
# PHP Redmine API
[](https://github.com/kbsali/php-redmine-api/releases)
[](LICENSE)
[](https://github.com/kbsali/php-redmine-api/actions)
[](https://codecov.io/gh/kbsali/php-redmine-api)
[](https://packagist.org/packages/kbsali/redmine-api)
A simple PHP Object Oriented wrapper for Redmine API.
Uses [Redmine API](https://www.redmine.org/projects/redmine/wiki/Rest_api/).
## Features
* Follows PSR-4 conventions and coding standard: autoload friendly
* Choose between using native `cURL` function or any
[PSR-18 HTTP client implementation ](https://packagist.org/providers/psr/http-client-implementation)
like [Guzzle](https://github.com/guzzle/guzzle) for handling http connections
* [mid-level API](docs/usage.md#mid-level-api) e.g.
```php
$client->getApi('issue')->create(['project_id' => 1, 'subject' => 'issue title']);
```
* [low-level API](docs/usage.md#low-level-api) e.g.
```php
$client->requestPost('/issues.json', '{"issue":{"project_id":1,"subject":"issue title"}}');
```
## Supported Redmine versions
We support (and run tests against) the [latest supported Redmine versions](https://www.redmine.org/projects/redmine/wiki/Download#Versions-status-and-releases-policy)
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](https://github.com/kbsali/php-redmine-api/issues).
## Requirements
* PHP ^7.4 || ^8.0
* The PHP [SimpleXML](https://php.net/manual/en/book.simplexml.php) extension
* The PHP [JSON](https://php.net/manual/en/book.json.php) 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](https://php.net/manual/en/book.curl.php) extension if you want to use the native `cURL` functions.
* [PHPUnit](https://phpunit.de/) >= 9.0 (optional) to run the test suite
## Todo
* Tracking of Redmine API feature support in [#305](https://github.com/kbsali/php-redmine-api/issues/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:
* List of activities & roles: https://www.redmine.org/issues/11464
* [Open issues because of missing Redmine API](https://github.com/kbsali/php-redmine-api/labels/pending%3A%20missing%20api)
## Install
By using [Composer](https://getcomposer.org/) you can simply run:
```bash
$ 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
: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](docs/migrate-to-nativecurlclient.md).
You will need a URL to your Redmine instance and either a valid Apikey...
```diff
:bulb: 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.
```diff
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](docs/migrate-to-psr18client.md).
The `Psr18Client` requires
- a `Psr\Http\Client\ClientInterface` implementation (like guzzlehttp/guzzle), [see](https://packagist.org/providers/psr/http-client-implementation)
- a `Psr\Http\Message\RequestFactoryInterface` implementation (like guzzlehttp/psr7), [see](https://packagist.org/providers/psr/http-factory-implementation)
- a `Psr\Http\Message\StreamFactoryInterface` implementation (like guzzlehttp/psr7), [see](https://packagist.org/providers/psr/http-message-implementation)
- 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.
```diff
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](https://www.redmine.org/projects/redmine/wiki/Rest_api#User-Impersonation). This can be done using the methods `startImpersonateUser()` and `stopImpersonateUser()`.
```php
$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
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](docs/usage.md).
### Thanks!
* Thanks to [Thomas Spycher](https://github.com/tspycher/) for the 1st version of the class.
* Thanks to [Thibault Duplessis aka. ornicar](https://github.com/ornicar) for the php-github-api library, great source of inspiration!
* And all the [contributors](https://github.com/kbsali/php-redmine-api/graphs/contributors)
* specially [JanMalte](https://github.com/JanMalte) for his impressive contribution to the test coverage! :)