README

A PHP wrapper for the University of Waterloo's Open Data API supporting asynchronous requests through Guzzle.

This library requires PHP 7.0 or greater.

安装

使用 Composer 安装客户端。

全局安装：

composer require hkwu/uwapi-php

本地安装：

php composer.phar require hkwu/uwapi-php

用法

所有请求方法都封装在库的 Client 类中。

<?php

// require the Composer autoloader
require __DIR__.'/vendor/autoload.php';

use UWaterlooAPI\Client;
use UWaterlooAPI\Endpoints;

// make a client
$client = new Client([
    'key' => '6b9e30736f2c741ee02c431dc1cf68b0', // your API key
]);

// change some client configuration options
// setConfig() will merge the provided options into the existing client configuration
$client->setConfig([
    'format' => Client::XML,
]);

Client 构造函数接受的配置选项如下。

发送请求

Client 类提供了一个 request() 方法，用于向API发送请求。

/**
 * MAKE A REQUEST
 * 
 * By default, requests are asynchronous and return promises.
 */
$promise = $client->request(Endpoints::FS_MENU); // request constants are available in the Endpoints class
$promise->then(
    function ($model) { // the success callback will receive an APIModel object
        echo $model->getMeta()['message'].PHP_EOL;
    },
    function ($error) { // the error callback will receive a Guzzle RequestException
        echo $error->getMessage().PHP_EOL;
    }
);

/**
 * PARAMETERIZED REQUESTS
 *
 * Some endpoints are parameterized and require a second argument 
 *   to be supplied to request().
 */
$promise = $client->request(Endpoints::BLOGS_SITE_ID, [
    'site' => 'student-success',
    'id' => 7721,
]);

/**
 * FORMATTING ENDPOINT STRINGS
 *
 * If you don't want to use the provided request constants,
 *   you can provide a string which will be formatted by the client.
 */
$promise = $client->request('news/{myParam1}/{myParam2}', [
    'myParam1' => 'student-success',
    'myParam2' => 7721,
]);

/**
 * OVERRIDING THE CLIENT CONFIGURATION
 *
 * You can also override client config options on a per-request 
 *   basis by supplying a third argument to request().
 */
$model = $client->request(
    Endpoints::BLOGS_SITE_ID, 
    [
        'site' => 'student-success',
        'id' => 7721,
    ], 
    [
        'async' => false, // make this request synchronous
    ]
);

您可以使用 batch() 方法一次性发送多个请求。

/**
 * SPECIFY ENDPOINTS
 *
 * Array containing endpoints to send requests to the
 *   keys are optional, an indexed array works as well.
 */
$endpoints = [
    'menu' => Endpoints::FS_MENU,
    'events' => Endpoints::EVENTS_SITE_ID,
    'news' => Endpoints::NEWS_SITE_ID,
];

/**
 * SPECIFY PARAMETERS
 *
 * The parameters for each endpoint request.
 * The keys here should match the ones specified in $endpoints.
 * For endpoints requiring no parameters, you may simply omit their key.
 */
$params = [
    'events' => [
        'site' => 'engineering',
        'id' => 1701,
    ],
    'news' => [
        'site' => 'science',
        'id' => 881,
    ],
];

/**
 * SPECIFY OPTIONS
 *
 * Options that affect the entire batch of requests.
 * Only the 'format' option will be accepted here.
 */
$options = [
    'format' => Client::XML,
];

/**
 * MAKE THE REQUESTS
 *
 * Returns an array of APIModels where each key corresponds
 *   to the keys provided in $endpoints.
 * Both $params and $options are optional.
 */
$models = $client->batch($endpoints, $params, $options);

访问响应数据

API返回的响应封装在数据模型类中。所有数据模型都提供了 getRawData() 方法，该方法返回API响应的字符串。

JSON（以及扩展的GeoJSON）数据模型提供了一些额外的便捷方法。

$jsonModel = $client->request(Endpoints::FS_MENU, [], [
    'format' => Client::JSON,
    'async' => false,
]);

$jsonModel->getDecodedData(); // json_decodes the response into an array
$jsonModel->getMeta(); // equivalent to $jsonModel->getDecodedData()['meta']
$jsonModel->getData(); // equivalent to $jsonModel->getDecodedData()['data']

// equivalent to $jsonModel->getDecodedData()['data']['date']['year']
$jsonModel->get('data', 'date', 'year');

端点

库提供了一些常量，用于发送请求。其中大多数常量直接来自API文档中提供的端点，但一些已被调整以更易于使用。

贡献

请随时为任何更改提交拉取请求。

几点注意事项

• 为新功能添加单元测试。
  • 您可以使用项目根目录下的 vendor/bin/phpunit 运行整个测试套件。
• 遵循 PSR-1 和 PSR-2 风格指南。