README

这是SnapAuth的官方PHP SDK，您可以访问SnapAuth。

文档

完整API和用法文档可在官方站点找到。

安装

composer require snapauth/sdk

设置

从仪表板获取您的密钥，并将其提供给SnapAuth\Client类

use SnapAuth\Client;

$yourSecret = getenv('SNAPAUTH_SECRET_KEY');
$snapAuth = new Client(secretKey: $yourSecret);

提示

密钥是特定于环境和域的。我们强烈建议使用环境变量或另一种外部存储机制。避免将其提交到版本控制，因为这可能导致更容易被篡改。

如果您没有直接提供值，SDK将自动检测SNAPAUTH_SECRET_KEY环境变量。

用法

注册

一旦从前端获取注册令牌，请使用Client完成流程并将其附加到用户

$token = 'value_from_frontend'; // $_POST['snapauth_token'] or similar
$userInfo = [
  'id' => 'your_user_id',
  'handle' => 'your_user_handle',
];
$snapAuth->attachRegistration($token, $userInfo);

这会激活密钥并将其与用户关联。在认证过程中，您将收到$userInfo，这样您就知道谁在登录。

id应该是某种稳定的标识符，例如数据库主键。

handle可以是您想要的任何内容，或者可以完全省略。它在客户端认证期间提供便利，这样您就不需要再次查找用户ID。这通常是指用户提供的登录值，例如用户名或电子邮件。

两者都必须是字符串，长度最多可达255个字符。认证过程中的查找是不区分大小写的。

提示

我们强烈建议您混淆任何可能敏感的信息，例如电子邮件地址。您可以通过哈希值来实现这一点。请注意，要在认证期间使用handle，您需要在您的客户端上重复混淆过程。

认证

与注册一样，您需要从前端获取客户端SDK提供的令牌。

使用verifyAuthToken方法以AuthResponse对象的形式获取有关认证过程的信息。该对象包含先前注册的用户id和handle。

$token = 'value_from_frontend'; // $_POST['snapauth_token'] or similar
$authInfo = $snapAuth->verifyAuthToken($token);

// Specific to your application:
$authenticatedUserId = $authInfo->user->id;

// Laravel:
use Illuminate\Support\Facades\Auth;
Auth::loginUsingId($authenticatedUserId);

错误处理

SnapAuth SDK以安全方式编写，如果您不在成功路径上，它将抛出异常。这有助于确保您的集成简单且可靠。

您可以选择在本地将API调用包装在try/catch块中，或者让通用的应用程序范围错误处理器处理任何异常。

所有SnapAuth异常都是instanceof \SnapAuth\ApiError。

兼容性

我们遵循语义版本控制，并将向后不兼容的更改限制在主要版本（X.Y.Z中的X）中。

SnapAuth SDK维护所有版本的PHP，包括当前安全支持的版本。由于Composer会检测您当前安装的PHP版本，因此停止支持旧版本不视为向后兼容性中断（但您可能无法安装较新版本，直到您更新到支持的PHP版本）。

标记为@internal的任何内容，或任何protected或private方法，都不在向后兼容性保证的范围内。类似地，所有方法应被视为可能抛出异常的方法，因此新类型的异常也不视为BC中断。