Our PHP client library SDK is currently in experimental form and available only as source.
Installation¶
You can find the latest source releases for the PHP client library SDK in our GitHub repository.
Dependencies. In order to use the PHP client library SDK, you’ll need to first ensure you have a working PHP development environment:
PHP 5.x (the reference environment uses 5.3) including the Client URL library.
Web server with permissions letting you put the library and sample files where the server can locate and load them.
Authentication API¶
The library provides a helper API you can use to make it easier to create authenticated URLs for REST API invocations. In general, there are three kinds of REST API routes:
Those that require an authenticated calling user context (the overwhelming majority) must be decorated by tokens that indicate the application making the request and the logged-in user context for the request (i.e. the logged-in user on behalf of which the client application is acting). (Note that because of the way our authentication system works, a calling user context also implies an application context.)
Those that require only an authenticated application context must be decorated by tokens that indicate the application making the request (but not a particular person with a back-end service user account). Typically these routes include only those that can gather general property information about the LMS API itself.
The authentication entry point route that a client application must use to start the process for establishing a user context.
In the typical work-flow with this API, the client application should start by creating a new application context with its App ID and App Key. Then, the client application can use this application context to initiate user authentication for an LMS user, and then handle the results of that user authentication process to create a calling user context for that logged-in user. Finally, the client application can use the created calling user context to properly decorate API queries with the authentication tokens that signal the user context to the back-end service.
API Reference¶
- interface ID2LAppContext¶
Interface for an application context object that a client application uses to create an application-specific calling context for use with a Learning Framework service.
To retrieve the default library-provided implementation of an application context, the client should invoke
createSecurityContexton the app context factory class.New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.
- createUrlForAuthentication($host, $port, $resultUri)¶
Retrieve a URL the client can use to initiate the authentication process with the back-end service.
- Parameters
host (
string) – Host name for the back-end service.port (
string) – Port the service uses for route requests.resultUri (
string) – Client-application-handled callback URI.
- Returns
URL the client can pass to a web control to initiate user authentication.
- Return type
String.
The client application will use the URL retrieved from this method by passing it to a web control or browser to let the user authenticate with the back-end service. The resultUri provided to this call is a callback URI that the client application will handle: when the back-end service finishes the user-auth process, it will redirect back to this URI, including the User ID and User Key tokens as quoted parameters.
- createUserContext($host, $port, $encryptOperations, $userId=null, $userKey=null, $callbackUri=null)¶
Build a new authenticated-user context the client application can use to create decorated URLs for invoking routes on the back-end service API.
- Parameters
host (
string) – Host name for the back-end service.port (
string) – Port the service uses for route requests.encryptOperations (
boolean) – If true, build context with HTTPS; otherwise, use HTTP.userId (
string) – (Optional, null default) Service-provided ID for user.UserKey (
string) – (Optional, null default) Service-provided Key for user, to sign with.callbackUri (
string) – (Optional, null default) Entire result URI service sent back with redirect after user auth.
- Returns
A new user context for creating user-authenticated URLs for API calls.
- Return type
Object implementing
ID2LUserContext.
An application context instance can create a user context in several modes:
If the client application already knows an authenticated user context’s state (host, port, user ID, user Key) then it can rebuild a user context for making authenticated calls.
If this application context implementation has just initiated the auth process with the back-end service, and now has a result URI to handle, the caller can provide that result URI and this method can parse the needed user context state out of it to build a new user context.
If the caller wants to use one of the API routes that doesn’t require an authenticated calling user context, it can leave userId, userKey, and callbackUri parameters as null to build a “default user” context.
- interface ID2LUserContext¶
Interface for a user context object that a client application uses to craft URLs for calling REST API routes, signalling the authenticated calling user context.
To retrieve an implementation, the client should invoke
createUserContexton a concrete application context instance.New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.
- createAuthenticatedUrl($path, $httpMethod)¶
Retrieve an appropriately decorated URI for invoking a REST route on the back-end service.
- Parameters
path (
string) – REST route for the action to invoke.httpMethod (
string) – HTTP method to use with the route for the action (DELETE, GET, POST, or PUT)
- Returns
Decorated URI usable to invoke the REST API action for the method and path.
- Return type
String.
- calcualteServerSkewFromResponse($responseBody)¶
Calculate the clock skew between the local clock and the back-end service clock, based on an HTTP response body sent by the service.
- Parameters
responseBody (
string) – HTTP response body for the timestamp out of range messaged response.
- Returns
True if this method successfully recalculates the clock skew; otherwise, false.
- Return type
Boolean.
If the back-end service sends back a 403 with the timestamp out of range message, the client application can use this method to re-calculate the user context’s cached server skew value.
- handleResult($response, $httpCode, $contentType)¶
Interpret an HTTP response from the back-end service in response to an API call.
- Parameters
response (
string) – Response body sent by the back-end service in response to a Learning Framework API call.httpCode (
string) – HTTP code associated with the response (i.e. 200, 403, etc).contentType (
string) – Response content-type.
- Returns
Numeric constant the caller can use to determine what the next action might be.
- Return type
Integer.
This method does two things:
Given a response from the back-end service, it can do a simple parse and return a numeric value (one of the RESULT_* constant values in the D2LUserContext default implementation) indicating what the caller might need to do next (re-authenticate the user, verify that the user has permissions to attempt the action taken, and so forth).
Most commonly, applications will minimally want to check for
RESULT_OKAYin order to proceed with interpreting result data sent back by the API call.If the response from the back-end service indicates that the service’s clock offset is outside an allowable range, this method re-calculates the clock offset and saves it in the user context’s state.
- getHostName()¶
- Returns
Back-end service’s host name for this calling user context.
- Return type
String.
- getPort()¶
- Returns
Port that the back-end service exposes for API calls.
- Return type
String.
- getUserId()¶
- Returns
Service-provided User ID for this calling user context.
- Return type
String.
- getUserKey()¶
- Returns
Service-provided User Key for this calling user context.
- Return type
String.
- getServerSkewSeconds()¶
- Returns
Currently known time-skew between the local and back-end service clocks.
- Return type
Integer.
- setServerSkewSeconds($seconds)¶
- Parameters
seconds (
integer) – New time-skew between local and back-end service clocks, in seconds.
- class D2LAppContextFactory¶
Factory class to build default application context implementation instances.
New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.
- createSecurityContext($appId, $appKey)¶
Build and pass back a new calling application context.
- Parameters
appId (
string) – Application ID, as provided by the Brightspace Manage Extensibility tool.appKey (
string) – Application Key for signing, as provided by the Brightspace Manage Extensibility tool.
- Returns
A new application context for creating calling user contexts.
- Return type
Object implementing
ID2LAppContext.
- class D2LUserContext¶
The relevant elements of this default
ID2LUserContextimplementation in the public API are the various RESULT_* reference constants for mapping API results to generic result types. Non-default user context implementations should also provide these constant values.New in version 1.0: Initial version of the PHP client library, compatible with LMS v9.4.1.
- constant RESULT_UNKNOWN¶
No result can be identified; also useful as an uninitialized value.
- constant RESULT_OKAY¶
Server has provided a result 200 OK response.
- constant RESULT_INVALID_SIG¶
Invalid signature or context ID (app or user); typically this should prompt the client application to attempt re-authentication.
- constant RESULT_INVALID_TIMESTAMP¶
Client application’s API call had a timestamp outside the validity window (the local clock has skewed too far from the service’s clock). The
handleResultmethod should automatically correct the state of the user context to adjust for the skew, so the client application should re-try the same API call.
- constant RESULT_NO_PERMISSION¶
Request API action is not allowed; typically the client application should inform the user, and perhaps direct the user to request different permissions from the service administrator.