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 XID 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-xid.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.

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

# composer update xid/xid

Inicio rápido

use Xid\XidClient;
use Xid\Exception\TokenException;
use Xid\Exception\JwksException;

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

try {
    $claims = $xid->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

$result = $xid->authenticateRequest($psrRequest);

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

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

Verificar webhook

use Xid\Exception\WebhookException;

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

Opciones de XidClient

Métodos de XidClient

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: XidException -> TokenException, JwksException, WebhookException.