---
title: "sdk/php"
description: "네트워크 호출 없는 JWT 검증, PSR-7 요청 인증, webhook 서명 검증을 위한 PHP 8.1+ 서버 SDK."
locale: "ko"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ko/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를 redirect가 비활성화된 exact same-origin POST /v1/sessions/token으로 전달해 교환하고 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` | 예상 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/ko/sdks/php/index.mdx