\BrightBase

This is the base object for interacting w/ Bright from PHP.

It should never be instantiated itself, but rather through creating a singleton of an inheriting class, like:

$bright = \Bright[WebStackClass]::getInstance(); // Wordpress, Drupal, etc.

Once instantiated, for most useful functions it is required to acquire an API token.

Note the leading \ before the Bright Namespace. While not always necessarily, this will always take you to the root namespace and should generally be included.

$bright->setCurrentUser(...); // replace ... with a the current user object; however you derive it.
$bright->getAuthenticationCodeForUser(); // ... initializes the api and/or fetches an accessToken

Summary

Methods
Properties
Constants
getInstance()
__destroy()
getOptions()
getAnonymousAccessToken()
reset()
isLogging()
addTemplate()
setCurrentUser()
setAndAuthenticateCurrentUser()
authenticateCurrentUser()
getCurrentUser()
doFooter()
curlErrorMsg()
returnAsJavascript()
expandShortcode()
hasWebserver()
formatBacktraceLine()
writeToPage()
getBrightServerUrl()
curl()
errorBlock()
getUserAgent()
isReadyUnAuthenticated()
isReadyAuthenticated()
getAuthenticationCodeForUser()
getAuthenticationCodeForEmail()
getTemplateClass()
getTemplateFromApi()
callApi()
getCourseData()
getCourseList()
getRegistrationDataForRegistration()
getRegistrationDataForCourse()
setParam()
getCourseDataByGuid()
getReportageUrls()
getSupportEmail()
resetCachedKey()
setAccessTokenFromValidCachedKey()
errorLog()
updateBrightUserMeta()
encodeJsonPrimitive()
encodeJson()
updateRealmUserCustom()
getLocalTemplates()
getTemplateText()
resetAuthenticationToken()
getCourseProviders()
createRegistration()
isTesting()
writePageHeader()
isBooleanOptionSet()
doErrorception()
getBrightLogoImage()
getRequestCode()
log()
invitationExists()
addLearnerToInvitation()
createInvitation()
isUserRegisteredToCourse()
setCurrentCourseProvider()
renderCourseList()
doesUserHaveActiveRegistrations()
setCourseCustomField()
getCourseCustom()
getRegistrationCustom()
setRegistrationCustom()
setRegistrationCustomField()
unsetRegistrationCustomField()
writeRealmCustomKey()
deleteRealmCustomKey()
setRealmCustomField()
updateRealmCustom()
removeRealmCustomKey()
getRealmData()
getRealmCustom()
extractMostRecentRegistrationFromCourseData()
generate_local_api_keys_if_needed()
api_call_from_remote_is_authorized()
get_course_data_by_custom_key()
get_course_data_for_learning_path()
$accessToken
$successfullyInitialized
$initializationError
$accessTokenExpiration
$isHeaderWritten
$curlHttpCode
$curlError
$curlInfo
$embedderTemplates
$realmGuid
$realmSecretKey
$scormCloudAppId
$scormCloudSecretKey
$apiRoot
$renderedCourseList
$maximumLogMsg
$runQuiet
$echoLogging
$footerJs
$CURLMISSINGERROR
$realmId
No constants found
__construct()
$instance
N/A
__clone()
__wakeup()
$apiCache
$curlInfoCache
$curlErrorCache
$numCacheHits
$numCacheMisses
$totalTimeInBrightApi
$courseLists
$currentUser
N/A

Properties

$accessToken

$accessToken : \Bright\The

Type

\Bright\The — Bright Access Token as return from the Bright API or from local cache.

$successfullyInitialized

$successfullyInitialized : 

Type

$initializationError

$initializationError : 

Type

$accessTokenExpiration

$accessTokenExpiration : \Bright\When

Type

\Bright\When — this token will expire

$isHeaderWritten

$isHeaderWritten : 

Type

— is set to true once the header is generated to the page. Some webstacks may generate the 'header' callback multiple times [like wordpress];

$curlHttpCode

$curlHttpCode : 

Type

$curlError

$curlError : 

Type

$curlInfo

$curlInfo : 

Type

$embedderTemplates

$embedderTemplates : 

Type

$realmGuid

$realmGuid : 

Type

$realmSecretKey

$realmSecretKey : 

Type

$scormCloudAppId

$scormCloudAppId : 

Type

$scormCloudSecretKey

$scormCloudSecretKey : 

Type

$apiRoot

$apiRoot : 

Type

$renderedCourseList

$renderedCourseList : 

Type

$maximumLogMsg

$maximumLogMsg : \Bright\Defaults

Type

\Bright\Defaults — to 1000 characters. Logging messages than this are clipped.

$runQuiet

$runQuiet : boolean

Type

boolean — for non webserver mode, don't echo out messages. If WP_DEBUG=true, logging is generated.

$echoLogging

$echoLogging : boolean

Type

boolean — for some reason, phpunit running inconsistently echos error_log messages. This forces an echo of the message.

$footerJs

$footerJs : string

Type

string — footerJs this variable holds javascript to be dumped in the page footer for bright to function.

$CURLMISSINGERROR

$CURLMISSINGERROR : 

Type

$realmId

$realmId : 

Type

$instance

$instance : \Bright\Singleton

Type

\Bright\Singleton — The reference to *Singleton* instance of this class

$apiCache

$apiCache : 

$apiCache stores api results, and will return the cached results when callApi is called with "matching" arguments.

Type

$curlInfoCache

$curlInfoCache : 

Type

$curlErrorCache

$curlErrorCache : 

Type

$numCacheHits

$numCacheHits : 

Type

$numCacheMisses

$numCacheMisses : 

Type

$totalTimeInBrightApi

$totalTimeInBrightApi : 

Type

$courseLists

$courseLists : 

Type

$currentUser

$currentUser : \Bright\Bright

Type

\Bright\Bright — is initialized to use this user for authenticated user. But you can actually set it to any valid user. This can be useful when the host authentication system is broken.

Methods

getInstance()

getInstance() : \Bright\Singleton

Returns the *Singleton* instance of this class.

Returns

\Bright\Singleton

The Singleton instance.

__destroy()

__destroy() 

getOptions()

getOptions() 

getAnonymousAccessToken()

getAnonymousAccessToken() 

reset()

reset() 

Resets the bright internal data and fetches a new authentication code.

isLogging()

isLogging() 

addTemplate()

addTemplate(  $name,   $text) 

Add in a template to the local dictionary.

Parameters

$name
$text

setCurrentUser()

setCurrentUser(  $user) : \Bright\WP_USER

sets the current user. Note when running from phpunit; calling this more than once can clear the current user altogether

Parameters

$user

Returns

\Bright\WP_USER —

a WP_USER object of the current user.

setAndAuthenticateCurrentUser()

setAndAuthenticateCurrentUser(  $user) 

Parameters

$user

authenticateCurrentUser()

authenticateCurrentUser() 

Takes the current user object and authenticates it.

getCurrentUser()

getCurrentUser() 

doFooter()

doFooter() 

curlErrorMsg()

curlErrorMsg() 

Return a curl error , or a comment that we didn't see an error. Don't use this function to check for errors!

returnAsJavascript()

returnAsJavascript(string  $code) 

Parameters

string $code

the code to embed in script tags

expandShortcode()

expandShortcode(array  $attr, string  $content = null) : \Bright\the

Converts a [bright] shortcode into two things: 1. a piece of converted content, most likely a <div> tag to be populated by the Bright.js templating library.

  1. Javascript that is cached, and then echo-ed into the page footer.

For more about the functionality of this method, see http://help.aura-software.com/bright-shortcode-reference

Parameters

array $attr
string $content

Returns

\Bright\the —

content string.

hasWebserver()

hasWebserver() : boolean

Returns

boolean —

returns true if we are running in a webserver. False means command line.

formatBacktraceLine()

formatBacktraceLine(  $c,   $function = true,   $file = true) : String

Returns a formatted line from a backtrace.

Parameters

$c

Array() an array returned as an element of the array returned from debug_trace();

$function
$file

Returns

String

writeToPage()

writeToPage(  $msg) 

Manages 'echo' statements. Originally we ran in a webserver and errors were written to the page. Now, for command line mode, it's nice to be able shut these statement off if necessary [like in the test chassis].

Thus, if the class variable $runQuiet is set, we won't generate echo statements.

Parameters

$msg

getBrightServerUrl()

getBrightServerUrl(  $base, array  $args = array()) : string

Parameters

$base
array $args
  • key 'params' becomes the query parameters

Returns

string —

the full URL with query parameters.

curl()

curl(string  $url, array  $args = array()) : string

Call the PHP base curl function, based on arguments below. As a side effect the following are set: * $this->curlInfo * $this->curlHttpCode * $this->curlError

Parameters

string $url

Full url to get/post

array $args
  • 'postData' indicates a POST, with the assigned value being an array.
    • 'errorMsgs' allows a set of error message to be passed in as an array, where the key is the HTTP response code, and values are the messages to be generated. Message generation is handled by the Bright->writeToPage() function. To suppress errorMsgs, just pass in a empty array for errorMsgs.
    • 'params' for the post or get data [get data will be in the URL].
    • 'suppressErrorBlock' - if any value, we will not generate the generic Bright error block on failure.

Returns

string —

The returned data. Use the $curlError and $curlInfo public class variables to get additional data about the curl call.

errorBlock()

errorBlock(  $msg,   $params = array()) 

Parameters

$msg
$params

getUserAgent()

getUserAgent() 

isReadyUnAuthenticated()

isReadyUnAuthenticated() 

isReadyAuthenticated()

isReadyAuthenticated() : boolean

Returns true if Bright has enough information to run in Authenticated Mode. If not, return false. By enough we mean, enough config data and a user object.

Returns

boolean

getAuthenticationCodeForUser()

getAuthenticationCodeForUser(  $user = null) 

Makes a call to Bright API for the current user, fetches an API key, and stores it in the Bright\Base object.

We also set the accessTokenExpiration Bright instance variable.

Parameters

$user

getAuthenticationCodeForEmail()

getAuthenticationCodeForEmail(  $email) 

Just fetches a one-time access token for an email

Parameters

$email

getTemplateClass()

getTemplateClass(  $template) : string

Derive the div CSS Class for a generated template, based on the

Parameters

$template

Returns

string —

the CSS class for a generated Bright Div.

getTemplateFromApi()

getTemplateFromApi(  $template, array  $args = array()) 

Parameters

$template
array $args

callApi()

callApi(string  $apiController, array  $args = array()) : mixed

Calls the Bright Api and returns the result.

Defined keys for the $args array() include:

  • accessMode: one of 'accessToken' or 'realm'. If accessToken, uses the apiKey derived when the Bright object is initialized. If 'realm', the accessToken is ignored and access is made just with the Bright realm guid and realm secret key.
  • params, these are used to assemble the query string and/or POST data. Anything placed here is passed through directly to the API call.
  • raw, which as a boolen when set disables parsing of returned JSON.
  • method. Set to "POST" for post method.
  • errorMsgs. You can define an array of error messages based on HTTP returl codes. The defaults are: array('401' => "Failed to authenticate with Bright server; code 401.", '404' => "A resource was attempted to be fetched from Bright Server, but not found; code 404.");
  • encode. A list of params that should be json_encooded.
  • dontcheckcache. Don't check the API cache for a previous result.
  • dontcacheresult. Don't place result in API cache.
  • removecacheresult. Remove data from the cache [use this when doing a fetch before an update].

Parameters

string $apiController

this is the app interface to hit (course|registration|api_key|...)

array $args

An array of arguments. See description for the arguments.

Returns

mixed —

an array parsed json; unless raw is set, then the raw response data.

getCourseData()

getCourseData(array  $args = array()) : Array

Parameters

array $args

Returns

Array —

the complete parsed json response

getCourseList()

getCourseList(  $key, array  $args = array()) 

Parameters

$key
array $args

getRegistrationDataForRegistration()

getRegistrationDataForRegistration(  $registrationGuid, array  $args = array()) 

Parameters

$registrationGuid
array $args

getRegistrationDataForCourse()

getRegistrationDataForCourse(string  $courseGuid, array  $args = array()) : mixed

Parameters

string $courseGuid

the course ID aka SCORMCloud course ID for the registration to be fetched. Note, on the most recent non-deleted registration is returned per the 'last_only' attribute as passed to bright server via the Bright API.

array $args

a set of args to pass to Bright::Base->callApi(). See the documentation of that function for more details.

Returns

mixed —

Null if not found, or a stdObject with the registration data.

setParam()

setParam(array  $args = array(),   $name,   $value) 

Parameters

array $args
$name
$value

getCourseDataByGuid()

getCourseDataByGuid(string  $courseGuid, array  $args = array()) : mixed

Parameters

string $courseGuid

the course ID aka SCORMCloud course ID for the course to be fetched.

array $args

a set of args to pass to Bright::Base->callApi(). See the documentation of that function for more details.

Returns

mixed —

Null if not found, or a stdObject with the course data.

getReportageUrls()

getReportageUrls() 

getSupportEmail()

getSupportEmail() : String

Returns

String —

the support text for this method [an HTML block if running in a webserver].

resetCachedKey()

resetCachedKey() 

setAccessTokenFromValidCachedKey()

setAccessTokenFromValidCachedKey(  $user) 

Checks in the webstack DB and looks for a valid cached API key that hasn't expired, and was generated from the same Bright URL we are currently talking to.

Also lift out the expiration data and provide that in a Bright instance variable.

Parameters

$user

errorLog()

errorLog(  $msg) 

Wraps the error_log function. If $echoLogging is set on the Bright object, the message will also be echoed.

Parameters

$msg

updateBrightUserMeta()

updateBrightUserMeta(mixed  $user) : string

Initiates a call to the Bright API, to update user attributes from this site for the user.

Parameters

mixed $user

A user object in the native format for the Webstack.

Returns

string —

Returns the data passed back from the bright API in raw format [as a string].

encodeJsonPrimitive()

encodeJsonPrimitive(  $item,   $key) 

Parameters

$item
$key

encodeJson()

encodeJson(array  $arr = array()) 

Parameters

array $arr

updateRealmUserCustom()

updateRealmUserCustom(  $email,   $userAttributes, array  $args = array()) 

Parameters

$email
$userAttributes
array $args

getLocalTemplates()

getLocalTemplates() : Array

Returns all the local templates available before filtering. Currently keys in the global $bright_embedder_templates will override the keys in the Bright class variable $embedderTemplates.

Returns

Array —

all the local templates available before filtering.

getTemplateText()

getTemplateText(array  $args = array()) : string

Returns the template text. Searches in the following order:

  1. the Bright class $embedderTemplates variable.
  2. the deprecated $bright_embedder_templates variable [this will be remove in Bright 9.0].
  3. the API is queried to see if the template is stored there.

Parameters

array $args

Returns

string —

the template text

resetAuthenticationToken()

resetAuthenticationToken() 

Resets the authentication token.

getCourseProviders()

getCourseProviders(array  $args = array()) 

Parameters

array $args

createRegistration()

createRegistration(array  $args = array()) 

Parameters

array $args

isTesting()

isTesting() 

writePageHeader()

writePageHeader() 

isBooleanOptionSet()

isBooleanOptionSet(array  $args = array()) 

Parameters

array $args

doErrorception()

doErrorception() 

Dumps out the necessary JS to integrate this site with errorception.

getBrightLogoImage()

getBrightLogoImage() : string

Returns

string —

URL of a bright logo image

getRequestCode()

getRequestCode() 

log()

log(  $message,   $extra_text = null) 

Parameters

$message
$extra_text

invitationExists()

invitationExists(array  $args = array()) 

returns the invitation object if an invitation exists with the requested parameters, otherwise returns NULL

Parameters

array $args

addLearnerToInvitation()

addLearnerToInvitation(  $learnerId,   $invitationName, array  $args = array()) 

Parameters

$learnerId
$invitationName
array $args

createInvitation()

createInvitation(array  $args = array()) 

Parameters

array $args

isUserRegisteredToCourse()

isUserRegisteredToCourse(  $courseGuid, array  $args = array()) 

Parameters

$courseGuid
array $args

setCurrentCourseProvider()

setCurrentCourseProvider() 

renderCourseList()

renderCourseList(  $courseList) 

Parameters

$courseList

doesUserHaveActiveRegistrations()

doesUserHaveActiveRegistrations() 

setCourseCustomField()

setCourseCustomField(  $courseGuid,   $tag,   $value,   $args = array()) 

Parameters

$courseGuid
$tag
$value
$args

getCourseCustom()

getCourseCustom(  $courseGuid,   $args = array()) 

Parameters

$courseGuid
$args

getRegistrationCustom()

getRegistrationCustom(  $registrationGuid,   $args = array()) 

Parameters

$registrationGuid
$args

setRegistrationCustom()

setRegistrationCustom(  $registrationGuid,   $json) 

Parameters

$registrationGuid
$json

setRegistrationCustomField()

setRegistrationCustomField(  $registrationGuid,   $tag,   $value) 

Parameters

$registrationGuid
$tag
$value

unsetRegistrationCustomField()

unsetRegistrationCustomField(  $registrationGuid,   $tag) 

Parameters

$registrationGuid
$tag

writeRealmCustomKey()

writeRealmCustomKey(  $key,   $value) 

Parameters

$key
$value

deleteRealmCustomKey()

deleteRealmCustomKey(  $key) 

Parameters

$key

setRealmCustomField()

setRealmCustomField(  $tag,   $value,   $args = array()) 

Parameters

$tag
$value
$args

updateRealmCustom()

updateRealmCustom(  $json,   $args = array()) 

Parameters

$json
$args

removeRealmCustomKey()

removeRealmCustomKey(  $tag,   $args = array()) 

Parameters

$tag
$args

getRealmData()

getRealmData(  $args = array()) 

Parameters

$args

getRealmCustom()

getRealmCustom(  $args = array()) 

Parameters

$args

extractMostRecentRegistrationFromCourseData()

extractMostRecentRegistrationFromCourseData(  $courseData) 

Parameters

$courseData

generate_local_api_keys_if_needed()

generate_local_api_keys_if_needed() 

Generates local API keys for remote agents to call, if not set.

api_call_from_remote_is_authorized()

api_call_from_remote_is_authorized() 

get_course_data_by_custom_key()

get_course_data_by_custom_key(  $key,   $args = array()) 

takes a key, and returns any course that has that key defined in it's custom metadata

Example:

$key = 'my-custom-key'; $courses = $this->get_course_data_by_custom_key($key,$args);

// $courses is an array();

Parameters

$key
$args

get_course_data_for_learning_path()

get_course_data_for_learning_path(  $key,   $args = array()) 

takes the learning path as $key, and returns an array of course records which are the courses in the learning path, ordered by learning path id.

Example:

$bright = Bright\Wordpress::getInstance(); $courses = $bright->get_course_data_for_learning_path('dashboard_test');

// get custom $json json_decode($courses[0]->custom);

Parameters

$key
$args

__construct()

__construct() 

Protected constructor to prevent creating a new instance of the *Singleton* via the `new` operator from outside of this class.

__clone()

__clone() : void

Private clone method to prevent cloning of the instance of the *Singleton* instance.

__wakeup()

__wakeup() : void

Private unserialize method to prevent unserializing of the *Singleton* instance.