README

使用 PHP 与 WCEA REST API 进行通信

使用 Composer 安装

如果您使用 Composer 来管理依赖项，您可以将其与 WCEA SDK 一起添加。

{
  "require" : {
    "wcealliance/php-sdk": "dev-master"
  },
  "minimum-stability": "dev"
}

从 GitHub 安装源代码

WCEA SDK 需要作为依赖项的 Unirest。它还需要 PHP v5.3+ 和 cURL 扩展。从 Github 下载 PHP 库，并在脚本中按如下方式引入：

安装源代码

$ git clone git@github.com:wcealliance/php-sdk.git

并将其包含在您的脚本中

// first include Unirest
require_once '/path/to/unirest-php/lib/Unirest.php';
// then include this
require_once '/path/to/php-sdk/lib/WCEAAPI.php';

##使用方法 运行此 SDK 的主要要求是 api_key 和 api_secret。在您继续之前，请确保您拥有它们。

可以通过在类实例化期间发送配置数组以多种方式配置该类

// create a new instance
$config_array = array(
  "api_endpoint"   => "http://wceaapi.org",
  "api_key"        => 'YOUR_API_KEY',
  "api_secret"     => 'YOUR_API_SECRET',
  "api_version"    => '1.1'
);
$api = new WCEAAPI($config_array);

或者使用更面向对象的策略

$api = new WCEAAPI();
$api->setKey('YOUR_API_KEY')
  ->setSecret('YOUR_API_SECRET')
  ->setConfig('api_version', '1.1');

除了 api_key 和 api_secret 之外的配置参数都有设置器和获取器方法

// set a config param
$api->setConfig('api_version', '1.1');
// get a config param
$version = $api->getConfig('api_version');

请注意：默认情况下，api_endpoint 参数设置为实时 URL，要使用沙盒模式，请使用沙盒 URL http://sandbox.wceaapi.org。

对 API 资源进行 REST 调用

有关可用的 API 资源端点的列表，请参阅 WCEA API 文档。该类使用 __call() 魔法方法来确定您正在调用的资源。

例如

// make a GET request to /user/user@email.com
$user = $api->getUser('user@email.com');
// make a POST request to /user
$user = $api->addUser(array('post_params'));
// make a PUT request to /user/user@email.com
$api->editUser('user@email.com', array('post_params'));
// make a DELETE request to /user/user@email.com
$api->deleteUser('user@email.com');

调用子资源遵循类似的 camelCased 模式，例如

// make a GET request to /user/user@email.com/trainingProfile/
$training_profile = $api->getUserTrainingProfile('user@email.com');

简单来说

• getXXX() 映射到 GET 请求
• addXXX() 映射到 POST 请求
• editXXX() 映射到 PUT 请求
• deleteXXX() 映射到 DELETE 请求

输出数据 & 错误处理

SDK 中的所有数据都是纯 PHP 数组。如果方法调用失败，输出为 false。

如果您遇到查询返回 false 的结果，则可以从 getError() 方法中获取发生的错误。

以下是一个非常简单的容错代码示例

$user = $api->getUser('user@email.com');
if ($user == false) {
  $error = $api->getError();
  if($error){
    throw new Exception($error['errorCode'] . $error['userMessage']);
  }
} else {
  //loop through the returned data
  //and do something with it
}

当调用 PUT 和 POST 端点（addXXXX() 和 editXXXX()）时，如果有效负载包含无效数据，则数据验证消息将以错误对象中数组的表单出现

array(
  'errorCode'   => '400',
  'userMessage' => 'Bad Request',
  'devMessage'  => array(
      'email'   => 'Invalid email address'
  )
)

响应元数据

除了特殊的获取器 getError() 之外，还有一个用于元数据的获取器方法。 getMetadata() 返回一个包含所有随响应发送的元数据的数组。

元数据通常包含响应状态、偏移/限制值和返回的总记录数。它还包含可利用于分页长列表的 HATEOAS 链接。

要仅获取 HATEOAS 链接，可以使用另一个特殊获取器 getLinks()。它只返回响应中的 HATEOAS 链接。