satun14/redmine-api

Redmine API client

v2.0 2020-12-29 06:44 UTC

Requires

• php: ^5.4 || ^7.2
• ext-curl: *
• ext-json: *
• ext-simplexml: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^2.0
• phpunit/phpunit: ^4.8.36 || ^5.4.8 || ^6.0

MIT

• Alexandr Tuncov

• api
• redmine

README

A simple PHP Object Oriented wrapper for Redmine API.

Uses Redmine API.

Features

• Follows PSR-0 conventions and coding standard: autoload friendly
• API entry points implementation state :
• OK Attachments
• OK Groups
• OK Custom Fields
• OK Issues
• OK Issue Categories
• OK Issue Priorities
• NOK Issue Relations - only partially implemented
• OK Issue Statuses
• OK News
• OK Projects
• OK Project Memberships
• OK Queries
• OK Roles
• OK Time Entries
• OK Time Entry Activities
• OK Trackers
• OK Users
• OK Versions
• OK Wiki

Limitations

Redmine is missing some APIs for a full remote management of the data :

• List of activities & roles : http://www.redmine.org/issues/11464
• ...

A possible solution to this would be to create an extra APIs implementing the missing entry points. See existing effort in doing so : https://github.com/rschobbert/redmine-miss-api

Requirements

• PHP >= 5.4
• The PHP cURL extension
• The PHP SimpleXML extension
• The PHP JSON extension
• PHPUnit >= 4.0 (optional) to run the test suite
• "Enable REST web service" for your Redmine project (/settings/edit?tab=authentication)
• then obtain your API access key in your profile page : /my/account
• or use your username & password

Install

Composer

Composer users can simply run:

$ composer require satun14/redmine-api

at the root of their 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('http://redmine.example.com', 'username', 'password');

Manual

It is also possible to install the library oneself, either locally to a project or globally; say, in /usr/share/php.

First, download and extract the library somewhere. For example, the following steps extract v1.5.18 of the library into the vendor/php-redmine-api-1.5.18 directory:

$ mkdir vendor
$ wget -q https://github.com/kbsali/php-redmine-api/archive/v1.5.18.tar.gz
$ tar -xf v1.5.18.tar.gz -C vendor/
$ rm v1.5.18.tar.gz

Now, in any scripts that will use the Redmine classes, include the src/autoload.php file from the php-redmine-api directory. For example,

<?php
// This file ships with php-redmine-api
require 'vendor/php-redmine-api-1.5.18/src/autoload.php';
$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');

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 6.5.14 by Sebastian Bergmann and contributors.

Error:         No code coverage driver is available

...............................................................  63 / 285 ( 22%)
............................................................... 126 / 285 ( 44%)
............................................................... 189 / 285 ( 66%)
............................................................... 252 / 285 ( 88%)
.................................                               285 / 285 (100%)

Time: 107 ms, Memory: 8.00MB

OK (285 tests, 662 assertions)

Basic usage of php-redmine-api client

<?php

// For Composer users (this file is generated by Composer)
require_once 'vendor/autoload.php';

// Or if you've installed the library manually, use this instead.
// require 'vendor/php-redmine-api-x.y.z/src/autoload.php';

$client = new Redmine\Client('http://redmine.example.com', 'API_ACCESS_KEY');
//-- OR --
$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');

$client->user->all();
$client->user->listing();

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

// OR

$client->issue->create([
    'ticket' => [
        'issue' => [
            'project_id' => 'test',
            'tracker_id' => '1',
            'status_id' => '1',
            'subject' => 'subject',
            'description' => 'description',
        ],
        'contact' => [
            'email' => '[e-mail]',
            'first_name' => 'first name'
        ]
    ]
], '/helpdesk/create_ticket.xml');

$client->issue->all([
    'limit' => 1000
]);

See example.php for further examples.

User Impersonation

As of Redmine V2.2 you can impersonate user through the REST API :

$client = new Redmine\Client('http://redmine.example.com', 'API_ACCESS_KEY');

// impersonate user
$client->setImpersonateUser('jsmith');

// create a time entry for jsmith
$client->time_entry->create($data);

// remove impersonation for further calls
$client->setImpersonateUser(null);

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! :)