---
title: "sdk/php"
description: "PHP 8.1+ 服务端 SDK，提供 networkless JWT 验证、PSR-7 请求认证和 webhook 签名校验。"
locale: "zh-Hans"
---

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

# sdk/php

## 状态

已在本地实现并验证。针对真实 Vonvon 实例的 IdP 往返验证（JWKS 获取、token 签名/验证）尚未执行，生产使用前必须完成。

Registry 状态:UNPUBLISHED。此 SDK 只能从仓库源码 checkout 安装；不要使用外部 package registry。

请求认证默认仅接受 Bearer。只有配置精确名称时才读取应用自有 JWT cookie。SDK 绝不扫描或本地验证 opaque \_\_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` | 期望的受众；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 缓存 |

## 平台注意事项

- 使用 `firebase/php-jwt` 进行 ES256/RS256 验证。HS256 和 `none` 算法会被拒绝。
- `authenticateRequest` 和 `verifyWebhook` 需要 PSR-7 请求对象。如需请使用 PSR-7 bridge 转换框架原生请求。
- 异常层级：`VonvonException` -> `TokenException`、`JwksException`、`WebhookException`。

Source: https://vonvon.id/zh-hans/sdks/php/index.mdx