dmm-api-client-php

DMM Web サービス API（v3）の PHP クライアントライブラリ。

レスポンスは Valinor で検証してから型付きの DTO として返す。 API の仕様と食い違うレスポンスは、null になって埋もれるのではなく、JSON パス付きの例外になる。

状態: 開発中。v1.0.0 までは予告なく API が変わる可能性がある。

動作要件

• PHP 8.3 以降
• PSR-18 HTTP クライアントと PSR-17 ファクトリの実装（インストール済みのものを自動検出する）

インストール

composer require yasukei/dmm-api-client-php

PSR-18 クライアントをまだ入れていない場合は、あわせてインストールする。

composer require guzzlehttp/guzzle
# または
composer require symfony/http-client nyholm/psr7

使い方

use DmmApiClient\Api\DmmApiClient;
use DmmApiClient\Api\Request\Credentials;
use DmmApiClient\Api\Request\ItemListRequest;
use DmmApiClient\Api\Request\ItemListSort;

$client = new DmmApiClient(new Credentials('your_api_id', 'your_affiliate_id'));

$response = $client->itemList(new ItemListRequest(
    site: 'DMM.com',
    service: 'mono',
    floor: 'book',
    keyword: 'PHP',
    sort: ItemListSort::Date,
    hits: 20,
));

echo $response->result->totalCount, " 件\n";

foreach ($response->result->items as $item) {
    echo $item->contentId, ' ', $item->title, ' ', $item->prices?->price, "\n";
}

var_dump($response->json()); // API が返した JSON をそのまま（DTO が知らない項目も含む）

リクエストの型は src/Api/Request、レスポンスの型は src/Api/Response 配下にある。 各パラメータ・項目の意味は、それぞれのクラスの docblock を参照。

DMM API を使ったサイトやアプリケーションには クレジット表示 が必要。

対応 API

API	メソッド	リクエスト
/ItemList	itemList()	ItemListRequest
/FloorList	floorList()	FloorListRequest（省略可）
/ActressSearch	actressSearch()	ActressSearchRequest
/GenreSearch	genreSearch()	GenreSearchRequest
/MakerSearch	makerSearch()	MakerSearchRequest
/SeriesSearch	seriesSearch()	SeriesSearchRequest
/AuthorSearch	authorSearch()	AuthorSearchRequest

エラー処理

ライブラリが投げる例外は、すべて DmmApiClient\Api\Exception\DmmApiClientException を実装している。

例外	発生する場面
InvalidArgumentException	リクエストを不正な値で組み立てた
TransportException	HTTP 通信に失敗した（DNS 失敗、タイムアウトなど）
ApiErrorException	API がエラーを返した（$error にエラー内容が入る）
MalformedResponseException	レスポンスが JSON として読めなかった
ResponseValidationException	レスポンスが期待する構造と一致しなかった（$errors に JSON パスと理由が入る）

コマンド

レスポンスを確認するための dmm-api-client コマンドを同梱している。 認証情報は環境変数 DMM_API_ID / DMM_AFFILIATE_ID、またはカレントディレクトリの .env から読む。

vendor/bin/dmm-api-client --help
vendor/bin/dmm-api-client item-list --site=DMM.com --keyword=PHP | jq .

# このリポジトリを直接 clone して使う場合は ./bin/dmm-api-client

出力に含まれる認証情報は、既定で *** に伏せ字にする。

開発

変更履歴は CHANGELOG.md にまとめている。

コマンド	用途
composer test	単体テスト（Pest）
composer coverage	コードカバレッジ付きの単体テスト（PCOV か Xdebug が必要）。CI では全体のカバレッジに下限を設けている
composer mutate	ミューテーションテスト。CLI（src/Console）は対象外（PCOV か Xdebug が必要）。CI ではスコアに下限を設けている
composer lint	stan + cs-check + rector-dry + deps
composer fix	rector + cs-fix
composer stan	静的解析（PHPStan）
composer cs-check / composer cs-fix	コードスタイル（PHP-CS-Fixer）
composer rector-dry / composer rector	自動リファクタリング（Rector）
composer deps	依存の過不足の検査（composer-dependency-analyser）
composer probe	実際の API から取得したデータで DTO を検証する。詳細は tools/live-probe

ライセンス

MIT