---
title: "sdk/php"
description: "SDK de servidor PHP 8.1+ para verificação JWT sem rede, autenticaçãode requisições PSR-7 e validação de assinatura de webhook."
locale: "pt-BR"
---

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

# sdk/php

## Estado

Implementado e verificado localmente. A verificação de ida e voltacom um IdP real (busca de JWKS, assinatura/verificação de tokencontra uma instância Vonvon ativa) ainda não foi realizada e deve serconcluída antes do uso em produção.

Status do registry: UNPUBLISHED. Instale este SDK somente a partir do checkout do código-fonte do repositório; não use um registry de pacotes externo.

A autenticação de requisições aceita somente Bearer por padrão. Um cookie JWT pertencente ao aplicativo só é lido quando seu nome exato é configurado. O cookie opaco do Core \_\_Host-vonvon.rt.\* nunca é pesquisado nem verificado localmente; troque-o encaminhando o header Cookie completo para o POST /v1/sessions/token da mesma origem exata, com redirects desativados, e aceite somente uma resposta que contenha apenas o campo token.

## Instalar

PHP 8.1+ obrigatório. As dependências principais são baixadasautomaticamente pelo Composer.

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

# composer update vonvon/vonvon
```

## Início rápido

```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);
}
```

## Autentica uma requisição 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,
);
```

## Verifica 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);
}
```

## Opções do VonvonClient

| Chave | Padrão | Descrição |
| --- | --- | --- |
| `issuer` | obrigatório | URI do emissor Vonvon |
| `audience` | `null` | Audiência esperada; null ignora a validação |
| `cache` | `null` | CacheInterface PSR-16 para cache de JWKS |
| `jwks_ttl` | `3600` | TTL do cache JWKS em segundos |
| `clock_leeway` | `0` | Tolerância de desvio de relógio JWT em segundos |
| `cookie_name` | `disabled` | Nome do cookie JWT pertencente ao aplicativo; desativado salvo configuração explícita |

## Métodos do VonvonClient

| Método | Retornos | Descrição |
| --- | --- | --- |
| `verifyToken(string $token)` | `Claims` | Verifica string JWT; lança exceção em caso de falha |
| `authenticateRequest(ServerRequestInterface $request)` | `AuthResult` | Autentica requisição PSR-7; não lança exceções |
| `verifyWebhook(ServerRequestInterface $request, string $secret)` | `WebhookPayload` | Valida a assinatura do webhook; lança exceção em caso de falha |
| `refreshJwks()` | `void` | Forçar atualização do cache JWKS |

## Notas da plataforma

- Usa `firebase/php-jwt` para verificação ES256/RS256. Osalgoritmos HS256 e `none` são rejeitados.
- Requer um objeto de requisição PSR-7 para `authenticateRequest`e `verifyWebhook`. Converta requisições nativas do framework comuma ponte PSR-7 se necessário.
- Hierarquia de exceções: `VonvonException` -> `TokenException`,`JwksException`, `WebhookException`.

Source: https://vonvon.id/pt-br/sdks/php/index.mdx