ToolRegistrationDocument
in package
Parsed Dynamic Registration state, plus the raw protocol log.
registration_json and lti_tool_message hold the current parsed document. lti_tool_message.sequence is the messages[] array index, starting at 0. A message placements array becomes one lti_tool_message_placement row per name. The message row is not repeated for each placement. message_json still keeps the original array. The log stores the exact payload text before any parse, including text that is not valid JSON. Deleting a registration removes its message rows and leaves the log rows, with registration_id set to null. Replacing the document deletes the message rows, which deletes their placements and any deployment enablement of those placements.
Table of Contents
Constants
- SCOPE_LINEITEM : mixed = 'https://purl.imsglobal.org/spec/lti-ags/scope/...
- SCOPE_LINEITEM_READONLY : mixed = 'https://purl.imsglobal.org/spec/lti-ags/scope/...
- SCOPE_RESULT : mixed = 'https://purl.imsglobal.org/spec/lti-ags/scope/...
- SCOPE_ROSTER : mixed = 'https://purl.imsglobal.org/spec/lti-nrps/scope...
- SCOPE_SCORE : mixed = 'https://purl.imsglobal.org/spec/lti-ags/scope/...
- TOOL_CONFIGURATION : mixed = 'https://purl.imsglobal.org/spec/lti-tool-confi...
- CLAIM_ORDER : array<int, string> = array('iss', 'sub', 'name', 'given_name', 'fami...
- SCOPE_ORDER : array<int, string> = array(self::SCOPE_SCORE, self::SCOPE_LINEITEM,...
Methods
- acceptPayload() : void
- Write the raw payload, then parse it. A parse failure leaves the log row in place and does not change the registration or its messages.
- appendLog() : int
- Append one raw payload. registration_id may be null before a registration row exists.
- appendMessageRow() : int
- Append one message at the next sequence and store its placements.
- attachLog() : void
- Point a log row that was written before the registration existed at that registration.
- canonicalMessageType() : string
- Message type used for a launch.
- claimVocabulary() : array<int, string>
- Claim names this registration knows how to store, in display order.
- customClaimName() : string
- Claim name for one stored custom parameter.
- customParameterMap() : array<string, string>
- String values from a custom_parameters object.
- deleteMessageRow() : void
- Delete one message and close the sequence gap after it.
- launchCustomParameters() : array<string, string>
- Custom parameters for one launch.
- logsForRegistration() : array<int, array<string, mixed>>
- Log rows for one registration, in the order they were appended.
- lti11Document() : array<string, mixed>
- The same document shape Dynamic Registration stores, built from LTI 1.1 checkboxes.
- messagesForRegistration() : array<int, array<string, mixed>>
- Messages in source-document order.
- messagesInDocument() : array<int, array<string, mixed>>
- Messages from the document, in source order.
- normalizeClaims() : array<int, string>
- normalizeScope() : string
- persistDocument() : void
- Write the parsed document without rebuilding message rows.
- registrationDocument() : array<string, mixed>|null
- The parsed registration document, or null when none has been stored.
- registrationLaunchUrl() : string
- The tool configuration target link. A message with none of its own uses this.
- requestedClaims() : array<int, string>
- Claims a deployment may allow. iss and sub are omitted because they are always sent.
- requestedScopes() : array<int, string>
- Scope URIs a deployment may allow.
- saveMessageRow() : void
- Replace the stored columns and message_json for one message.
- scopeVocabulary() : array<int, string>
- Scope URIs this registration knows how to store, in display order.
- storeDocument() : void
- Replace the parsed registration document and rebuild its message rows.
- withMessages() : array<string, mixed>
- Copy of the document with its messages array replaced.
- db() : PDOX
- decodeObject() : array<string, mixed>
- Decode a JSON object into an associative array.
- decodeStoredJson() : array<string, mixed>
- Same array decode as decodeObject().
- direction() : string
- encodeJson() : string
- findRegistration() : array<string, mixed>|null
- messageForLaunch() : array<string, mixed>|null
- messageList() : array<int, array<string, mixed>>
- Messages from a spec registration live inside the LTI tool configuration object. A document that has that object uses its messages array, including when the array is absent or empty. A document without that object may carry messages at the root. registration_json still stores the whole document either way.
- messageRow() : array<string, mixed>
- messagesValue() : mixed
- nextLogSequence() : int
- optionalLabel() : string|null
- optionalRegistrationId() : int|null
- optionalStatus() : int|null
- phase() : string
- placementNames() : array<int, string>
- Placement names from one message object. Absent or null means none.
- prefix() : string
- requireMessageRow() : array<string, mixed>
- requireRegistrationId() : int
- scalarString() : string|null
- toolConfiguration() : array<string, mixed>|null
- uniqueNames() : array<int, string>
- writeDocument() : void
Constants
SCOPE_LINEITEM
public
mixed
SCOPE_LINEITEM
= 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem'
SCOPE_LINEITEM_READONLY
public
mixed
SCOPE_LINEITEM_READONLY
= 'https://purl.imsglobal.org/spec/lti-ags/scope/lineitem.readonly'
SCOPE_RESULT
public
mixed
SCOPE_RESULT
= 'https://purl.imsglobal.org/spec/lti-ags/scope/result.readonly'
SCOPE_ROSTER
public
mixed
SCOPE_ROSTER
= 'https://purl.imsglobal.org/spec/lti-nrps/scope/contextmembership.readonly'
SCOPE_SCORE
public
mixed
SCOPE_SCORE
= 'https://purl.imsglobal.org/spec/lti-ags/scope/score'
TOOL_CONFIGURATION
public
mixed
TOOL_CONFIGURATION
= 'https://purl.imsglobal.org/spec/lti-tool-configuration'
CLAIM_ORDER
private
array<int, string>
CLAIM_ORDER
= array('iss', 'sub', 'name', 'given_name', 'family_name', 'email')
SCOPE_ORDER
private
array<int, string>
SCOPE_ORDER
= array(self::SCOPE_SCORE, self::SCOPE_LINEITEM, self::SCOPE_LINEITEM_READONLY, self::SCOPE_RESULT, self::SCOPE_ROSTER)
Methods
acceptPayload()
Write the raw payload, then parse it. A parse failure leaves the log row in place and does not change the registration or its messages.
public
static acceptPayload(int $registrationId, string $direction, string $phase, string $payloadText[, string|null $contentType = null ][, int|null $httpStatus = null ]) : void
Parameters
- $registrationId : int
- $direction : string
-
inbound or outbound
- $phase : string
- $payloadText : string
-
exact body, not reformatted
- $contentType : string|null = null
- $httpStatus : int|null = null
appendLog()
Append one raw payload. registration_id may be null before a registration row exists.
public
static appendLog(int|null $registrationId, string $direction, string $phase, string $payloadText[, string|null $contentType = null ][, int|null $httpStatus = null ]) : int
The text is stored unchanged.
Parameters
- $registrationId : int|null
- $direction : string
-
inbound or outbound
- $phase : string
- $payloadText : string
- $contentType : string|null = null
- $httpStatus : int|null = null
Return values
int —log_id
appendMessageRow()
Append one message at the next sequence and store its placements.
public
static appendMessageRow(int $registrationId, array<string, mixed> $message) : int
Parameters
- $registrationId : int
- $message : array<string, mixed>
Return values
int —message_id
attachLog()
Point a log row that was written before the registration existed at that registration.
public
static attachLog(int $logId, int $registrationId[, int|null $httpStatus = null ]) : void
Parameters
- $logId : int
- $registrationId : int
- $httpStatus : int|null = null
canonicalMessageType()
Message type used for a launch.
public
static canonicalMessageType(string $type) : string
The resource-link type in the specification is LtiResourceLinkRequest. A registration that says LtiResourceLink is stored as that message. The registration document keeps the type the tool sent.
Parameters
- $type : string
Return values
stringclaimVocabulary()
Claim names this registration knows how to store, in display order.
public
static claimVocabulary() : array<int, string>
iss and sub are included. They are always sent and are not a grant.
Return values
array<int, string>customClaimName()
Claim name for one stored custom parameter.
public
static customClaimName(string $name) : string
Lower case. A character that is not a letter or number becomes an underscore.
Parameters
- $name : string
Return values
stringcustomParameterMap()
String values from a custom_parameters object.
public
static customParameterMap(mixed $value) : array<string, string>
An empty object decodes as a list and means there are none.
Parameters
- $value : mixed
Return values
array<string, string>deleteMessageRow()
Delete one message and close the sequence gap after it.
public
static deleteMessageRow(int $registrationId, int $messageId) : void
Placements and deployment enablement of this message go with the row.
Parameters
- $registrationId : int
- $messageId : int
launchCustomParameters()
Custom parameters for one launch.
public
static launchCustomParameters(int $registrationId, string $messageType, string $targetLinkUri) : array<string, string>
Tool configuration parameters apply to every message. Parameters on the message replace a tool parameter with the same claim name. One message of this type is that message. Several messages of this type match by target link.
Parameters
- $registrationId : int
- $messageType : string
- $targetLinkUri : string
Return values
array<string, string>logsForRegistration()
Log rows for one registration, in the order they were appended.
public
static logsForRegistration(int|null $registrationId) : array<int, array<string, mixed>>
Null returns rows that were written before a registration existed, or whose registration has since been deleted. Those rows share a null registration_id, and each registration numbers sequence from zero, so this combined result is ordered by log_id. Ordering it by sequence would interleave unrelated exchanges.
Parameters
- $registrationId : int|null
Return values
array<int, array<string, mixed>>lti11Document()
The same document shape Dynamic Registration stores, built from LTI 1.1 checkboxes.
public
static lti11Document(string $launchUrl, array<int, array{type: string, placements: array}> $messages, mixed $claims, mixed $scopes) : array<string, mixed>
iss and sub are always requested. Name and email claims are added when asked. scope is the service URIs, space-separated, and is omitted when none are asked.
Parameters
- $launchUrl : string
-
$messages
: array<int, array{type: string, placements: array
}> - $claims : mixed
- $scopes : mixed
Return values
array<string, mixed>messagesForRegistration()
Messages in source-document order.
public
static messagesForRegistration(int $registrationId) : array<int, array<string, mixed>>
Parameters
- $registrationId : int
Return values
array<int, array<string, mixed>>messagesInDocument()
Messages from the document, in source order.
public
static messagesInDocument(array<string, mixed> $document) : array<int, array<string, mixed>>
Parameters
- $document : array<string, mixed>
Return values
array<int, array<string, mixed>>normalizeClaims()
public
static normalizeClaims(mixed $claims) : array<int, string>
Parameters
- $claims : mixed
Return values
array<int, string>normalizeScope()
public
static normalizeScope(mixed $scopes) : string
Parameters
- $scopes : mixed
Return values
stringpersistDocument()
Write the parsed document without rebuilding message rows.
public
static persistDocument(int $registrationId, array<string, mixed> $document) : void
Grants shrink to the claims and scopes still in the document. Message rows, their placements, and deployment enablement stay. storeDocument() is the call that replaces messages.
Parameters
- $registrationId : int
- $document : array<string, mixed>
registrationDocument()
The parsed registration document, or null when none has been stored.
public
static registrationDocument(int $registrationId) : array<string, mixed>|null
Parameters
- $registrationId : int
Return values
array<string, mixed>|nullregistrationLaunchUrl()
The tool configuration target link. A message with none of its own uses this.
public
static registrationLaunchUrl(int $registrationId) : string
Parameters
- $registrationId : int
Return values
stringrequestedClaims()
Claims a deployment may allow. iss and sub are omitted because they are always sent.
public
static requestedClaims(array<string, mixed> $document) : array<int, string>
Parameters
- $document : array<string, mixed>
Return values
array<int, string>requestedScopes()
Scope URIs a deployment may allow.
public
static requestedScopes(array<string, mixed> $document) : array<int, string>
Parameters
- $document : array<string, mixed>
Return values
array<int, string>saveMessageRow()
Replace the stored columns and message_json for one message.
public
static saveMessageRow(int $registrationId, int $messageId, array<string, mixed> $message) : void
The placement table is not changed here.
Parameters
- $registrationId : int
- $messageId : int
- $message : array<string, mixed>
scopeVocabulary()
Scope URIs this registration knows how to store, in display order.
public
static scopeVocabulary() : array<int, string>
Return values
array<int, string>storeDocument()
Replace the parsed registration document and rebuild its message rows.
public
static storeDocument(int $registrationId, array<string, mixed> $document) : void
Grants on deployments of this registration are reduced to claims and scopes that are still in the new document.
Parameters
- $registrationId : int
- $document : array<string, mixed>
-
parsed JSON object
withMessages()
Copy of the document with its messages array replaced.
public
static withMessages(array<string, mixed> $document, array<int, array<string, mixed>> $messages) : array<string, mixed>
The array is written where messageList() reads it.
Parameters
- $document : array<string, mixed>
- $messages : array<int, array<string, mixed>>
Return values
array<string, mixed>db()
private
static db() : PDOX
Return values
PDOXdecodeObject()
Decode a JSON object into an associative array.
private
static decodeObject(string $payloadText) : array<string, mixed>
The true argument stays. false would return stdClass, and the is_array checks in this service would reject a valid document. An empty object and an empty array are the same PHP array, so encode writes []. In this spec that is an empty custom_parameters. A lookup by name or by position finds nothing either way. A non-empty object or array keeps the type the spec names. The raw log still has the original text. Leave this flag alone unless outbound JSON is rebuilt from registration_json or message_json.
Parameters
- $payloadText : string
Return values
array<string, mixed>decodeStoredJson()
Same array decode as decodeObject().
private
static decodeStoredJson(mixed $value) : array<string, mixed>
Parameters
- $value : mixed
Return values
array<string, mixed>direction()
private
static direction(mixed $direction) : string
Parameters
- $direction : mixed
Return values
stringencodeJson()
private
static encodeJson(mixed $value) : string
Parameters
- $value : mixed
Return values
stringfindRegistration()
private
static findRegistration(int $registrationId) : array<string, mixed>|null
Parameters
- $registrationId : int
Return values
array<string, mixed>|nullmessageForLaunch()
private
static messageForLaunch(array<int, array<string, mixed>> $messages, string $messageType, string $targetLinkUri[, string $fallback = '' ]) : array<string, mixed>|null
Parameters
- $messages : array<int, array<string, mixed>>
- $messageType : string
- $targetLinkUri : string
- $fallback : string = ''
-
Target link of the registration. A message with none of its own uses it.
Return values
array<string, mixed>|nullmessageList()
Messages from a spec registration live inside the LTI tool configuration object. A document that has that object uses its messages array, including when the array is absent or empty. A document without that object may carry messages at the root. registration_json still stores the whole document either way.
private
static messageList(array<string, mixed> $document) : array<int, array<string, mixed>>
Parameters
- $document : array<string, mixed>
Return values
array<int, array<string, mixed>>messageRow()
private
static messageRow(int $sequence, array<string, mixed> $message) : array<string, mixed>
Parameters
- $sequence : int
- $message : array<string, mixed>
Return values
array<string, mixed>messagesValue()
private
static messagesValue(array<string, mixed> $document) : mixed
Parameters
- $document : array<string, mixed>
Return values
mixed —null when this document declares no messages
nextLogSequence()
private
static nextLogSequence(int|null $registrationId) : int
Parameters
- $registrationId : int|null
Return values
intoptionalLabel()
private
static optionalLabel(mixed $value, int $max, string $label) : string|null
Parameters
- $value : mixed
- $max : int
- $label : string
Return values
string|nulloptionalRegistrationId()
private
static optionalRegistrationId(mixed $registrationId) : int|null
Parameters
- $registrationId : mixed
Return values
int|nulloptionalStatus()
private
static optionalStatus(mixed $status) : int|null
Parameters
- $status : mixed
Return values
int|nullphase()
private
static phase(mixed $phase) : string
Parameters
- $phase : mixed
Return values
stringplacementNames()
Placement names from one message object. Absent or null means none.
private
static placementNames(array<string, mixed> $message, string $messageType) : array<int, string>
The names are checked here so a bad document fails before any row is written.
Parameters
- $message : array<string, mixed>
- $messageType : string
Return values
array<int, string>prefix()
private
static prefix() : string
Return values
stringrequireMessageRow()
private
static requireMessageRow(int $registrationId, int $messageId) : array<string, mixed>
Parameters
- $registrationId : int
- $messageId : int
Return values
array<string, mixed>requireRegistrationId()
private
static requireRegistrationId(mixed $registrationId) : int
Parameters
- $registrationId : mixed
Return values
intscalarString()
private
static scalarString(array<string, mixed> $message, string $key) : string|null
Parameters
- $message : array<string, mixed>
- $key : string
Return values
string|nulltoolConfiguration()
private
static toolConfiguration(array<string, mixed> $document) : array<string, mixed>|null
Parameters
- $document : array<string, mixed>
Return values
array<string, mixed>|nulluniqueNames()
private
static uniqueNames(mixed $values, string $label) : array<int, string>
Parameters
- $values : mixed
- $label : string
Return values
array<int, string>writeDocument()
private
static writeDocument(int $registrationId, string $encoded, array<int, array<string, mixed>> $rows) : void
Parameters
- $registrationId : int
- $encoded : string
- $rows : array<int, array<string, mixed>>