---
title: "sdk/php"
description: "ネットワークレス JWT 検証、PSR-7 リクエスト認証、webhook 署名検証用の PHP 8.1+ サーバー SDK。"
locale: "ja"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ja/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# sdk/php

## 状態

ローカルで実装および検証済み。実際の IdP ラウンドトリップ検証（JWKS 取得、実稼働 Vonvon インスタンスに対するトークン署名/検証）はまだ実行されておらず、本番利用前に完了する必要があります。

Registry 状態: UNPUBLISHED。この SDK はリポジトリのソース checkout からのみインストールし、外部 package registry は使用しないでください。

リクエスト認証はデフォルトで Bearer のみを受け付けます。アプリケーション所有の JWT cookie は、その正確な名前を設定した場合にのみ読み取られます。不透明な \_\_Host-vonvon.rt.\* Core cookie はスキャンもローカル検証も行いません。完全な Cookie header を exact same-origin の POST /v1/sessions/token に redirect 無効で転送して交換し、token フィールドだけを含むレスポンスのみ受け入れてください。

## インストール

PHP 8.1+ が必要です。コア依存関係は Composer が自動的に取得します。

```shell
{
  "repositories": [
{ "type": "path", "url": "../vonvon/sdk/php" }
  ],
  "require": {
"vonvon/vonvon": "dev-main"
  }
}

# composer update vonvon/vonvon
```

## クイックスタート

```php
use Vonvon\VonvonClient;
use Vonvon\Exception\TokenException;
use Vonvon\Exception\JwksException;

$vonvon = new VonvonClient([
'issuer'   => 'https://vonvon.id',
'audience' => 'your-client-id',
'cache'    => $psrSimpleCacheImpl, // PSR-16; null disables JWKS cache
]);

try {
$claims = $vonvon->verifyToken($jwtString);
echo $claims->sub();    // user ID
echo $claims->scope();  // "openid profile email"
echo implode(',', $claims->amr()); // "phr" / "otp"
} catch (TokenException $e) {
http_response_code(401);
} catch (JwksException $e) {
http_response_code(503);
}
```

## PSR-7 リクエストを認証します

```php
$result = $vonvon->authenticateRequest($psrRequest);

if ($result->isAuthenticated()) {
$userId = $result->claims()->sub();
} else {
// $result->reason() for server-side logs only
http_response_code(401);
}

$token = $vonvon->exchangeSessionToken(
'https://app.example.com/account',
$psrRequest->getHeaderLine('Cookie'),
$sessionTokenTransport,
);
```

## webhook を検証

```php
use Vonvon\Exception\WebhookException;

try {
$payload = $vonvon->verifyWebhook($psrRequest, 'whsec_...');
$type = $payload->type();  // "user.created"
$data = $payload->data();
} catch (WebhookException $e) {
http_response_code(400);
}
```

## VonvonClient オプション

| キー | デフォルト | 説明 |
| --- | --- | --- |
| `issuer` | 必須 | Vonvon 発行者 URI |
| `audience` | `null` | expected audience。null は検証をスキップします |
| `cache` | `null` | JWKS キャッシュ用の PSR-16 CacheInterface |
| `jwks_ttl` | `3600` | JWKS キャッシュ TTL（秒） |
| `clock_leeway` | `0` | JWT クロックスキュー許容値（秒） |
| `cookie_name` | `disabled` | アプリケーション所有の JWT cookie 名。明示的に設定した場合のみ有効 |

## VonvonClient メソッド

| 方式 | 戻り値 | 説明 |
| --- | --- | --- |
| `verifyToken(string $token)` | `Claims` | JWT 文字列を検証します。失敗時にスローします |
| `authenticateRequest(ServerRequestInterface $request)` | `AuthResult` | PSR-7 リクエストを認証します。スローしません |
| `verifyWebhook(ServerRequestInterface $request, string $secret)` | `WebhookPayload` | webhook 署名を検証します。失敗時にスローします |
| `refreshJwks()` | `void` | JWKS キャッシュを強制更新します |

## プラットフォームの注意事項

- ES256/RS256 検証に `firebase/php-jwt` を使用します。HS256 と `none` アルゴリズムは拒否されます。
- `authenticateRequest` と `verifyWebhook` には PSR-7 リクエストオブジェクトが必要です。必要に応じて PSR-7 ブリッジでフレームワークネイティブリクエストを変換してください。
- 例外階層：`VonvonException` -> `TokenException`、`JwksException`、`WebhookException`。

Source: https://vonvon.id/ja/sdks/php/index.mdx