Download the PHP package trust-medical/laravel-chatwork-api without Composer

laravel-chatwork-api

Chatwork API v2 を Laravel から安全に利用するための Composer パッケージです。Facade / DI / Laravel Notification の3経路を公式サポートします。

• PHP ^8.3
• Laravel ^11.0 || ^12.0 || ^13.0
• Chatwork API v2（Base URI: https://api.chatwork.com/v2）

特長

• すべてのエンドポイント（rooms / messages / members / tasks / files / links / contacts / me / my / incoming_requests）をカバー
• API Token と OAuth2 Bearer Token の両認証に対応（排他は型で構造的に保証）
• 戻り値モードを呼び出し側でチェーン切り替え（DTO / 配列 / Collection / Response / Result）
• readonly Response DTO と immutable Request オブジェクトによる型安全な API
• Laravel Notification channel（ChatworkChannel）を同梱
• OAuth2 認可フロー（認可URL生成・callback・refresh token、Cache::lock による多重 refresh 防止）

インストール

ServiceProvider と Facade は Laravel のパッケージ自動検出で登録されるため、手動登録は不要です。

設定ファイルを publish します:

.env に最低限の認証情報を設定します:

設定

config/chatwork.php の主なキー:

複数 connection の例:

基本的な使い方

connection の切り替え

connection() / withApiToken() / withBearerToken() / as*() は新しい manager を返すイミュータブル設計のため、安全にチェーンできます。ChatworkManager はコンテナ singleton ですが、これらは共有インスタンスを mutate せず clone を返すため、Laravel Octane / Swoole / キューワーカー等の常駐プロセスでもリクエスト間で connection・認証情報・戻り値モードが漏れません。

戻り値モード

既定は asDto()。呼び出し側でチェーンして変更できます。

送信前バリデーション失敗は戻り値モードに関わらず常に ChatworkValidationException を throw します。

メソッド別の戻り値型（asDto() 契約）

各 Resource メソッドのネイティブ署名は : mixed です（戻り値型は ResponseMode により実行時に変わるため）。下表は 既定の asDto() モード での戻り値型です。 asArray() / asCollection() / asResponse() / asPsrResponse() / asResult() へ切り替えた場合は宣言型・下表の型と実行時型が乖離し、その型解釈は呼び出し側の 責務になります（設計判断の詳細は docs/03-package-architecture/response-strategy.md）。

list<…> 系で Chatwork が 204 を返す場合、asDto() では [] に縮退します （contacts()->list() / my()->tasks() / incomingRequests()->list()）。

リソース別の例

Rooms

Messages

Members

Tasks

Files

Invitation Links

Me / My / Contacts / Incoming Requests

エラーハンドリング

例外

すべての例外は marker interface ChatworkException を実装します。本パッケージ由来の例外を一括捕捉したい場合は catch (ChatworkException $e) が使えます（status() / violations() などの固有メソッドは具象例外型で分岐してください）。

ChatworkRequestException はエラーボディ2系統を取り出せます:

asResult()（例外を投げない）

Notification チャンネル

Notification から Chatwork へ送信できます。チャンネルは内部的に asResult() 固定で、4xx は permanent failure として例外化、5xx / 429 / ネットワークエラーはそのまま伝播してキュー再試行に委譲されます。

ChatworkMessage はメッセージ組み立て専用のビルダー / DTO です（Notification ではありません）。ChatworkNotification を継承すると via() は自動で ChatworkChannel に接続されるため、toChatwork() を実装するだけで送信できます。

ChatworkNotification を使わず通常の Notification で via() に [ChatworkChannel::class] を返し、toChatwork($notifiable): ChatworkMessage を実装しても構いません（queueable・複数チャンネル併用などはこちら）。

メッセージビルダーは body() / title() / code() / hr() / plain() / escape() / to()（TO 付与）/ toRoom() / selfUnread() を提供します。

送信先は ChatworkMessage::toRoom() のほか、notifiable 側の routeNotificationForChatwork() でも指定できます（両方指定は競合エラー）:

OAuth2

config/chatwork.php の oauth セクションで設定します。

Confidential / Public Client の自動判定: Chatwork は OAuth クライアント 種別ごとにトークンエンドポイントの認証方式が異なります。Confidential Client (client_secret あり) は Authorization: Basic Base64(client_id:client_secret) ヘッダーが必須、Public Client (client_secret なし) は body に client_id のみを 含めて Basic 認証ヘッダーを送りません。本ライブラリは CHATWORK_OAUTH_CLIENT_SECRET の有無 (空文字含む) で自動判定します。Confidential / Public を切り替える追加 設定キーはありません。

callback ルートは既定で無効です（セキュリティのため）。利用する場合は config/chatwork.php で有効化します:

有効化すると GET {route_prefix}/callback（ルート名 chatwork.oauth.callback）が登録されます。callback では state 検証が必須で、token は設定した TokenRepository に保存されます。取得済みトークンは Chatwork::connection('oauth-connection') 経由で利用でき、期限切れ時は Cache::lock で多重発行を防ぎつつ自動 refresh されます。

本番環境の推奨: 既定の StateStore / TokenRepository は Cache ストアを使います。state の一度きりの消費（リプレイ攻撃防止）には read-and-delete のアトミック性が必要なため、本番では redis または database キャッシュドライバを使用してください。array / file ドライバは read→delete が非アトミックで、同一 state の二重消費が理論上成立し得ます。永続トークンには独自の TokenRepository（例: DB 実装）を設定することを推奨します。

トークンの暗号化: 既定の CacheTokenRepository は access/refresh トークンを Laravel の Encrypter（APP_KEY）で暗号化してからキャッシュへ保存します。Redis / Memcached を直接参照されてもトークンは平文露出しません。APP_KEY 未設定だと MissingAppKeyException になります（通常の Laravel アプリでは設定済み）。APP_KEY をローテーションした場合、暗号化済みの既存トークンは復号できず「未保存」とみなされ、利用者は再認証が必要になります。独自の TokenRepository を使う場合は暗号化も自実装の責務です。

callback ルートの throttle

config/chatwork.php の oauth.route_throttle（既定 '10,1' = 1分あたり10回）が callback ルートに throttle ミドルウェアとして適用され、state / code のブルートフォースを抑制します。"max,decayMinutes" 形式の文字列、または名前付き rate limiter 名を指定できます。null / 空文字で throttle を無効化します。形式不正値は ServiceProvider 起動時に ChatworkConfigurationException になります。

独自 RouteServiceProvider からの手動登録

routes_enabled を false のままにしつつ、任意の middleware / ドメイン / プレフィックス配下で callback ルートを登録したい場合は、ChatworkServiceProvider::registerOAuthRoutes() を独自の RouteServiceProvider から呼び出せます（意図的に public）。

route:cache 利用時の注意: OAuth callback ルートは packageBooted() 内のクロージャで登録されます。php artisan route:cache が有効な環境ではこのクロージャが実行されず、callback ルートが登録されず、また route_throttle の形式検証も行われません。registerOAuthRoutes() を独自 RouteServiceProvider から手動呼び出しする場合も route:cache 下では同様にスキップされます。route:cache を使う環境で OAuth callback を利用する場合は、ルートをアプリ側の実 routes ファイルに明示登録し、route_throttle の指定が実際に効いているか（php artisan route:list 等で）確認してください。

動的 (per-tenant) OAuth コネクション

Laravel のユーザーごとに別の OAuth access_token を持つ SaaS / マルチテナント環境では、Chatwork::forOAuthKey($key) を使うと TokenRepository の検索キーをランタイムに指定して OAuth コネクションを組み立てられます。

固定 OAuth connection（config/chatwork.php で auth: 'oauth' を宣言する方式）との違い:

$base を明示すると、その connection の base_uri / timeout を継承しつつ TokenRepository のキーには $key を使います（$base は auth 値を問わず baseUri / timeout のメタデータ源としてのみ参照されます）。$base 指定が config に存在しない場合は ChatworkAuthenticationException を投げます。

$key の選び方: $key は TokenRepository::find() / save() および Cache::lock のキー（chatwork:oauth:refresh:<sha256($key)>）として使われます。メールアドレス等の PII を直接渡さず、DB の User PK 等の安定 ID を使ってください。Connection::$name は "oauth:{$key}" 形式となり、例外メッセージ・ログに現れます。

manager を長期保持しない: forOAuthKey() は呼び出し時点で BearerTokenCredentials を確定して Connection に焼き込みます（connection() と同じ resolve-at-bind セマンティクス）。access_token の expire 後に再利用できないため、Queue worker / Octane でもリクエスト直前に都度呼び出してください。

テスト

すべてのテストは Http::fake() で実 API を叩かずに検証しています。

セキュリティ

• API token / client secret / refresh token をログ・例外メッセージに含めません
• OAuth2 callback は state 検証を必須とし、ルートは既定で無効です
• API Token（x-chatworktoken）と OAuth2 Bearer（Authorization: Bearer）は1リクエストで同時送信されません（Credentials 実装で構造的に保証）
• OAuth2 state のリプレイ防止には read-and-delete のアトミック性が必要なため、本番では redis / database キャッシュドライバを推奨します（array / file は非アトミック）

脆弱性を発見した場合は公開 issue ではなく非公開でご連絡ください。

ライセンス

MIT License