README

A simple dependency-free PHP wrapper for the Almefy API.

快速指南

以下是如何在 PHP 项目中集成 Almefy 以便轻松测试的快速指南。我们正在准备一份全面文档，涵盖所有可能的用例和参数。请耐心等待。

请注意：此文档仍在进行中。

先决条件

要成功初始化 PHP 客户端，您需要从 Almefy 获取 API 密钥和 API 秘密。

# Example .env Data

ALMEFY_KEY=...
ALMEFY_SECRET=...

安装

Almefy PHP Client 可在 Packagist 上作为 almefy/client 包使用。在终端中，从项目根目录运行 composer require almefy/client，然后完成。如果由于任何原因您不能使用 composer，您可以从 GitHub 下载最新版本。目前支持的最低 PHP 版本为 8.0。

客户端初始化

安装完包后，您需要实例化一个客户端对象。此示例假设您将密钥存储在某些环境变量中

$client = new \Almefy\Client($_ENV['ALMEFY_KEY'], $_ENV['ALMEFY_SECRET']);

身份注册

在用户账户可以使用 Almefy 应用之前，它需要注册并且设备配置。使用 Almefy 注册账户的最简单方法是发送一封包含注册 QR 码的电子邮件给用户。一个不错的选择是在受保护区域内的某个地方放置一个“使用 Almefy 连接”按钮，该按钮在后端触发以下过程

try {
    $enrollmentToken = $client->enrollIdentity('john.doe');
    
} catch (\Almefy\Exception\TransportException $e) {
    echo 'Could not connect to Almefy service: '.$e->getMessage();
}

返回的 $enrollmentToken 对象提供了一个公开的 base64ImageData 属性，其中包含用于任何 HTML 电子邮件的 base64 编码的图像数据。

如果启用，您还可以使用 Almefy API 发送不带自定义电子邮件客户端兼容模板的通用注册电子邮件

try {
    $client->enrollIdentity('john.doe', array(
        'sendEmail' => true
        'sendEmailTo' => 'john.doe@example.com'
    ));
    
} catch (\Almefy\Exception\TransportException $e) {
    echo 'Could not connect to Almefy service: '.$e->getMessage();
}

注意：查看 API 注册参考了解所有可用选项。

此过程创建或使用现有身份并发送包含 QR 码的注册电子邮件，需要使用 Almefy 应用扫描以配置它。完成后，注册完成，用户即可使用 Almefy 应用进行身份验证。

前端

将以下几行添加到您的 HTML 前端以显示用于身份验证的 Almefy 图片。

<!-- Place this HTML code wherever the Almefy image should appear -->
<div data-almefy-auth
     data-almefy-key="5bbf4923faf099a3515a40d9b0e6e6e32c890ef6cd7a8a120657c2f49d2341fe"
     data-almefy-auth-url="/path/to/auth-controller"></div>

<!-- Load the JavaScript library -->
<script async src="https://cdn.almefy.com/js/almefy-0.9.8.js"
        integrity="sha384-YrIFSeu+BqWh1wivbt+Q90LfEPlPMvlrel3UTRT2FWTc8P1HauLvZNQcoRBzCMpo"
        crossorigin="anonymous"></script>

身份验证

配置在 data-alemfy-auth-url 中的身份验证控制器将接收到来自 Almefy API 的 X-Almefy-Authorization 头。在控制器中要做的第一件事是从头中提取令牌并对其进行解码（它也进行了验证）。

// Get the JWT from header
$jwt = $request->headers->get('X-Almefy-Authorization');

// decode it
$token = $client->decodeJwt($jwt);

注意：JWT 是使用 X-Almefy-Authorization 头提供的，出于兼容性原因（例如，Apache 服务器不会将其转发到 PHP 进程），但也使用标准的 Authorization: Bearer ... 头。

接下来，您应该检查尝试进行身份验证的用户是否在您的身份管理系统内，并且允许进行身份验证。这是您自己的业务逻辑，因此仅作为一个示例

// $userRepository is any PHP class used for database queries 
$user = $userRepository->retrieveByUsername($token->getIdentifier());

// Check any internal business logic
if (!$user->isEnabled() || !$user->isSubscriptionActive()) {
    return false;
}

最后且重要的一步是在 Almefy 系统上验证和确认身份验证尝试

if (!$client->authenticate($token)) {
    // Authentication attempt could not be verified or is invalid
    return false;
}

注意：出于安全原因，任何网络或服务器错误都将始终返回 false。

在此阶段，您可以通过设置会话等方式验证用户，并将其重定向到受保护区域。

许可证

Almefy PHP SDK 在 Apache 许可证第 2 版下授权。

almefy / client

维护者

详细信息