/php-redmine-api

A simple PHP Redmine API client, Object Oriented

Primary LanguagePHPMIT LicenseMIT

PHP Redmine API

A simple Object Oriented wrapper for Redmine API, written with PHP5.

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

Todo

Limitations

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

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:

$ php composer.phar require kbsali/redmine-api:~1.0

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.1 of the library into the vendor/php-redmine-api-1.5.1 directory:

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

Now, in any scripts that will use the Redmine classes, include the lib/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.1/lib/autoload.php';
$client = new Redmine\Client('http://redmine.example.com', 'username', 'password');

Running the test suite

If you have PHPUnit >= 4.0 installed, you can run the test suite to make sure that the library will function properly on your system. Simply run phpunit in the php-redmine-api directory. For example,

$ phpunit
PHPUnit 4.3.1 by Sebastian Bergmann.

Configuration read from ./phpunit.xml.dist

...............................................................  63 / 276 ( 22%)
............................................................... 126 / 276 ( 45%)
............................................................... 189 / 276 ( 68%)
............................................................... 252 / 276 ( 91%)
........................

Time: 591 ms, Memory: 10.50Mb

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/lib/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->api('user')->all();
$client->api('user')->listing();

$client->api('issue')->create([
    'project_id'  => 'test',
    'subject'     => 'some subject',
    'description' => 'a long description blablabla',
    'assigned_to' => 'user1',
]);
$client->api('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->api('time_entry')->create($data);

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

Thanks!