\CanvasPest

An object to handle interactions with the Canvas API.

For more information on the Canvas API refer to the offical Canvas API documentation or to the (slightly more up-to-date and pleasingly interactive) live documentation.

You can access the live documentation for your own Canvas instance and make actual API calls to it at https://<path-to-your-instance>/doc/api/live

Summary

Methods
Properties
Constants
__construct()
setupToken()
prepData()
get()
post()
put()
delete()
patch()
No public properties found
PARAM_PER_PAGE
prepHeaders()
postprocessResponse()
$headers
N/A
preprocessData()
No private properties found
N/A

Constants

PARAM_PER_PAGE

PARAM_PER_PAGE

Name of the parameter controlling the number of responses per page

Properties

$headers

$headers : array<mixed,string>

Type

array<mixed,string> — Additional headers to be passed to the API with each call

Methods

__construct()

__construct(string  $apiInstanceUrl, string  $apiAuthorizationToken = null) : void

Construct a new CanvasPest

Parameters

string $apiInstanceUrl

URL of the API instance (e.g. 'https://canvas.instructure.com/api/v1')

string $apiAuthorizationToken

(Optional) API access token for the API instance (if not provided now, it will need to be provided later)

setupToken()

setupToken(string  $token) 

Set up a new API access token to access this instance

Parameters

string $token

API access token

Throws

\CanvasPest_Exception

INVALID_TOKEN on an empty or non-string token value

prepData()

prepData(array<mixed,string>  $data) : string|array<mixed,string>

Prepare data

Extended by CanvasPest to format the HTTP query parameters with non-indexed array elements (so ...foo?bar[]=1&bar[]=2, rather than ...foo?bar[0]=1&bar[1]=2, as the Canvas API prefers them).

Parameters

array<mixed,string> $data

Query parameters

Returns

string|array<mixed,string>

get()

get(string  $path, string|array<mixed,string>  $data = array(), string|array<mixed,string>  $headers = array()) : \CanvasObject|\CanvasArray

Make a GET call to the API

For queries to individually identified endpoints (e.g. accounts/1/users/123), return a CanvasObject representing the API response describing that individually identified object affected by the query.

For queries to generic endpoints (e.g. accounts/1/users), return a traversable CanvasArray (of CanvasObjects) representing the API response describing the list of objects affected by the query.

Parameters

string $path

Path to the API endpoint of this call

string|array<mixed,string> $data

(Optional) Query parameters for this call

string|array<mixed,string> $headers

(Optional) Any additional HTTP headers for this call

Returns

\CanvasObject|\CanvasArray

post()

post(string  $path, string|array<mixed,string>  $data = array(), string|array<mixed,string>  $headers = array()) : \CanvasObject|\CanvasArray

Make a POST call to the API

For queries to individually identified endpoints (e.g. accounts/1/users/123), return a CanvasObject representing the API response describing that individually identified object affected by the query.

For queries to generic endpoints (e.g. accounts/1/users), return a traversable CanvasArray (of CanvasObjects) representing the API response describing the list of objects affected by the query.

Parameters

string $path

Path to the API endpoint of this call

string|array<mixed,string> $data

(Optional) Query parameters for this call

string|array<mixed,string> $headers

(Optional) Any additional HTTP headers for this call

Returns

\CanvasObject|\CanvasArray

put()

put(string  $path, string|array<mixed,string>  $data = array(), string|array<mixed,string>  $headers = array()) : \CanvasObject|\CanvasArray

Make a PUT call to the API

For queries to individually identified endpoints (e.g. accounts/1/users/123), return a CanvasObject representing the API response describing that individually identified object affected by the query.

For queries to generic endpoints (e.g. accounts/1/users), return a traversable CanvasArray (of CanvasObjects) representing the API response describing the list of objects affected by the query.

Parameters

string $path

Path to the API endpoint of this call

string|array<mixed,string> $data

(Optional) Query parameters for this call

string|array<mixed,string> $headers

(Optional) Any additional HTTP headers for this call

Returns

\CanvasObject|\CanvasArray

delete()

delete(string  $path, string|array<mixed,string>  $headers = array()) : \CanvasObject|\CanvasArray

Make a DELETE call to the API

For queries to individually identified endpoints (e.g. accounts/1/users/123), return a CanvasObject representing the API response describing that individually identified object affected by the query.

For queries to generic endpoints (e.g. accounts/1/users), return a traversable CanvasArray (of CanvasObjects) representing the API response describing the list of objects affected by the query.

Parameters

string $path

Path to the API endpoint of this call

string|array<mixed,string> $headers

(Optional) Any additional HTTP headers for this call

Returns

\CanvasObject|\CanvasArray

patch()

patch() : void

Make a PATCH call to the API

Throws

\CanvasPest_Exception

UNSUPPORTED_METHOD All calls to this method will cause an exception

prepHeaders()

prepHeaders(array<mixed,string>  $headers) : array<mixed,string>

Prepare API request headers

Flatten headers from an associative array to a numerically indexed array of "Name: Value" style entries like CURLOPT_HTTPHEADER expects. Numerically indexed arrays are not modified.

Extended by CanvasPest to include the API access token in the Authorization header.

Parameters

array<mixed,string> $headers

Returns

array<mixed,string>

postprocessResponse()

postprocessResponse(string  $response) : \CanvasObject|\CanvasArray

Parse the API response into an object (or collection of objects).

For queries to individually identified endpoints (e.g. accounts/1/users/123), return a CanvasObject representing the API response describing that individually identified object affected by the query.

For queries to generic endpoints (e.g. accounts/1/users), return a traversable CanvasArray (of CanvasObjects) representing the API response describing the list of objects affected by the query.

Parameters

string $response

JSON-encoded response from the API

Returns

\CanvasObject|\CanvasArray

preprocessData()

preprocessData(array<mixed,string>  $data) : array<mixed,string>

Preprocess API call parameters before use

Force maximum response page size, if not already defined.

Parameters

array<mixed,string> $data

Array of parameters for the next API call

Returns

array<mixed,string> —

Updated array of parameters