hkwu/uwapi-php

PHP wrapper for the University of Waterloo's Open Data API.

uwapi-php

, _(*1)

A PHP wrapper for the University of Waterloo's Open Data API supporting asynchronous requests through Guzzle., _(*2)

This library requires PHP 7.0 or greater., _(*3)

Installation

Install the client via Composer., _(*4)

For global installations,, _(*5)

composer require hkwu/uwapi-php

For local installations,, _(*6)

php composer.phar require hkwu/uwapi-php

Usage

All request methods are wrapped inside the library's Client class., _(*7)

<?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., _(*8)

Making Requests

The Client class comes with the request() method for sending requests to the API., _(*9)

/**
 * 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., _(*10)

/**
 * 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., _(*11)

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

$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., _(*13)

Contributing

Feel free to make pull requests for any changes., _(*14)

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., _(*15)