README

PHP API 客户端

此库提供了与 mosparo 通信并验证提交的 API 客户端。

描述

使用此 PHP 库，您可以连接到 mosparo 安装并验证提交的数据。

安装

使用 composer 安装此库

composer require mosparo/php-api-client

使用

1. 在您的 mosparo 安装中创建一个项目
2. 在您的表单中包含 mosparo 脚本

<div id="mosparo-box"></div>

<script src="https://[URL]/build/mosparo-frontend.js" defer></script>
<script>
    var m;
    window.onload = function(){
        m = new mosparo('mosparo-box', 'https://[URL]', '[UUID]', '[PUBLIC_KEY]', {loadCssResource: true});
    };
</script>

1. 在您的项目中包含库

composer require mosparo/php-api-client

1. 在表单提交后，在处理之前验证数据

<?php
require_once(__DIR__ . '/vendor/autoload.php');

$client = new Mosparo\ApiClient\Client($url, $publicKey, $privateKey, [ /* Options for Guzzle */ ]);

$mosparoSubmitToken = $_POST['_mosparo_submitToken'];
$mosparoValidationToken = $_POST['_mosparo_validationToken'];

$result = $client->verifySubmission($_POST, $mosparoSubmitToken, $mosparoValidationToken);

if ($result->isSubmittable()) {
    // Send the email or process the data
} else {
    // Show error message
}

API 文档

客户端

客户端初始化

创建一个新的客户端对象以使用 API 客户端。

/**
 * @param string $url URL of the mosparo installation
 * @param string $publicKey Public key of the mosparo project
 * @param string $privateKey Private key of the mosparo project 
 * @param array $args Arguments for the Guzzle client, see https://docs.guzzlephp.org/en/stable/request-options.html
 */
$client = new Mosparo\ApiClient\Client($url, $publicKey, $privateKey, $args);

验证表单数据

要验证表单数据，请使用数组中的表单数据和提交以及验证令牌调用 verifySubmission，这些令牌是 mosparo 在表单初始化和表单数据验证时生成的。此方法将返回一个 VerificationResult 对象。

/**
 * @param array $formData Array with the form values. All not-processed fields by mosparo (hidden, checkbox, 
 *                        radio and so on) have to be removed from this array
 * @param string $mosparoSubmitToken Submit token which mosparo returned on the form initialization
 * @param string $mosparoValidationToken Validation token which mosparo returned after the form was validated
 * @return \Mosparo\ApiClient\VerificationResult Returns a VerificationResult object with the response from mosparo
 * 
 * @throws \Mosparo\ApiClient\Exception Submit or validation token not available.
 * @throws \Mosparo\ApiClient\Exception An error occurred while sending the request to mosparo.
 */
$result = $client->verifySubmission($formData, $mosparoSubmitToken, $mosparoValidationToken);

请求统计数据

mosparo 还有一个 API 方法可以获取项目的统计数据。您可以使用 getStatisticByDate 方法获取统计数据。您可以指定秒数范围或从其中 mosparo 应返回统计数据的起始日期。此方法将返回一个 StatisticResult 对象。

/**
 * @param int $range = 0 The range in seconds for which mosparo should return the statistical data (will be rounded up to a full day since mosparo v1.1)
 * @param \DateTime $startDate = null The Start date from which on mosparo should return the statistical data (requires mosparo v1.1)
 * @return \Mosparo\ApiClient\StatisticResult Returns a StatisticResult object with the response from mosparo
 * 
 * @throws \Mosparo\ApiClient\Exception An error occurred while sending the request to mosparo.
 */
$result = $client->getStatisticByDate($range, $startDate);

VerificationResult

常量

• FIELD_NOT_VERIFIED: 'not-verified'
• FIELD_VALID: 'valid'
• FIELD_INVALID: 'invalid'

isSubmittable(): boolean

如果表单可提交，则返回 true。这意味着验证成功，表单数据有效。

isValid(): boolean

如果 mosparo 将表单视为有效，则返回 true。与 isSubmittable() 的区别在于，这是 mosparo 的原始结果，而 isSubmittable() 还会检查验证是否正确完成。

getVerifiedFields(): array (see Constants)

返回包含所有已验证字段键的数组。

getVerifiedField($key): string (see Constants)

返回一个字段的验证状态。

hasIssues(): boolean

如果有验证问题，则返回 true。

getIssues(): array

返回包含所有验证问题的数组。

StatisticResult

getNumberOfValidSubmissions(): int

返回请求日期范围内有效提交的总数。

getNumberOfSpamSubmissions(): int

返回请求日期范围内垃圾邮件提交的总数。

getNumbersByDate(): array

返回包含请求时间范围内所有统计数据的数组。数组中的键是日期，而值是数组。该数组包含一个键 numberOfValidSubmissions，其中包含有效提交的数量，以及一个键 numberOfSpamSubmissions，其中包含垃圾邮件提交的数量。