README

A PHP library to interact with the Ellucian Ethos API.

Installation

composer require melonsmasher/ethos-php

API Docs

Complete API docs can be found here.

Features

As of now ethos-php has support for 316 models/routes. It supports nearly all Banner & Colleague models with the following feature set.

A fluent API allowing for methods to be chained to improve readability.
Convenience methods that return the response data as an object: data(), as an array: toArray(), and as a JSON string: toJson().
Simple control over API pagination. Max ten items returned per-page.
Automatic re-authentication when a session expires.
Support for Banner and Colleague backends.
Automatically versioned API calls.
Control over request params and headers.
Class level awareness of Ethos CRUD support.
Support for ID based routes. E.G. /api/persons/35b16136-bafd-4b5d-9dd2-995ad9f4ba00
Support for the /consume subscription message queue route.

Features To Come

Support for the /publish subscription message queue route.

Usage/Examples

The example below demonstrates the fluent API, convenience methods, and control over pagination.

<?php

include_once 'vendor/autoload.php';

use MelonSmasher\EthosPHP\EthosClient;
use MelonSmasher\EthosPHP\Foundation\PersonsClient;

// Your API Key / Refresh Token
$secret = 'YourApiKey/RefreshToken';
// Create an authenticated Ethos session
$ethos = EthosClient::createSession($secret);
// Create a new Persons client using your Ethos session
$personsClient = new PersonsClient($ethos);
// Read the first page of persons
$page1 = $personsClient->read()->data();
// Move to the next page
$personsClient->nextPage();
// Read the second page
$page2 = $personsClient->read()->data();
// Set the page to the fourth page
$personsClient->setPage(4);
// Read the 4th page to an array
$page4 = $personsClient->read()->toArray();
// Move 1 page back to the 3rd
$personsClient->backPage();
// Read the 3rd page to a JSON string
$page3 = $personsClient->read()->toJson();
// Skip to the 6th page
$personsClient->nextPage(4);
// Read the 7th page
$page7 = $personsClient->read()->data();
// Skip back to the 5th page
$personsClient->backPage(2);
// Read the 5th page
$page5 = $personsClient->read()->data();

The example below demonstrates the ability to provide custom request parameters.

<?php

include_once 'vendor/autoload.php';

use MelonSmasher\EthosPHP\EthosClient;
use MelonSmasher\EthosPHP\Foundation\PersonsClient;

// Your API Key / Refresh Token
$secret = 'YourApiKey/RefreshToken';
// Create an authenticated Ethos session
$ethos = EthosClient::createSession($secret);
// Create a new Persons client using your Ethos session
$personsClient = new PersonsClient($ethos);
// Send a request with the `criteria` parameter filtering for a person with a colleaguePersonId of 9000001.
$data = $personsClient->read([
    'criteria' => '{"credentials":[{"type":"colleaguePersonId","value":"9000001"}]}'
])->data();

Dev Setup

Install PHIVE

Install build tools

phive install

Install composer requirements

./composer install

melonsmasher / ethos-php

Maintainers

Details