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.

Installation

Install the client via Composer.

For global installations,

composer require hkwu/uwapi-php

For local installations,

php composer.phar require hkwu/uwapi-php

Usage

All request methods are wrapped inside the library's Client class.

<?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,
]);

The configuration options the Client constructor takes are listed below.

Making Requests

The Client class comes with the request() method for sending requests to the 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
    ]
);

You can send several requests all at once by using the batch() method.

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

Accessing Response Data

Returned responses from the API are wrapped in data model classes. All data models provide the getRawData() method, which returns the API response as a string.

The JSON (and by extension, GeoJSON) data models provide some additional convenience methods.

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

Endpoints

The library provides a number of constants to use when making requests. Most of these constants follow directly from the endpoints as provided in the API documentation, but a few have been tweaked to be more usable.

Contributing

Feel free to make pull requests for any changes.

Just a couple of things:

Add unit tests for any new functionality.
- You can run the entire test suite using vendor/bin/phpunit from the project root.
Follow the PSR-1 and PSR-2 style guides.

hkwu / uwapi-php

Maintainers

Details