Result
extends Entity
in package
This is a class to provide access to the user's result data.
This data comes from the LTI launch from the LMS.
Table of Contents
Properties
- $grade : mixed
- The current grade for the user
- $id : mixed
- The integer primary key for this link in the 'lti_result' table.
- $lastSendTransport : mixed
- The transport used to send the most recent grade.
- $launch : mixed
- A reference to our containing launch
- $PRIMARY_KEY : mixed
- $TABLE_NAME : mixed
Methods
- atAttemptLimit() : mixed
- Whether a hard cap on attempts has been reached.
- canRetry() : mixed
- Whether a new attempt is allowed given delay settings.
- getAttempts() : object
- Retrieve the number of attempts and latest attempt
- getComment() : string|false
- Get the comment stored for this result.
- getJson() : string
- Load the json field for this entity
- getJsonForUser() : The
- Get a JSON for a different user
- getJsonKey() : mixed
- Get a JSON key for this entity
- getJsonKeyForUser() : The
- Get a JSON key for a result for a different user
- getJsonKeyLegacy() : mixed
- Get a JSON key for this entity (legacy array style)
- getNote() : string|false
- The comment for this result. Reads lti_result.comment.
- gradeGet() : mixed
- Load the grade for a particular row and update our local copy
- gradeSend() : mixed
- Send a grade and update our local copy
- gradeSendDueDate() : mixed
- Send a grade applying the due date logic and only increasing grades
- gradeSendStatic() : mixed
- Send a grade and update our local copy
- lookupResultBypass() : mixed
- ltiCustomGet() : mixed
- Pull out a custom variable from the LTIX session. Do not include the "custom_" prefix - this is automatic.
- ltiParameter() : mixed
- Pull a keyed variable from the original LTI post data in the current session with default
- ltiParameterUpdate() : mixed
- Update a keyed variable from the original LTI post data in the current session with default
- ltiRawParameter() : mixed
- Pull a keyed variable from the original LTI post data in the current session with default
- ltiRawPostArray() : mixed
- Return the original $_POST array
- notifyReadyToGrade() : mixed
- Notify the LMS that this result is ready for grading
- recordAttempt() : mixed
- Record an attempt on this result - different than submitting a grade
- secondsUntilRetry() : int
- Seconds remaining before another attempt is allowed.
- setComment() : mixed
- Set the comment stored for this result.
- setJson() : mixed
- Set the JSON entry for this entity
- setJsonForUser() : The
- Set JSON for a different user
- setJsonKey() : mixed
- Set/update a JSON key for this entity
- setJsonKeyForUser() : The
- Set a JSON key for a result for a different user
- setJsonKeys() : mixed
- Set/update an array of JSON keys for this entity
- setNote() : mixed
- The comment for this result. Writes lti_result.comment.
- numericSetting() : mixed
- Coerce a link-setting value to a number.
- suppliedProgress() : string|false
- A progress value from $extra. Absent or empty uses $default.
Properties
$grade
The current grade for the user
public
mixed
$grade
= null
If there is a current grade (float between 0.0 and 1.0) it is in this variable. If there is not yet a grade for this user/link combination, this will be false.
$id
The integer primary key for this link in the 'lti_result' table.
public
mixed
$id
$lastSendTransport
The transport used to send the most recent grade.
public
mixed
$lastSendTransport
= null
Set to false if the grade was local-only.
$launch
A reference to our containing launch
public
mixed
$launch
$PRIMARY_KEY
protected
mixed
$PRIMARY_KEY
= "result_id"
$TABLE_NAME
protected
mixed
$TABLE_NAME
= "lti_result"
Methods
atAttemptLimit()
Whether a hard cap on attempts has been reached.
public
atAttemptLimit(mixed $max_tries[, object|null $info = null ]) : mixed
Non-numeric or less-than-one $max_tries means no cap.
Parameters
- $max_tries : mixed
-
Maximum allowed attempts
- $info : object|null = null
-
Optional getAttempts() result
canRetry()
Whether a new attempt is allowed given delay settings.
public
canRetry([mixed $delay = 0 ][, mixed $delay_tries = 0 ][, object|null $info = null ]) : mixed
Parameters
- $delay : mixed = 0
-
Seconds between retries
- $delay_tries : mixed = 0
-
Attempts allowed before the delay applies
- $info : object|null = null
-
Optional getAttempts() result
getAttempts()
Retrieve the number of attempts and latest attempt
public
getAttempts() : object
Return values
object —with attempted_at, attempts, submitted_at, and updated_at
getComment()
Get the comment stored for this result.
public
getComment([mixed $user_id = false ]) : string|false
Parameters
- $user_id : mixed = false
-
The primary key of the user (instructor only)
Return values
string|falsegetJson()
Load the json field for this entity
public
getJson() : string
Return values
string —This returns the json string - it is not parsed - if there is nothing to return - this returns "false"
getJsonForUser()
Get a JSON for a different user
public
getJsonForUser(mixed $user_id) : The
Parameters
- $user_id : mixed
-
The primary key of the user (instructor only)
Return values
The —JSON string (unparsed)
getJsonKey()
Get a JSON key for this entity
public
getJsonKey(mixed $key[, mixed $default = false ]) : mixed
Parameters
- $key : mixed
-
The key to be retrieved from the JSON
- $default : mixed = false
-
The default value (optional)
getJsonKeyForUser()
Get a JSON key for a result for a different user
public
getJsonKeyForUser(mixed $key[, mixed $default = false ][, mixed $user_id = false ]) : The
Parameters
- $key : mixed
-
The key to be retrieved from the JSON
- $default : mixed = false
-
The default value (optional)
- $user_id : mixed = false
-
The primary key of the user (instructor only)
Return values
The —value of the JSON key (parsed)
getJsonKeyLegacy()
Get a JSON key for this entity (legacy array style)
public
getJsonKeyLegacy(mixed $key[, mixed $default = false ]) : mixed
Parameters
- $key : mixed
-
The key to be retrieved from the JSON
- $default : mixed = false
-
The default value (optional)
getNote()
The comment for this result. Reads lti_result.comment.
public
getNote([mixed $user_id = false ]) : string|false
Parameters
- $user_id : mixed = false
-
The primary key of the user (instructor only)
Return values
string|falsegradeGet()
Load the grade for a particular row and update our local copy
public
static gradeGet([mixed $row = false ][, mixed &$debug_log = false ]) : mixed
Call the right LTI service to retrieve the server's grade and update our local cached copy of the server_grade and the date retrieved. This routine pulls the key and secret from the LTIX session to avoid crossing cross tenant boundaries.
TODO: Add LTI 2.x support for the JSON style services to this
Parameters
- $row : mixed = false
-
An optional array with the data that has the result_id, sourcedid, and service (url) if this is not present, the data is pulled from the LTI session for the current user/link combination.
- $debug_log : mixed = false
-
An (optional) array (by reference) that returns the steps that were taken. Each entry is an array with the [0] element a message and an optional [1] element as some detail (i.e. like a POST body)
Return values
mixed —If this work this returns a float. If not you get a string with an error.
gradeSend()
Send a grade and update our local copy
public
gradeSend(mixed $grade[, mixed $row = false ][, mixed &$debug_log = false ][, mixed $extra = false ]) : mixed
Call the right LTI service to send a new grade up to the server. update our local cached copy of the server_grade and the date retrieved. This routine pulls the key and secret from the LTIX session to avoid crossing cross tenant boundaries.
Parameters
- $grade : mixed
-
A new grade - floating point number between 0.0 and 1.0
- $row : mixed = false
-
An optional array with the data that has the result_id, sourcedid, service (url), key_key, and secret. If these are not present, the data is pulled from the LTI session for the current user/link combination.
- $debug_log : mixed = false
-
An (optional) array (by reference) that returns the steps that were taken. Each entry is an array with the [0] element a message and an optional [1] element as some detail (i.e. like a POST body)
- $extra : mixed = false
-
A key/value store of extra parameters
Return values
mixed —If this works it returns true. If not, you get a string with an error.
gradeSendDueDate()
Send a grade applying the due date logic and only increasing grades
public
gradeSendDueDate(mixed $gradetosend[, mixed $oldgrade = false ][, mixed $dueDate = false ]) : mixed
Puts messages in the session for a redirect.
Parameters
- $gradetosend : mixed
-
- The grade in the range 0.0 .. 1.0
- $oldgrade : mixed = false
-
- The previous grade in the range 0.0 .. 1.0 (optional)
- $dueDate : mixed = false
-
- The due date for this assignment
gradeSendStatic()
Send a grade and update our local copy
public
static gradeSendStatic(mixed $grade[, mixed $row = false ][, mixed &$debug_log = false ][, mixed $extra = false ]) : mixed
Call the right LTI service to send a new grade up to the server. update our local cached copy of the server_grade and the date retrieved. This routine pulls the key and secret from the LTIX session to avoid crossing cross tenant boundaries.
Parameters
- $grade : mixed
-
A new grade - floating point number between 0.0 and 1.0
- $row : mixed = false
-
An optional array with the data that has the result_id, sourcedid, service (url), key_key, and secret. If these are not present, the data is pulled from the LTI session for the current user/link combination.
- $debug_log : mixed = false
-
An (optional) array (by reference) that returns the steps that were taken. Each entry is an array with the [0] element a message and an optional [1] element as some detail (i.e. like a POST body)
- $extra : mixed = false
-
A key/value store of extra parameters
Return values
mixed —If this works it returns true. If not, you get a string with an error.
lookupResultBypass()
public
static lookupResultBypass(mixed $user_id) : mixed
Parameters
- $user_id : mixed
ltiCustomGet()
Pull out a custom variable from the LTIX session. Do not include the "custom_" prefix - this is automatic.
public
ltiCustomGet(mixed $varname[, mixed $default = false ]) : mixed
Parameters
- $varname : mixed
- $default : mixed = false
ltiParameter()
Pull a keyed variable from the original LTI post data in the current session with default
public
ltiParameter(mixed $varname[, mixed $default = false ]) : mixed
Parameters
- $varname : mixed
- $default : mixed = false
ltiParameterUpdate()
Update a keyed variable from the original LTI post data in the current session with default
public
ltiParameterUpdate(mixed $varname, mixed $value) : mixed
Parameters
- $varname : mixed
- $value : mixed
ltiRawParameter()
Pull a keyed variable from the original LTI post data in the current session with default
public
ltiRawParameter(mixed $varname[, mixed $default = false ]) : mixed
Parameters
- $varname : mixed
- $default : mixed = false
ltiRawPostArray()
Return the original $_POST array
public
ltiRawPostArray() : mixed
notifyReadyToGrade()
Notify the LMS that this result is ready for grading
public
notifyReadyToGrade([mixed &$debug_log = false ]) : mixed
For LTI13, we set the values and send a null grade. For LTI11, we send a grade of 0.0 with a comment as long as a grade has not already been sent.
Parameters
- $debug_log : mixed = false
-
An (optional) array (by reference) that returns the steps that were taken.
recordAttempt()
Record an attempt on this result - different than submitting a grade
public
recordAttempt() : mixed
Increments attempts, sets attempted_at, and stamps submitted_at on the first real attempt (leaves later submissions unchanged).
secondsUntilRetry()
Seconds remaining before another attempt is allowed.
public
secondsUntilRetry([mixed $delay = 0 ][, mixed $delay_tries = 0 ][, object|null $info = null ]) : int
After $delay_tries free attempts, the student must wait $delay seconds from attempted_at. Blank, non-numeric, or non-positive delay means no wait.
Parameters
- $delay : mixed = 0
-
Seconds between retries
- $delay_tries : mixed = 0
-
Attempts allowed before the delay applies
- $info : object|null = null
-
Optional getAttempts() result to avoid a second query
Return values
int —Seconds to wait (0 if a retry is allowed now)
setComment()
Set the comment stored for this result.
public
setComment(mixed $comment_str[, mixed $user_id = false ]) : mixed
Parameters
- $comment_str : mixed
-
The comment
- $user_id : mixed = false
-
The primary key of the user (instructor only)
setJson()
Set the JSON entry for this entity
public
setJson(mixed $json) : mixed
Parameters
- $json : mixed
-
This is a string - no validation is done
setJsonForUser()
Set JSON for a different user
public
setJsonForUser(mixed $json_str[, mixed $user_id = false ]) : The
Parameters
- $json_str : mixed
-
The JSON String
- $user_id : mixed = false
-
The primary key of the user (instructor only)
Return values
The —annotation array
setJsonKey()
Set/update a JSON key for this entity
public
setJsonKey(mixed $key, mixed $value) : mixed
Parameters
- $key : mixed
-
The key to be inserted/updated in the JSON
- $value : mixed
-
The value to be inserted/updated in the JSON
setJsonKeyForUser()
Set a JSON key for a result for a different user
public
setJsonKeyForUser(mixed $key, mixed $value[, mixed $user_id = false ]) : The
Parameters
- $key : mixed
-
The key to be set in the JSON
- $value : mixed
-
The value to store in the JSON
- $user_id : mixed = false
-
The primary key of the user (instructor only)
Return values
The —annotation array
setJsonKeys()
Set/update an array of JSON keys for this entity
public
setJsonKeys(mixed $values) : mixed
Parameters
- $values : mixed
-
An array of key/value pairs to be inserted/updated in the JSON
setNote()
The comment for this result. Writes lti_result.comment.
public
setNote(mixed $note_str[, mixed $user_id = false ]) : mixed
Parameters
- $note_str : mixed
-
The comment
- $user_id : mixed = false
-
The primary key of the user (instructor only)
numericSetting()
Coerce a link-setting value to a number.
private
static numericSetting(mixed $value[, mixed $default = 0 ]) : mixed
Parameters
- $value : mixed
- $default : mixed = 0
suppliedProgress()
A progress value from $extra. Absent or empty uses $default.
private
static suppliedProgress(mixed $extra, string $key, array<string|int, string> $allowed, string $default) : string|false
Any other value must be a recognized string, or this returns false.
Parameters
- $extra : mixed
- $key : string
- $allowed : array<string|int, string>
- $default : string