PHP library for the e-satisfaction API
PHP 7.1.0 and later.
You can install the bindings via Composer. Run the following command:
composer require esatisfaction/esat-php
To use the bindings, use Composer's autoload:
require_once('vendor/autoload.php');
If you do not wish to use Composer, you can download the latest release. Then, to use the bindings, include the init.php
file.
require_once('/path/to/esatisfaction-php/init.php');
This library require the following extensions and packages in order to work properly:
panda/config
panda/helpers
ramsey/uuid
symfony/http-foundation
monolog/monolog
php-http/guzzle6-adapter
esatisfaction/http
symfony/cache
If you use Composer, these dependencies should be handled automatically. If you install manually, you'll want to make sure that these extensions are available and loaded.
To start working with the SDK, you have to initialize the following:
- Setup the main Esat Registry
- Set the Authorization Scheme to be used by each service's HttpClient
Example:
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();
Read your questionnaires:
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();
}
Create a questionnaire instance and send the link to your customers:
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' => '[email protected]',
'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
}
Read, Update or Delete Questionnaire Instances:
NOTICE: This will cause data deletion and might alter your data. It will not affect your credits as the credits are reduced on questionnaire submit.
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;
}
Read your pipelines:
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();
}
Add a queue item to allow e-satisfaction to send a survey:
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' => '[email protected]',
'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;
}
Read, Update or Delete Queue Items:
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;
}
Each request stores the last response so that you can access it and get messages in case of errors.
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;
}
This library is using a default runtime caching mechanism that reduces API calls during runtime.
The caching mechanism is on service level and works only on READ requests and is being reset when a POST or PATCH method is called on the same service.
If you are trying to READ the same resource twice without any updates in between, the service will hit the cache and get the same result.
You can override the cache by calling setCacheEnabled(false)
on the service before calling the method.
Examples:
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();
}
This is an open-source library for calling e-satisfaction API.
Feel free to open Issues and Pull Requests to update it or fix bugs that you might find.
Take a look at the Code of Conduct document.