---
title: "sdk/php"
description: "SDK de servidor PHP 8.1+ para verificación JWT sin llamadas de red, autenticación de solicitudes PSR-7 y validación de firma de webhook."
locale: "es"
---

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

# sdk/php

## Estado

Implementado y verificado localmente. La verificación de ida y vuelta contra un IdP real (obtención de JWKS, firma/verificación de tokens contra una instancia Vonvon en producción) aún no se ha realizado y debe completarse antes del uso en producción.

Estado del registro: UNPUBLISHED. Instala este SDK únicamente desde el checkout del código fuente del repositorio; no uses un registro de paquetes externo.

La autenticación de solicitudes acepta solo Bearer de forma predeterminada. Una cookie JWT propiedad de la aplicación solo se lee cuando se configura su nombre exacto. La cookie opaca de Core \_\_Host-vonvon.rt.\* nunca se busca ni se verifica localmente; intercámbiala reenviando el header Cookie completo al POST /v1/sessions/token del mismo origen exacto, con las redirecciones desactivadas, y acepta solo una respuesta que contenga únicamente el campo token.

## Instalación

Se requiere PHP 8.1+. Las dependencias principales se obtienen automáticamente con Composer.

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

# composer update vonvon/vonvon
```

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

## Autenticar una solicitud 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,
);
```

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

## Opciones de VonvonClient

| Clave | Por defecto | Descripción |
| --- | --- | --- |
| `issuer` | obligatorio | URI del emisor Vonvon |
| `audience` | `null` | Audiencia esperada; null omite la validación |
| `cache` | `null` | CacheInterface PSR-16 para almacenamiento en caché de JWKS |
| `jwks_ttl` | `3600` | TTL del caché de JWKS en segundos |
| `clock_leeway` | `0` | Tolerancia de desfase de reloj JWT en segundos |
| `cookie_name` | `disabled` | Nombre de cookie JWT propiedad de la aplicación; desactivado salvo configuración explícita |

## Métodos de VonvonClient

| Método | Devuelve | Descripción |
| --- | --- | --- |
| `verifyToken(string $token)` | `Claims` | Verifica una cadena JWT; lanza excepción al fallar |
| `authenticateRequest(ServerRequestInterface $request)` | `AuthResult` | Autenticar solicitud PSR-7; no lanza excepciones |
| `verifyWebhook(ServerRequestInterface $request, string $secret)` | `WebhookPayload` | Valida la firma del webhook; lanza excepción al fallar |
| `refreshJwks()` | `void` | Forzar actualización del caché de JWKS |

## Notas de plataforma

- Usa `firebase/php-jwt` para la verificación ES256/RS256. Los algoritmos HS256 y `none` son rechazados.
- Requiere un objeto de solicitud PSR-7 para `authenticateRequest` y `verifyWebhook`. Convierte las solicitudes nativas del framework con un bridge PSR-7 si es necesario.
- Jerarquía de excepciones: `VonvonException` -> `TokenException`, `JwksException`, `WebhookException`.

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