mirror of
https://github.com/wiosna-dev/limesurvey-api-client.git
synced 2026-03-12 02:11:45 +01:00
254 lines
7.7 KiB
Markdown
254 lines
7.7 KiB
Markdown
# Meritoo LimeSurvey API Client
|
|
Client of the [LimeSurvey's API](https://manual.limesurvey.org/RemoteControl_2_API).
|
|
|
|
[](https://travis-ci.org/meritoo/limesurvey-api-client) [](https://packagist.org/packages/meritoo/limesurvey-api-client) [](https://styleci.io/repos/104114960) [](https://github.com/meritoo/limesurvey-api-client) [](https://github.com/meritoo/limesurvey-api-client) [](https://coveralls.io/github/meritoo/limesurvey-api-client?branch=master)
|
|
|
|
## Installation
|
|
|
|
Run [Composer](https://getcomposer.org) to install this package in your project:
|
|
|
|
```bash
|
|
$ composer require meritoo/limesurvey-api-client
|
|
```
|
|
|
|
> How to install Composer: https://getcomposer.org/download
|
|
|
|
## Configuration of LimeSurvey
|
|
|
|
1. Login to the LimeSurvey administration, e.g. using https://your-domain/admin address
|
|
2. Go to menu: `Configuration` -> `Global settings`
|
|
3. Open `Interfaces` tab
|
|
4. For `RPC interface enabled` select `JSON-RPC` option
|
|
5. Enable `Publish API on /admin/remotecontrol` option
|
|
|
|
It should look like here:
|
|
|
|
More information: https://manual.limesurvey.org/RemoteControl_2_API#Introduction
|
|
|
|
## Usage
|
|
|
|
1. First of all you have to prepare configuration of connection and create instance of a client:
|
|
|
|
```php
|
|
use Meritoo\LimeSurvey\ApiClient\Client\Client;
|
|
use Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration;
|
|
use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
|
|
|
|
/*
|
|
* Prepare configuration of connection and client of the API
|
|
*/
|
|
$configuration = new ConnectionConfiguration('http://test.com', 'test', 'test');
|
|
$client = new Client($configuration);
|
|
```
|
|
|
|
2. Next run the method which you would like:
|
|
|
|
```php
|
|
/*
|
|
* Run required method
|
|
*/
|
|
$result = $client->run(MethodType::LIST_SURVEYS);
|
|
```
|
|
|
|
3. Finally grab data from result of called method:
|
|
|
|
```php
|
|
/*
|
|
* ...and grab data from the result
|
|
*/
|
|
$data = $result->getData();
|
|
```
|
|
|
|
Full code of this example:
|
|
|
|
```php
|
|
use Meritoo\LimeSurvey\ApiClient\Client\Client;
|
|
use Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration;
|
|
use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
|
|
|
|
/*
|
|
* Prepare configuration of connection and client of the API
|
|
*/
|
|
$configuration = new ConnectionConfiguration('http://test.com', 'test', 'test');
|
|
$client = new Client($configuration);
|
|
|
|
/*
|
|
* Run required method and grab data from the result
|
|
*/
|
|
$result = $client->run(MethodType::LIST_SURVEYS);
|
|
$data = $result->getData();
|
|
```
|
|
|
|
## Available methods
|
|
|
|
All available methods provides `Meritoo\LimeSurvey\ApiClient\Type\MethodType` class as constants of the class. Examples:
|
|
|
|
```php
|
|
// Add a response to the survey responses collection
|
|
MethodType::ADD_RESPONSE;
|
|
|
|
// The IDs and properties of token/participants of a survey
|
|
MethodType::LIST_PARTICIPANTS;
|
|
|
|
// List the surveys belonging to a user
|
|
MethodType::LIST_SURVEYS;
|
|
```
|
|
|
|
Name of the method, actually constant of the `MethodType` class, you should pass as 1st argument of `\Meritoo\LimeSurvey\ApiClient\Client\Client::run()` method. Example:
|
|
|
|
```php
|
|
$client->run(MethodType::GET_PARTICIPANT_PROPERTIES);
|
|
```
|
|
|
|
## Debug mode
|
|
|
|
In some cases more information may be required to fix bugs. The "debug" mode will help you do this. You can turn it on while preparing configuration of connection by passing `true` as 4th argument of constructor:
|
|
|
|
```php
|
|
use Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration;
|
|
$configuration = new ConnectionConfiguration('http://test.com', 'test', 'test', true);
|
|
```
|
|
|
|
The "debug" mode can be turned on if the instance of configuration exists by using the `\Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration::setDebugMode()` method:
|
|
|
|
```php
|
|
$configuration->setDebugMode(true);
|
|
```
|
|
|
|
If you want to verify if if the "debug" mode is turned on simply call the `\Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration::isDebugModeOn()` method:
|
|
|
|
```php
|
|
$debugMode = $configuration->isDebugModeOn();
|
|
```
|
|
|
|
## Getting data from result
|
|
|
|
#### Verify if the result is empty
|
|
|
|
First of all you have to call required method to get result - instance of `\Meritoo\LimeSurvey\ApiClient\Result\Result` class. The result allows you to get information if there is any data by calling the `\Meritoo\LimeSurvey\ApiClient\Result\Result::isEmpty()` method:
|
|
|
|
```php
|
|
use Meritoo\LimeSurvey\ApiClient\Result\Result;
|
|
use Meritoo\LimeSurvey\ApiClient\Type\MethodType;
|
|
|
|
$result = new Result(MethodType::LIST_SURVEYS, []);
|
|
$isEmpty = $result->isEmpty();
|
|
|
|
var_dump($isEmpty); // bool(true)
|
|
```
|
|
|
|
#### Prepared/processed vs raw data
|
|
|
|
Result allows you to get data, the essence of calling API's method by calling the `\Meritoo\LimeSurvey\ApiClient\Result\Result::getData()` method. This method accepts 1 bool argument:
|
|
- `false` - (default) prepared/processed data provided will be returned
|
|
- `true` - raw data will be returned
|
|
|
|
Prepared/processed data means instances of classes from `Meritoo\LimeSurvey\ApiClient\Result\Item\*` namespace.
|
|
|
|
> Attention.
|
|
> 1. The above is true, if result provided by the API *is iterable*. Otherwise - instance of single item is returned.
|
|
> 2. Methods that provides iterable result:
|
|
>
|
|
> - MethodType::LIST_PARTICIPANTS
|
|
> - MethodType::LIST_QUESTIONS
|
|
> - MethodType::LIST_SURVEYS
|
|
> - MethodType::LIST_USERS
|
|
>
|
|
> They are defined in `Meritoo\LimeSurvey\ApiClient\Type\MethodType::isResultIterable()` method.
|
|
|
|
#### Prepared/processed data
|
|
|
|
All instances are returned as elements of collection (instance of `Meritoo\Common\Collection\Collection` class). Example:
|
|
|
|
```php
|
|
class Meritoo\Common\Collection\Collection#565 (1) {
|
|
private $elements =>
|
|
array(2) {
|
|
[0] =>
|
|
class Meritoo\LimeSurvey\ApiClient\Result\Item\Survey#564 (5) {
|
|
private $id =>
|
|
int(456)
|
|
private $title =>
|
|
string(12) "Another Test"
|
|
private $expiresAt =>
|
|
NULL
|
|
private $active =>
|
|
bool(true)
|
|
}
|
|
[1] =>
|
|
class Meritoo\LimeSurvey\ApiClient\Result\Item\Survey#564 (5) {
|
|
private $id =>
|
|
int(456)
|
|
private $title =>
|
|
string(12) "Another Test"
|
|
private $expiresAt =>
|
|
NULL
|
|
private $active =>
|
|
bool(true)
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
If result provided by the API *is not iterable*, as mentioned above, instance of single item is returned. Example:
|
|
|
|
```php
|
|
class Meritoo\LimeSurvey\ApiClient\Result\Item\Participant#701 (17) {
|
|
private $id =>
|
|
int(123)
|
|
private $participantId =>
|
|
int(456)
|
|
private $mpId =>
|
|
NULL
|
|
private $firstName =>
|
|
string(5) "Lorem"
|
|
private $lastName =>
|
|
string(5) "Ipsum"
|
|
(...)
|
|
}
|
|
```
|
|
|
|
#### Raw data
|
|
|
|
An array with scalars or other arrays. Example:
|
|
|
|
```php
|
|
array(2) {
|
|
[0] =>
|
|
array(5) {
|
|
'sid' =>
|
|
string(3) "123"
|
|
'surveyls_title' =>
|
|
string(4) "Test"
|
|
'startdate' =>
|
|
NULL
|
|
'expires' =>
|
|
string(19) "2017-09-19 13:02:41"
|
|
'active' =>
|
|
string(1) "N"
|
|
}
|
|
[1] =>
|
|
array(5) {
|
|
'sid' =>
|
|
string(3) "456"
|
|
'surveyls_title' =>
|
|
string(12) "Another Test"
|
|
'startdate' =>
|
|
string(19) "2017-09-19 13:02:41"
|
|
'expires' =>
|
|
NULL
|
|
'active' =>
|
|
string(1) "Y"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Links
|
|
|
|
- LimeSurvey:
|
|
https://www.limesurvey.org
|
|
- Composer:
|
|
https://getcomposer.org
|
|
|
|
Enjoy!
|