README

LimeSurvey API的客户端。

安装

运行Composer以将此包安装到您的项目中

$ composer require meritoo/limesurvey-api-client

如何安装Composer: https://getcomposer.org.cn/download

LimeSurvey配置

1. 登录到LimeSurvey管理，例如使用https://your-domain/admin地址
2. 转到菜单：配置 -> 全局设置
3. 打开接口标签
4. 对于启用RPC接口选择JSON-RPC选项
5. 启用在/admin/remotecontrol上发布API选项

它应该看起来像这里：更多信息：https://manual.limesurvey.org/RemoteControl_2_API#Introduction

用法

1. 首先，您需要准备连接配置并创建客户端实例

   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. 然后运行您想要的方法

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

3. 最后从调用方法的返回结果中获取数据

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

此示例的完整代码

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

可用方法

所有可用方法都提供了Meritoo\LimeSurvey\ApiClient\Type\MethodType类的常量。示例

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

方法的名称，实际上是MethodType类的常量，您应该将其作为\Meritoo\LimeSurvey\ApiClient\Client\Client::run()方法的第一个参数传递。示例

$client->run(MethodType::GET_PARTICIPANT_PROPERTIES);

调试模式

在某些情况下，可能需要更多信息来修复错误。调试模式将帮助您做到这一点。您可以通过将true作为构造函数的第四个参数传递来在准备连接配置时打开它

use Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration;
$configuration = new ConnectionConfiguration('http://test.com', 'test', 'test', true);

如果配置实例存在，可以使用\Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration::setDebugMode()方法打开调试模式

$configuration->setDebugMode(true);

如果您想检查是否打开了“调试”模式，只需调用\Meritoo\LimeSurvey\ApiClient\Configuration\ConnectionConfiguration::isDebugModeOn()方法即可

$debugMode = $configuration->isDebugModeOn();

从结果获取数据

验证结果是否为空

首先，您必须调用所需的方法以获取结果 - \Meritoo\LimeSurvey\ApiClient\Result\Result类的实例。该结果允许您通过调用\Meritoo\LimeSurvey\ApiClient\Result\Result::isEmpty()方法来获取有关是否存在任何数据的信息

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)

准备/处理的数据与原始数据

结果允许您通过调用\Meritoo\LimeSurvey\ApiClient\Result\Result::getData()方法来获取数据，这是调用API方法的本质。此方法接受一个布尔参数

• false - (默认) 将返回准备/处理的数据
• true - 将返回原始数据

准备/处理的数据意味着来自Meritoo\LimeSurvey\ApiClient\Result\Item\*命名空间的类实例。

注意。

1. 如果API提供的返回结果是可迭代的，则上述内容为真。否则，将返回单个项的实例。
2. 提供可迭代结果的方法

• MethodType::LIST_PARTICIPANTS
• MethodType::LIST_QUESTIONS
• MethodType::LIST_SURVEYS
• MethodType::LIST_USERS

它们在Meritoo\LimeSurvey\ApiClient\Type\MethodType::isResultIterable()方法中定义。

准备/处理的数据

所有实例都以集合（Meritoo\Common\Collection\Collection类的实例）的元素形式返回。示例

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

如果API提供的结果如上所述不可迭代，则返回单个项目的实例。示例

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"
  (...)
}

原始数据

一个包含标量或其它数组的数组。示例

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

链接

• LimeSurvey: https://www.limesurvey.org
• Composer: https://getcomposer.org.cn

享受吧！