Tsugi

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_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'

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
string

claimVocabulary()

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
string

customParameterMap()

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
string

persistDocument()

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>|null

registrationLaunchUrl()

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
string

requestedClaims()

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>

decodeObject()

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
string

encodeJson()

private static encodeJson(mixed $value) : string
Parameters
$value : mixed
Return values
string

findRegistration()

private static findRegistration(int $registrationId) : array<string, mixed>|null
Parameters
$registrationId : int
Return values
array<string, mixed>|null

messageForLaunch()

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>|null

messageList()

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
int

optionalLabel()

private static optionalLabel(mixed $value, int $max, string $label) : string|null
Parameters
$value : mixed
$max : int
$label : string
Return values
string|null

optionalRegistrationId()

private static optionalRegistrationId(mixed $registrationId) : int|null
Parameters
$registrationId : mixed
Return values
int|null

optionalStatus()

private static optionalStatus(mixed $status) : int|null
Parameters
$status : mixed
Return values
int|null

placementNames()

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>

requireMessageRow()

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
int

scalarString()

private static scalarString(array<string, mixed> $message, string $key) : string|null
Parameters
$message : array<string, mixed>
$key : string
Return values
string|null

toolConfiguration()

private static toolConfiguration(array<string, mixed> $document) : array<string, mixed>|null
Parameters
$document : array<string, mixed>
Return values
array<string, mixed>|null

uniqueNames()

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>>

        
On this page

Search results