novadaemon/skyflow-php

此PHP SDK旨在帮助开发者轻松将Skyflow集成到他们的php后端。

维护者

详细信息

github.com/novadaemon/skyflow-php

源代码

问题

资助包维护！
novadaemon

安装: 6

依赖项: 0

建议者: 0

安全: 0

星标: 1

关注者: 1

分支: 0

开放问题: 0

v1.0.0 2023-06-10 14:06 UTC

Requires

MIT f2fe9620ed94bf58939bbb7355af6de1a45afe62

  • Jesús García <novadaemon.woop@gmail.com>

This package is auto-updated.

Last update: 2024-09-16 18:07:50 UTC

README

描述

此PHP SDK旨在帮助开发者轻松将Skyflow集成到他们的php后端。

Cover

目录表

功能

使用Skyflow服务帐户进行身份验证并生成承载令牌。

执行向保险库API插入、检索、更新、删除和令牌化敏感数据操作。

在保险库模式中执行SQL查询。

调用下游第三方API，而不直接处理敏感数据。

安装

要求

  • 需要PHP 8.1或更高版本
  • 您需要已安装Composer

安装

在终端中输入

composer require novadaemon/skyflow-php

示例

您可以在samples目录中找到SDK所有功能的示例。要运行特定示例

  1. 使用git clone https://github.com/novadaemon/skyflow-php.git下载仓库
  2. 在项目目录中运行$ composer install
  3. 转到终端中的samples目录。
  4. 将示例文件中<<括号内的值更改为正确值。
  5. 执行您想要的示例： $ php get_records.php

先决条件

  • 一个Skyflow帐户。如果您还没有，可以在尝试Skyflow页面注册一个。
  • PHP 8.1或更高。
  • GIT

创建保险库

  1. 在浏览器中，登录到Skyflow Studio。
  2. 通过点击创建保险库 > 从模板开始 > 快速启动保险库创建一个保险库。
  3. 一旦保险库准备就绪，点击齿轮图标并选择编辑保险库详细信息。
  4. 注意您的保险库URL和保险库ID值，然后点击取消。您稍后需要这些信息。

创建服务帐户

  1. 在侧导航中点击，IAM > 服务帐户 > 新建服务帐户。
  2. 对于名称，输入"SDK示例"。对于角色，选择保险库编辑器。
  3. 点击创建。您的浏览器将下载一个credentials.json文件。请确保此文件安全，因为您将需要它在每个示例中。

服务帐户令牌生成

Novadaemon\SkyFlow\ServiceAccount\Token类用于从服务帐户凭证文件生成服务帐户令牌，该文件是在创建服务帐户时下载的。从这个类生成的令牌有效期为60分钟，可用于向保险库服务以及基于服务帐户权限的管理API(s)进行API调用。

Token::generateBearerToken($credentialsPath)静态方法用于接受令牌生成的凭证文件路径，或者您也可以通过使用Token::generateBearerTokenFromCredentials($credentials)发送整个凭证作为数组。

使用文件路径的示例:

<?php

declare(strict_types=1);

use Novadaemon\Skyflow\Exceptions\SkyflowException;
use Novadaemon\Skyflow\ServiceAccount\Token;

require __DIR__ . '/../vendor/autoload.php';

try {
    $path = '<YOUR_CREDENTIALS_FILE_PATH>';

    $token = Token::generateBearerToken($path);

    var_dump($token);
} catch (SkyflowException $e) {
    echo($e->getMessage());
}

使用凭证的示例:

<?php

declare(strict_types=1);

use Novadaemon\Skyflow\ServiceAccount\Token;
use Novadaemon\Skyflow\Exceptions\SkyflowException;

require __DIR__ . '/../vendor/autoload.php';

try {
    $credentials = [
        'clientID' => '<CLIENT_ID>',
        'clientName' => '<CLIENT_NAME>',
        'tokenURI' => '<TOKEN_URI>',
        'keyID' => '<KEY_ID>',
        'privateKey' => '<PRIVATE_KEY>',
    ];

    $token = Token::generateBearerTokenFromCredentials($credentials);

    var_dump($token);
} catch (SkyflowException $e) {
    echo($e->getMessage());
}

响应

<?php 

array (
  'accessToken' => 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL21hbmFnZS5za3lmbG93YXBpcy5jb20iLCJjbGkiOiJlNzVkZmNmMzMwN2Q0M2I2YjZlN2JhNTk2ZTU5ODgxNyIsImV4cCI6MTY3ODEyMzI1NCwiaWF0IjoxNjc4MTE5NjU3LCJpc3MiOiJzYS1hdXRoQG1hbmFnZS5za3lmbG93YXBpcy5jb20iLCJqdGkiOiJmZTZkYzRjNGY1YmM0OTllODhjOTc0ZmNjZGRjZGMyZCIsImtleSI6ImJlNjk0YTJlYTFmNjQ3ZDM5N2E1YzIwNWZlYjRmMzUxIiwic2NwIjpudWxsLCJzdWIiOiJUZXN0U2VydmljZSJ9.WXSqZh7fQwx9E1ngKKSD9jfPLNWLzE46CKWuZ0bovbZFTGLKcHy94z-SKb1qxtW-CedcbgbnK7Wjd-H20PusjbLGCcjPcAQt7pghUvdpLabuR8DIW0sbfTwen5JnhVupHp0_3tXwp8jJDGF6s8JExVA9DhMLoyusqC9wD_Gmemdj4dU_r4drKhiVYgnsbD8NgZyc6yfgWXrE51IoqLd9FsZ0rDDrys3ttwEbYLRXnr1NGGsftqI0-y4K2gu090BJ2wtDlQO61ZD8_KZSZSEpxr6ZYIMuYsG7SxvnkR6OMz1fVWbtptf1EzEk-ky2M2r5oGGYH_WFBakVk8wKHQy3og',
  'tokenType' => 'Bearer',
)

保险库API

Novadaemon\Skyflow\Vault\Client 类提供了所有在保险库上执行操作的方法，例如获取记录、插入记录、解密令牌、获取 skyflow_id 对应的令牌、执行 SQL 查询和调用连接。

要使用此类，必须首先按照以下方式初始化 skyflow 客户端。

<?php

use Novadaemon\Skyflow\Vault\Client;
use Novadaemon\Skyflow\ServiceAccount\Token;

require __DIR__.'/../vendor/autoload.php';

# User defined function to provide access token to the vault apis
$tokenProvider = function (string $token): string {

    if (Token::isExpired($token)) {
        $token = Token::generateBearerToken('<YOUR_CREDENTIALS_FILE_PATH>');
        return $token['accessToken'];
    }

    return $token;
};

#Initializing a Skyflow Client instance with the required constructor parameters
$client = new Client(
    vaultID: '<YOUR_VAULT_ID>', 
    vaultUrl: '<YOUR_VAULT_URL>', 
    tokenProvider: $tokenProvider
);

必须使用客户端实例调用所有 Vault API 端点。

获取记录

使用 Client@getRecords() 方法执行检索表格记录的批量操作。此方法有以下参数

注意：有些参数不能与其他参数同时使用。如果您错误地传递了 getRecords 方法的参数，则会抛出 SkyflowException。

注意：如果令牌化参数为 true，则可以在 fields 参数中设置仅包含令牌化的字段名称。如果将令牌化参数设置为 true 并在 fields 参数中设置非令牌化的字段名称，则返回错误。

Client@getRecords() 调用的示例

<?php

$response = $client->getRecords(
    table: 'cards',
    ids: [
        "1a8ec9d5-9be6-465d-a8ad-2797d7258a10",
        "76c892f4-7523-4e74-ac82-afc7bdea7d74"
    ],
    redaction: RedactionType::PLAIN_TEXT,
    tokenization: false
);

响应

<?php 

array (
  'records' => 
  array (
    0 => 
    array (
      'fields' => 
      array (
        'card_cvv' => '123',
        'card_expiration' => '03/26',
        'card_number' => '4242424242424242',
        'skyflow_id' => '1a8ec9d5-9be6-465d-a8ad-2797d7258a10',
      ),
    ),
    1 => 
    array (
      'fields' => 
      array (
        'card_cvv' => '234',
        'card_expiration' => '12/24',
        'card_number' => '4111111111111111',
        'skyflow_id' => '76c892f4-7523-4e74-ac82-afc7bdea7d74',
      ),
    ),
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 5,
    'http_code' => 404,
    'message' => 'No Records Found',
    'http_status' => 'Not Found',
  ),
)

通过 ID 获取记录

要仅从 Skyflow 保险库中检索一条记录，请使用 Client@getRecordById() 方法。此方法有以下参数

Client@getRecordById() 调用的示例

<?php 

$response = $client->getRecordById(
    table: 'consumers',
    id: '76193681-d272-4ffe-80f9-6498398e4c7b',
    fields: [
        'first_name',
        'last_name',
        'email',
        'phone',
    ]
);

响应

<?php 

array (
  'fields' => 
  array (
    'email' => 'j******s@gmail.com',
    'first_name' => '*REDACTED*',
    'last_name' => '*REDACTED*',
    'phone' => 'XXXXXX0000',
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 5,
    'http_code' => 404,
    'message' => 'No Records Found',
    'http_status' => 'Not Found',
  ),
)

将记录插入到保险库中

要向保险库中插入数据，请使用 Cient@insertRecord() 方法。此方法的参数为

Client@insertRecords() 调用的示例

<?php 

$records = [
    [
        "fields" => [
            "card_number" => "5555555555554444",
            "card_expiration" => "12/25",
            "card_cvv" => "111",
        ]
    ],
    [
        "fields" => [
            "card_number" => "5105105105105100",
            "card_expiration" => "04/28",
            "card_cvv" => "123",
        ]
    ],
];

$response = $client->insertRecords(
    table: 'cards',
    records: $records,
    tokenization: true,
    upsert: 'card_number'
);

响应

<?php 

array (
  'records' => 
  array (
    0 => 
    array (
      'skyflow_id' => '76c892f4-7523-4e74-ac82-afc7bdea7d74',
      'tokens' => 
      array (
        'card_cvv' => '19a364b9-0b39-4cad-a544-45c7ba1c52eb',
        'card_expiration' => '1b4ab2f7-fdd8-48f2-8b50-eb97075eda2e',
        'card_number' => '5554-3665-8198-3602',
      ),
    ),
    1 => 
    array (
      'skyflow_id' => '1a8ec9d5-9be6-465d-a8ad-2797d7258a10',
      'tokens' => 
      array (
        'card_cvv' => 'b5bade68-3a0d-4895-8c27-edd911c11e99',
        'card_expiration' => '767eda0a-ed3a-4781-82d5-755207acf1e0',
        'card_number' => '8080-3444-8671-2308',
      ),
    ),
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 9,
    'http_code' => 400,
    'message' => 'Error Inserting Records due to unique constraint violation',
    'http_status' => 'Bad Request',
    'details' => 
    array (
    ),
  ),
)

更新记录

要更新保险库中的数据，请使用 Client@updateRecord() 方法。此方法的参数为

Client@updateRecord() 调用的示例

<?php 

$record =  [
    'fields' => [
        "email" => 'jhon@fake.com',
        "phone" => '+5478698765',
    ]
];

$response = $client->updateRecord(
    table: 'consumers',
    id: '76193681-d272-4ffe-80f9-6498398e4c7b',
    record: $record,
    tokenization: false
);

响应

<?php 

array (
  'skyflow_id' => '76193681-d272-4ffe-80f9-6498398e4c7b',
  'createdTime' => '',
  'updatedTime' => '',
  'tokens' => 
  array (
    'email' => 'nqmlqdxatzkwhqujzltu@opkfulnxkx.com',
    'phone' => '54df9553-6688-4359-a8ff-df5cbd9cfa55',
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 3,
    'http_code' => 400,
    'message' => 'Invalid field present in JSON invalid-field',
    'http_status' => 'Bad Request',
    'details' => 
    array (
    ),
  ),
)

删除记录

Client@deleteRecord() 允许您从 Skyflow 保险库中删除记录。此方法有以下参数

Client@deleteRecord() 调用的示例

<?php 

$response = $client->deleteRecord('cards', 'e95834a2-cf1e-40ac-9f0d-0ea2c7920a8d');

响应

<?php 

array (
  'skyflow_id' => 'e95834a2-cf1e-40ac-9f0d-0ea2c7920a8d',
  'deleted' => true,
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 5,
    'http_code' => 404,
    'message' => 'No Records Found',
    'http_status' => 'Not Found',
  ),
)

批量删除

Client@bulkDelete() 允许您从 Skyflow 保险库中删除指定的记录。此方法有以下参数

Client@bulkDelete() 调用的示例

<?php 

#Delete all records from cards table
$response = $client->bulkDelete('cards');

响应

<?php 

array (
  'RecordIDResponse' => 
  array (
    0 => '*',
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 13,
    'http_code' => 500,
    'message' => 'Couldn\'t load data',
    'http_status' => 'Internal Server Error',
    'details' => 
    array (
    ),
  ),
)

脱密

为了使用您先前为该数据生成的令牌从您的保险库中检索数据，您可以使用 Client@detokenize() 方法。此方法的参数为

Client@detokenize() 调用的示例

<?php 

$params =  [
    ['token' => 'aa3cc614-af50-4365-a7ac-82f83a79eef8'],
    ['token' => 'e77674ac-4a21-4318-8bdd-5ad20f1b47c7'],
    ['token' => 'nqmlqdxatzkwhqujzltu@opkfulnxkx.com']
];

$response = $client->detokenize($params);

响应

<?php 

array (
  'records' => 
  array (
    0 => 
    array (
      'token' => 'aa3cc614-af50-4365-a7ac-82f83a79eef8',
      'valueType' => 'STRING',
      'value' => '234',
    ),
    1 => 
    array (
      'token' => 'e77674ac-4a21-4318-8bdd-5ad20f1b47c7',
      'valueType' => 'STRING',
      'value' => '12/24',
    ),
    2 => 
    array (
      'token' => 'nqmlqdxatzkwhqujzltu@opkfulnxkx.com',
      'valueType' => 'STRING',
      'value' => 'jhon@fake.com',
    ),
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 5,
    'http_code' => 404,
    'message' => 'Token not found for invalid-token',
    'http_status' => 'Not Found',
    'details' => 
    array (
    ),
  ),
)

注意：params 参数的每个项目的结构为

<?php 

[
  'token' => 'STRING' # The Skyflow token to be detokenized
  'redaction' => 'STRING' # Redaction policy. Not required. Default DEFAULT. Only accept values presente in RedactionType enum: DEFAULT, REDACTED, MASKED, PLAIN_TEXT  
]

令牌化

Client@tokenize() 方法返回与指定记录对应的令牌。仅适用于具有确定性令牌化的字段。此方法的参数为

注意：此端点不插入记录，它返回现有值的令牌。要插入记录并令牌化新记录的值，请参阅将记录插入保险库和令牌化参数。

Client@tokenize() 调用的示例

<?php 

$params =  [
    [
        'value' => '5105105105105100',
        'table' => 'cards',
        'column' => 'card_number'
    ],
];

$response = $client->tokenize($params);

响应

<?php 

array (
  'records' => 
  array (
    0 => 
    array (
      'token' => '0782-1334-4999-6413',
    ),
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 5,
    'http_code' => 404,
    'message' => 'Tokenize returns previously issued tokens for existing data. Provided value(s) do not exist in the provided table.column(s): card_number',
    'http_status' => 'Not Found',
    'details' => 
    array (
    ),
  ),
)

执行SQL查询

Client@query() 方法返回有效 SQL 查询的记录。虽然此端点检索符合有效编辑方案的列，但它无法检索令牌。仅支持 SELECT 命令。此方法的参数为

注意： 查看关于查询限制的更多信息，请参阅 Skyflow API 文档。

以下是一个 示例，展示了如何调用 Client@query() 方法。

<?php 

$query =  "SELECT * FROM cards WHERE card_number = '5105105105105100'";

$response = $client->query($query);
<?php 

array (
  'records' => 
  array (
    0 => 
    array (
      'fields' => 
      array (
        'card_cvv' => '*REDACTED*',
        'card_expiration' => '*REDACTED*',
        'card_number' => '5105105105105100',
        'orders_skyflow_id' => NULL,
        'skyflow_id' => '1084350b-d4a2-45b1-801f-2fd46bef0721',
      ),
    ),
  ),
)

错误

<?php 

array (
  'error' => 
  array (
    'grpc_code' => 13,
    'http_code' => 500,
    'message' => 'ERROR (internal_error): Could not find Field car_number',
    'http_status' => 'Internal Server Error',
    'details' => 
    array (
    ),
  ),
)

调用连接

使用 Skyflow 连接，最终用户应用程序可以将结账/卡发行流程与其应用程序/系统集成。要调用连接，请使用 Skyflow 客户端的 Client@invokeConnection() 方法。此方法接受以下参数：

注意： 查看有关连接的更多信息，请参阅 Skyflow API 文档。

以下是一个 示例，展示了如何调用 Client@invokeConnection() 方法。

<?php 

$headers = [
    'Content-Type' => 'application/json',
    'Authorization' => '<YOUR_CONNECTION_BASIC_AUTH>'
];

$body = [
    'firstName' => 'Jesús',
    'lastName' => 'García',
    'email' => 'nqmlqdxatzkwhqujzltu@opkfulnxkx.com',
    'phone' => '54df9553-6688-4359-a8ff-df5cbd9cfa55',
];

$url = 'https://ebfc9bee4242.gateway.skyflowapis.com/v1/gateway/outboundRoutes/x2f47b94462a46989ac7b37817ef99bf/users/add';

$response = $client->invokeConnection(
    connectionUrl: $url,
    method: RequestMethodType::POST,
    headers: $headers,
    body: $body
);
<?php 

array (
    'email' => 'jhon@fake.com',
    'firstName' => 'Jesús',
    'lastName' => 'García',
    'phone' => '+5478698765'
)