takuya/php-nulab-backlog-api-client

Access to Nulab Backlog Api.

1.0.0 2023-03-01 10:45 UTC

Requires

• php: >=8.0
• ext-gd: *
• ext-json: *
• doctrine/inflector: ^2.0
• guzzlehttp/guzzle: >=7.5
• takuya/php-genetator-array-access: ^1.0

Requires (Dev)

• ext-dom: *
• larapack/dd: ^1.1
• phpunit/phpunit: ^9.5

GPL-3.0-or-later

• takuya

README

目標：NulabのBacklog APIに快適にアクセスして、全データを取り出せるようにする。

バックログのスペースとプロジェクト内部を探索してデータを探すのが面倒なので、データを網羅的に探せるようにしてある。

基本的な使い方。

<?php
use Takuya\BacklogApiClient\BacklogAPIClient;
$key = getenv('backlog_api_key');
$space = getenv('backlog_space');
$cli = new BacklogAPIClient($space, $key);
$cli->getSpace();
$cli->getIssue(['query_options'=>['projectIds'=>[1,2,3],'count'=>100]]);
$cli->getComment("PRJ-234",1)

spaceId はURLを入れます。

$space='http://xxx-your-space.backlog.xxx'

提供するクラス

２つのクラスファイルを提供しています。

• class BacklogAPIClient 更新・取得用
• class Backlog 取得専用

<?php
// Apiで呼び出し
use Takuya\BacklogApiClient\BacklogAPIClient;
$cli = new BacklogAPIClient($space, $key);
$cli->getProject("PRJEKEY");
$cli->getIssue("PRJEKEY-123");
// オブジェクト・モデルでアクセス。
use Takuya\BacklogApiClient\Backlog;
$cli = new Backlog($space, $key);
$cli->project('PRJKEY');
$cli->issue('PRJKEY-123');

class Backlog はID探索のために作っています。更新は実装していません。 class BacklogAPIClient を使って更新をします。

認証

APIキーのアクセスを実装しています。OAUTHアクセスキー（BEARERトークン）は実装していません。

特長

PHPStormのIDE自動補完を使えるようにした。

データモデルをModelクラスとして作成した。これによりスペース→プロジェクト→課題->コメント->通知 のBacklog階層構造を辿れる。

階層構造でたどれば、全体を取得しやすくなる。

サンプル

<?php
use Takuya\BacklogApiClient\Backlog;
$key = getenv('backlog_api_key');
$space = getenv('backlog_space');
$cli = new Backlog($space, $key);
// スペースの取得->プロジェクト一覧->課題一覧
foreach ($cli->space()->projects(Backlog::PROJECTS_ONLY_MINE) as $prj){
  foreach ($prj->issues() as $issue) {
    foreach ($issue->comments() as $comment) {
       print([
        $prj->id,
        $issue->id,
        $comment->id]
    )} 
  }
}

自動補完の例

BacklogのAPIのメソッド名を自動補完します。

$cli = new BacklogAPIClient($space, $key);
$cli->...

サンプル

APIはバックログを開いてアドレスを見ながら使います。

課題コメントを開いたときのアドレスは次のようになっています。

https://example.backlog.com/view/MYPRJ-40#comment-8408

アドレスから次の情報が読み取れます。

{
  "スペースKey":"example",
  "プロジェクトKey": "MYPRJ",
  "課題Key": "40",
  "コメントID": "8408"
}

URL(path)	値	Apiでの引数表記	呼び方
/MYPRJ-40#comment-8408	MYPRJ	ProjectIdOrKey	ProjectKey
/MYPRJ-40#comment-8408	40	IssueIdOrKey	IssueKey
/MYPRJ-40#comment-8408	8409	CommentId	CommentId

APIドキュメントにProjectIdOrKeyと書かれた場合は、 ProjectId Or ProjectKey を意味しています。ProjectKeyとProjectIdとは１対１対応のようです。 上記の情報を使ってAPIにアクセスします。

たとえば、以下のように使います。

<?php
// API呼び出し
use Takuya\BacklogApiClient\BacklogAPIClient;
$space = 'example';
$key = 'YOUR_API_KEY';
$cli = new BacklogAPIClient($space, $key);

## プロジェクト取得 
$cli->getProject("MYPRJ");
## 課題取得 
$cli->getIssue("MYPRJ-40");

基本的に、KeyよりIDアクセスが楽ちんです。

なぜなら、リクエスト引数へIDsを指定で検索するAPIが殆どだからです。たとえばパラメータprojectIds[]やIssueIds[]などです。

このためにID と Key を相互に変換するメソッドを作成してあります。

<?php
use Takuya\BacklogApiClient\Backlog;
$cli = new Backlog($space, $key);
$project_id = $cli->projectIdByKeyName("MYPRJ");

api 一覧

APIの名前とメソッド名と実際のAPIの対応表をapi.htmlに用意しています。

日付と時刻

BacklogのAPIは created / updated で日付が返されます。すべてUTCのようです。

インストール via github

composer config repositories.'php-nulab-backlog-api-client' \
vcs https://github.com/takuya/php-nulab-backlog-api-client  
composer require takuya/php-nulab-backlog-api-client:master
composer install

インストール via packagist with composer

composer require takuya/php-nulab-backlog-api-client

Development

インストールしてテストして開発。

## clone
git clone [e-mail]:takuya/php-nulab-backlog-api-client.git
cd php-nulab-backlog-api-client
composer install
## generate api from backlog WebSite.
composer run-script gen_api_methods
## Test api methods.
export backlog_api_key='YOUR_API_KEY'
export backlog_space='xxxspace'
composer run-script test
## test some test case
php vendor/bin/phpunit --filter get_space

サンプル

更新をするときのサンプル

画像の投稿のサンプル

画像を投稿して、画像を貼り付けたコメントを作る。

$api = new BacklogAPIClient($space, $key);
$part = [
  'name'=>"file",
  'contents' => file_get_contents(__DIR__.'/../../../../sample.jpg'),
  "filename"=>"sample.jpg"
];
$param = ['multipart' => [$part]];
$ret = $api->postAttachmentFile($param);
$params = [
  'content'=>"画像を貼り付ける\nサブスクに気をつけて\n![image][sample.jpg]\n",
  'attachmentId[]'=>$ret->id,
];
$ret = $api->addComment($key,$params);