README

用于 e-satisfaction API 的 PHP 库

要求

PHP 7.1.0 及以上版本。

Composer

您可以通过 Composer 安装绑定。运行以下命令

composer require esatisfaction/esat-php

要使用绑定，请使用 Composer 的自动加载

require_once('vendor/autoload.php');

手动安装

如果您不想使用 Composer，您可以下载最新版本。然后，要使用绑定，包含 init.php 文件。

require_once('/path/to/esatisfaction-php/init.php');

依赖

此库需要以下扩展和包才能正常工作

如果您使用 Composer，这些依赖项应该会自动处理。如果您手动安装，请确保这些扩展可用并已加载。

如何开始使用服务？

要开始使用 SDK，您必须初始化以下内容

设置主 Esat 注册表
设置每个服务的 HttpClient 所使用的授权方案

示例

use \Esat\Esat;
use \Esat\Auth\TokenAuthProvider;
use \Esat\Http\AuthClient;
use \Monolog\Logger;

// Initialize Authentication
$tokenAuthProvider = new TokenAuthProvider('YOUR_TOKEN', 'YOUR_DOMAIN');
$httpClient = new AuthClient($tokenAuthProvider);

// Initialize main Esatisfaction Registry
$esatRegistry = new Esat();

问卷调查

读取您的问卷调查

use \Esat\Services\Questionnaires\Questionnaire;
use \Esat\Support\Model\Propel\FilterCriteria;
use \Esat\Support\Model\Propel\Pagination;
use \Monolog\Logger;

// Create Questionnaire Service
$questionnaire = new Questionnaire($esatRegistry, new Logger(), $httpClient);

// Load all questionnaires for my application
$applicationId = '123';
$filterCriteria = (new FilterCriteria())->equal('OwnerApplicationId', $applicationId);
$pagination = (new Pagination())->setMaxPerPage(25)->setPage(1);
$questionnairePager = $questionnaire->getList($filterCriteria, null, $pagination);

// Read all questionnaires
foreach ($questionnairePager->getQuestionnaires() as $questionnaireItem) {
    // Get questionnaire display name
    echo $questionnaireItem->getDisplayName();
}

// Load a questionnaire by id
if ($questionnaire->load('456sdfa')) {
    // Access questionnaire data
    $questionnaireModel = $questionnaire->getQuestionnaire();
    echo $questionnaireModel->getDisplayName();
}

问卷调查实例

创建问卷调查实例并发送给您的客户

use \Esat\Services\Questionnaires\Instances\Questionnaire;
use \Monolog\Logger;

// Create Questionnaire Service
$questionnaire = new Questionnaire($esatRegistry, new Logger(), $httpClient);

// Create questionnaire instance, with metadata
$responderMetadata = [
    'email' => 'john@doe.com',
    'gender' => 'male'
];
$questionnaireMetadata = [
    'transaction_id' => '12345asd',
    'transaction_date' => '2019-05-03 14:12'
];
if ($questionnaire->create('YOUR_QUESTIONNAIRE_ID', [], $questionnaireMetadata, $responderMetadata)) {
    // Get questionnaire collection url
    $collectionUrl = $questionnaire->getQuestionnaire()->getCollectionUrl();
    
    // Send your email with the above url
}

读取、更新或删除问卷调查实例

注意：这将导致数据删除并可能更改您的数据。这不会影响您的积分，因为积分在提交问卷调查时减少。

use \Esat\Services\Questionnaires\Instances\Questionnaire;
use \Monolog\Logger;

// Create Questionnaire Service
$questionnaire = new Questionnaire($esatRegistry, new Logger(), $httpClient);

// Load a questionnaire instance
// We always have to load the instance before performing an update or delete operation
$instanceId = 'sadfewf2134d';
if (!$questionnaire->load($instanceId)) {
    // Handle error
    echo 'Questionnaire instance Not Found';
    die;
}

// Update the questionnaire instance
$questionnaire->getQuestionnaire()->setLocale('el');
$questionnaire->getQuestionnaire()->setValidDayes(50);
if (!$questionnaire->update()) {
    // Handle error
    echo 'Questionnaire instance failed to be updated';
    die;
}

// Load another questionnaire instance to delete
// We always have to load the instance before performing an update or delete operation
$instanceId = '23rteg34';
if (!$questionnaire->load($instanceId)) {
    // Handle error
    echo 'Questionnaire instance Not Found';
    die;
}

// Delete the questionnaire instance
if (!$questionnaire->delete()) {
    // Handle error
    echo 'Questionnaire instance failed to be deleted';
    die;
}

流水线

读取您的流水线

use \Esat\Services\Questionnaires\Pipeline;
use \Monolog\Logger;

// Create Pipeline Service
$pipeline = new Pipeline($esatRegistry, new Logger(), $httpClient);

// Get all pipelines for a given questionnaire id
$questionnaireId = 'asdf34rtefdfwe';
$pipelines = $pipeline->getList($questionnaireId);

// Read all pipelines
foreach ($pipelines as $pipelineItem) {
    // Get pipeline title
    echo $pipelineItem->getTitle();
}

// Load a pipeline by id
if ($pipeline->load('345uyjhg')) {
    // Access pipeline data
    $pipelineModel = $pipeline->getPipeline();
    echo $pipelineModel->getTitle();
}

队列项

添加队列项以允许 e-satisfaction 发送调查

use \Esat\Services\Questionnaires\Pipelines\Queue;
use \Monolog\Logger;

// Create Queue Service
$queue = new Queue($esatRegistry, new Logger(), $httpClient);

// Prepare queue item parameters
$questionnaireId = 'asdf34rtefdfwe';
$pipelineId = 'a09uherwgfd';
$parameters = [
    'responder_channel_identifier' => 'john@doe.com',
    'send_time' => '2019-05-02 12:32',
];

// Create queue item
if (!$queue->create($questionnaireId, $pipelineId, $parameters)) {
    // Handle error
    echo 'Queue item failed to be created. Error: ' . $queue->getErrorFromLastResponse();
    die;
}

读取、更新或删除队列项

use \Esat\Services\Questionnaires\Pipelines\Queue;
use \Monolog\Logger;

// Create Queue Service
$queue = new Queue($esatRegistry, new Logger(), $httpClient);

// Load a queue item
// We always have to load the item before performing an update or delete operation
$itemId = '9867w4wqrefd';
if (!$queue->load($itemId)) {
    // Handle error
    echo 'Queue item Not Found';
    die;
}

// Update the queue item
$queue->getQueueItem()->setLocale('el');
$queue->getQueueItem()->setSendTime('2019-06-03 14:32');
if (!$queue->update()) {
    // Handle error
    echo 'Queue item failed to be updated';
    die;
}

// Load another queue item to delete
// We always have to load the item before performing an update or delete operation
$itemId = '234rweg34';
if (!$queue->load($itemId)) {
    // Handle error
    echo 'Queue item Not Found';
    die;
}

// Delete the queue item
if (!$queue->delete()) {
    // Handle error
    echo 'Queue item failed to be deleted';
    die;
}

错误处理

每个请求都会存储最后的响应，以便您可以访问它并在出错时获取消息。

use \Esat\Services\Questionnaires\Questionnaire;
use \Monolog\Logger;

// Create Questionnaire Service
$questionnaire = new Questionnaire($esatRegistry, new Logger(), $httpClient);

// Load a questionnaire by id
if ($questionnaire->load('456sdfa')) {
    // Access questionnaire data
    $questionnaireModel = $questionnaire->getQuestionnaire();
} else {
    // Handle the error, get the http response code and error message, if any
    $error = '';
    switch ($questionnaire->getLastResponse()->getStatusCode()) {
        case 500:
            $error = 'An unexpected error occurred';
            break;
        case 404:
            $error = 'Questionnaire Not Found';
            break;
        default:
            $error = $questionnaire->getErrorFromLastResponse();
    }
    
    // Display error
    echo $error;
}

缓存

此库使用默认的运行时缓存机制，以减少运行时的 API 调用。

缓存机制在服务级别，仅在读取请求上工作，并在对同一服务调用 POST 或 PATCH 方法时重置。

如果您试图在不进行任何更新的情况下两次读取相同的资源，服务将命中缓存并获取相同的结果。您可以在调用方法之前通过在服务上调用 setCacheEnabled(false) 来覆盖缓存。

示例

use \Esat\Services\Questionnaires\Questionnaire;
use \Monolog\Logger;

// Create Questionnaire Service
$questionnaire = new Questionnaire($esat, new Logger(), $httpClient);

// DOES NOT hit cache
if ($questionnaire->load('456sdfa')) {
    // Access questionnaire data
    $questionnaireModel = $questionnaire->getQuestionnaire();
}

// DOES hit cache
if ($questionnaire->load('456sdfa')) {
    // Access questionnaire data
    $questionnaireModel = $questionnaire->getQuestionnaire();
}

// SKIP cache. From now on, all requests will skip cache.
$questionnaire->setCacheEnabled(false);
if ($questionnaire->load('456sdfa')) {
    // Access questionnaire data
    $questionnaireModel = $questionnaire->getQuestionnaire();
}

// Enable cache again to restore initial behavior. The following will DO hit cache
$questionnaire->setCacheEnabled(true);
if ($questionnaire->load('456sdfa')) {
    // Access questionnaire data
    $questionnaireModel = $questionnaire->getQuestionnaire();
}

反馈

这是一个用于调用 e-satisfaction API 的开源库。

请随意提出问题和拉取请求以更新它或修复您可能发现的错误。

行为准则指南

查看行为准则文档。

esatisfaction / esat-php

维护者

详细信息