Meritoo LimeSurvey API Client

Installation

Run Composer to install this package in your project:

```bash
$ composer require meritoo/limesurvey-api-client
```

How to install Composer: https://getcomposer.org/download

Usage

First of all you have to prepare configuration of connection and create instance of a client:

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);

Next run the method which you would like:

/*
 * Run required method
 */
$result = $client->run(MethodType::LIST_SURVEYS);

Finally grab data from result of called method:

/*
 * ...and grab data from the result
 */
$data = $result->getData();

Full code of this example:

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:

// 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:

$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:

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:

$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:

$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:

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.

The above is true, if result provided by the API is iterable. Otherwise - instance of single item is returned.

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:

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:

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:

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"
  }
}

mplattner / limesurvey-api-client