Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/takuya/php-nulab-backlog-api-client
ヌーラボ・バックログのAPI用ライブラリ / nulab backlog api library for php
https://github.com/takuya/php-nulab-backlog-api-client
backlog-api php
Last synced: 21 days ago
JSON representation
ヌーラボ・バックログのAPI用ライブラリ / nulab backlog api library for php
- Host: GitHub
- URL: https://github.com/takuya/php-nulab-backlog-api-client
- Owner: takuya
- License: gpl-3.0
- Created: 2023-01-30T14:58:25.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2023-03-09T05:24:22.000Z (over 1 year ago)
- Last Synced: 2024-10-13T18:53:20.099Z (about 1 month ago)
- Topics: backlog-api, php
- Language: PHP
- Homepage:
- Size: 222 KB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Nulab Backlog APIアクセス用
目標：NulabのBacklog APIに快適にアクセスして、全データを取り出せるようにする。
バックログのスペースとプロジェクト内部を探索してデータを探すのが面倒なので、データを網羅的に探せるようにしてある。
## 基本的な使い方。
```php
getSpace();
$cli->getIssue(['query_options'=>['projectIds'=>[1,2,3],'count'=>100]]);
$cli->getComment("PRJ-234",1)
```
spaceId はURLを入れます。
```php
$space='http://xxx-your-space.backlog.xxx'
```
## 提供するクラス
２つのクラスファイルを提供しています。
- `class BacklogAPIClient` 更新・取得用
- `class Backlog` 取得専用
```php
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
プロジェクト一覧->課題一覧
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
```
アドレスから次の情報が読み取れます。
```json
{
"スペース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
getProject("MYPRJ");
## 課題取得
$cli->getIssue("MYPRJ-40");
```
基本的に、`Key`より`ID`アクセスが楽ちんです。
なぜなら、リクエスト引数へIDsを指定で検索するAPIが殆どだからです。たとえばパラメータ`projectIds[]`や`IssueIds[]`などです。
このためにID と Key を相互に変換するメソッドを作成してあります。
```php
projectIdByKeyName("MYPRJ");
```
## api 一覧
APIの名前とメソッド名と実際のAPIの対応表を`api.html`に用意しています。
## 日付と時刻
BacklogのAPIは `created` / `updated` で日付が返されます。すべてUTCのようです。
## インストール via github
```sh
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
```sh
composer require takuya/php-nulab-backlog-api-client
```
## Development
インストールしてテストして開発。
```sh
## clone
git clone [email protected]: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
```
## サンプル
更新をするときのサンプル
### 画像の投稿のサンプル
画像を投稿して、画像を貼り付けたコメントを作る。
```php
$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);
```