This document describes how to obtain the $bright object in WordPress, authenticate against the Bright server, and call the Bright API using callApi() and callV3Api().
It covers the WordPress connector layer (the $args model, access modes, response handling, and curl metadata). For field-by-field definitions of individual API controllers, see the Bright API documentation.
Prerequisites
Use this approach when you need server-side PHP access to Bright from:
bright_anonymous_api_key — for unauthenticated (user ID 0) requests. Set in the WP Admin Console Bright settings
Obtaining $bright
$bright is a local variable name, not a WordPress global and is an instantiation of the Bright Singleton pattern (see PHP Singleton explanation). The standard pattern is:
getInstance() creates one instance per request (lazy singleton)
Never instantiate Bright\Base directly
On first getInstance():
Constructor runs getOptions() and loads apiRoot, realmGuid, realmSecretKey, SCORM Cloud keys from WordPress options
If curl_init is missing, successfullyInitialized is set to false and initializationError describes the problem
$bright = \Bright\Wordpress::getInstance();
if (!$bright->successfullyInitialized) {
error_log($bright->initializationError);
return;
}
Other web stacks
If you maintain a non-WordPress Bright connector, brightClass() can return a different class name (for example \Bright\Drupal). The default is \Bright\Wordpress.
Authentication
Most callApi() calls use the default access mode accessToken, which requires $bright->accessToken to be set. If it is empty, callApi() returns null immediately (no HTTP request).
When authentication happens automatically
On a normal front-end page request, the plugin runs doHeader(), which:
Sets the current WordPress user via setCurrentUser()
Calls getAuthenticationCodeForUser() to obtain or restore an access token
In that context you can often call callApi() without extra setup, as long as the visitor is logged in (or anonymous access is configured).
The WordPress Action Workflow that Calls doHeader()
The Bright plugin integrates with WordPress using standard WP action hooks to ensure authentication and environment setup occur early in the page load cycle. The principal initialization occurs in the doHeader() method of the Bright connector class.
When is doHeader() called?
doHeader() is hooked into the wp action, which fires after the query variables are set and just before output starts.
This ensures that authentication and connection setup are ready before any content is rendered (including shortcodes, templates, etc).
Shortcodes and API calls can rely on $bright having access/authentication initialized
In short:
If you call plugin APIs on a normal page, authentication/setup has already occurred because doHeader() runs on wp. This is why in normal theme/template code you do not need to manually call setCurrentUser() and getAuthenticationCodeForUser().
For custom workflows—before wp fires (early/exotic scripts, AJAX, admin, CLI)—you must handle authentication manually as referenced above.
When you must authenticate manually
Use this path in custom code that runs beforedoHeader(), in admin/CLI contexts, or when switching users:
POST / PUT:params are sent as the request body; query string is empty
callApi() — full $args model
Key
Default
Behavior
accessMode
'accessToken'
'accessToken' merges accessToken into params; 'realm' merges realm_guid and realm_secret_key from plugin options. See Access modes.
params
[]
Query string (GET) or POST/PUT body. Auth fields are merged automatically per accessMode.
method
(GET)
Set to 'POST' or 'PUT' to change HTTP method.
raw
unset → decode
If the key exists (isset($args['raw'])), the response body is returned as a string. If unset, json_decode() is applied. raw => false still returns a string because only key presence is checked.
encode
—
Array of param names to json_encode before send (e.g. nested structures for invitations).
success
—
Callable function ($rsp, $curlInfo, $curlError). Return value becomes the callApi() return. Runs when body length > 1.
failure
—
Same signature; runs when body is empty or length ≤ 1.
errorMsgs
401, 404 messages
Map HTTP status code → message string. Passed to curl(); may write HTML error blocks via writeToPage().
suppressErrorBlock
false
If true, suppresses generic Bright HTML error blocks on curl/HTTP errors.
dontcheckcache
false
Skip reading from the per-request in-memory API cache.
dontcacheresult
false
Do not store this response in the cache.
removecacheresult
false
Delete the matching cache entry after the call (use before updates).
apiRoot
$bright->apiRoot
Override API base URL. Set automatically by callV3Api().
Return semantics
Condition
Return
accessMode === 'accessToken' and empty accessToken
null (no request)
Response body empty or length ≤ 1
null, or failure callback result
Success, no success callback
Decoded JSON (stdClass / arrays) or raw string if raw key set
Success, with success callback
Whatever the callback returns
Failure, with failure callback
Whatever the callback returns
Important:json_decode() is called without the true flag, so JSON objects become stdClass, not associative arrays.
Access modes
Only two values are implemented in callApi():
accessToken (default)
Merges the current user's token into params:
'accessToken' => $bright->accessToken
Use for: learner-scoped data — courses, registrations, stored queries run as the logged-in user.
Use for: server-side / admin operations — creating invitations, realm custom data, fetching registration by GUID without a user token, WooCommerce license-key flows.
Any value other than 'accessToken' or 'realm' skips auth injection. Requests will likely return 401. Always pass exactly one of the two supported strings.
Raw vs non-raw responses
Non-raw (default)
JSON is decoded automatically:
$course = $bright->getCourseDataByGuid($guid);
// $course is a stdClass with properties like course_guid, title, ...
List endpoints return a JSON array, which becomes a PHP array of stdClass objects:
$courses = $bright->callApi('course');
// array of stdClass
Raw
Pass 'raw' => true (or any value — only key presence matters):
$json = $bright->callApi('stored_query/run', array(
'params' => array(
'name' => 'bright_completion_matrix',
'host_url' => get_site_url(),
'query_scope' => 'bright',
),
'raw' => true,
));
// $json is a string — embed in a page or pass to JavaScript
Often an array; helper methods return the first element:
$reg = $bright->getRegistrationDataForCourse($courseGuid);
// stdClass or '{}' string on 404
Example registration fields: type, course_guid, registration_guid, registration_guids.
v2 — stored query (stored_query/run)
Shape depends on the query name. Reports typically use raw => true and return a JSON string for templates or DataTables. See also Bright Scoped Stored Queries API Reference and your team's Rails stored-query docs for query parameters.
Realm-mode calls such as addLearnerToInvitation may return an object with messages or error — inspect $bright->curlHttpCode alongside the decoded body.
Success and failure callbacks
Callbacks receive three arguments: $rsp, $curlInfo, $curlError.
Success callback — transform return value
$title = $bright->getCourseDataByGuid($guid, array(
'success' => function ($rsp, $curlInfo, $curlError) {
return $rsp->title;
},
));
// $title is a string
Failure callback — branch on HTTP status
$bright->callApi('stored_query/run', array(
'params' => array(
'name' => 'invitation_completion_matrix',
'invitation_name' => $name,
'host_url' => get_site_url(),
'query_scope' => 'bright',
),
'suppressErrorBlock' => true,
'raw' => true,
'failure' => function ($rsp, $curlInfo, $curlError) {
if ($curlInfo['http_code'] == 401) {
_e('You do not have permission to view this report.');
}
return null;
},
));
Curl metadata
callApi() does not return curl data. After every call (including cache hits), inspect properties on $bright:
Property
Set from
Typical use
$bright->curlHttpCode
$bright->curlInfo['http_code']
Branch on 200, 404, 500
$bright->curlError
curl_error()
Transport-level failures
$bright->curlInfo
curl_getinfo()
Full metadata array
Example: HTTP status after invitation
$ret = $bright->addLearnerToInvitation($email, $licenseKey, array(
'errorMsgs' => array(),
'params' => array('nodelay' => true),
));
if ($bright->curlHttpCode == 404) {
// license key not found
} elseif ($bright->curlHttpCode == 200) {
// success — check $ret->messages
} else {
// other error — may use $ret->error
}
Notable curlInfo keys
After a call, $bright->curlInfo may include:
Key
Meaning
http_code
HTTP status (mirrored in curlHttpCode)
url
Request URL
total_time
Total time in seconds
content_type
Response Content-Type
size_download
Bytes downloaded
curlErrorMsg()
Returns a human-readable message. Do not use this to detect errors — use $bright->curlHttpCode and $bright->curlError instead.
Per-request API cache
Identical callApi arguments (URL + sorted params) are cached in memory for the duration of the request. On cache hit, curlInfo and curlError are restored from cache.
The page footer may expose stats via JavaScript:
Bright.cacheData = { "num_cache_hits": N, "num_cache_misses": M, "total_time": T };
If your team maintains scoped stored-query documentation on the Rails app, use that for query name, query_scope, and parameter definitions. The WordPress plugin only passes those through via params on stored_query/run.
