README

A PHP client for the D2L Brightspace REST API, built for the scripts CETLOE runs against Georgia State's Brightspace instance. See D2L's API documentation for the endpoints themselves.

What it does

Most of the work in this library is getting authenticated. Brightspace wants an OAuth2 bearer token on API calls, and getting that token normally means a person clicking through a browser consent screen. This library does that part without a browser:

Posts your username and password to the Brightspace login form.
Answers the MFA prompt with a TOTP code generated from your MFA key, if the account has MFA turned on.
Uses the resulting login cookie to walk the OAuth2 authorization-code flow (with PKCE) and trade the code for an access token and refresh token.
Writes both tokens to JSON files and refreshes the access token when it expires.

Once a token file exists, later runs skip the login entirely until the refresh token stops working.

On top of that there are small typed wrappers for a few API areas:

Users: whoami, list, get, create, update, delete.
Org units: org info, org unit types, ancestors and descendants, add and remove parent and child links.
Data Hub: list Brightspace Data Sets, list extracts, download an extract.
Outcomes: look up a registry, read it, import objectives.

Each wrapper is a class that extends the base client and returns model objects instead of raw arrays. Anything not wrapped yet you can call through the base client's request methods.

Requirements

PHP 8.1 or later
A PSR-18 HTTP client and PSR-17 request factory (the example scripts use Guzzle)
A Brightspace account with API access, and an OAuth2 app registered in Brightspace with a client ID, secret, and redirect URI

Installation

composer require gsu-cetloe/d2l-api-php

Configuration

Configuration comes from environment variables, or from an array with the same keys in camel case. The variables are:

Variable	Purpose
`D2L_HOST`	Base URL of your Brightspace instance, such as `https://example.brightspace.com`
`D2L_USER`	Login username
`D2L_PASS`	Login password
`D2L_MFA_KEY`	TOTP secret for the account. Leave unset if MFA is off.
`D2L_LP_VERSION`	Learning Platform API version. Defaults to 1.44.
`D2L_LE_VERSION`	Learning Environment API version. Defaults to 1.71.
`D2L_LOGIN_TOKEN_PATH`	Where to cache the login cookie
`D2L_OAUTH_TOKEN_PATH`	Where to cache the OAuth tokens
`D2L_OAUTH_CLIENT_ID`	OAuth2 client ID
`D2L_OAUTH_CLIENT_SECRET`	OAuth2 client secret
`D2L_OAUTH_REDIRECT_URI`	OAuth2 redirect URI registered with the app
`D2L_OAUTH_SCOPE`	Space-separated OAuth2 scopes, such as `core::`
`D2L_OAUTH_AUTH_CODE_URL`	Defaults to D2L's hosted auth endpoint
`D2L_OAUTH_ACCESS_TOKEN_URL`	Defaults to D2L's hosted token endpoint

The token files hold live credentials. Keep them out of version control and out of shared directories.

Usage

The shortest path is to build a config, then hand it and your HTTP client to the API wrapper you need. The test helper in TestEnv.php shows all the wiring; a trimmed version looks like this:

use GSU\D2L\API\D2LAPIConfig;
use GSU\D2L\API\Users\UsersAPI;

$config = D2LAPIConfig::create($env);

$users = new UsersAPI(
    $config,
    $loginTokenStore,
    $oauthTokenStore,
    $requestFactory,
    $httpClient
);

$me = $users->whoami();

If you use the cetloelib-php container, D2LAPIDefinitionSource registers the config from the environment and pulls in the HTTP client definitions.

A runnable example lives in tests/scripts/test.example.php. Copy config.example.php next to it, fill in your values, and run it.

Development

composer install
composer phpunit
composer phpstan
composer phpcs

PHPStan runs at level 9 and the code style rules are in phpcs.xml. The PHPUnit tests run against a mocked HTTP client with the fixture tokens in tests/work, so they need no Brightspace access.

License

MIT. See LICENSE.md.

gsu-cetloe / d2l-api-php

Package info

Security

Statistics