Tsugi

LessonsNormalize
in package

Canonical Lessons item model and lossless legacy normalizer.

Foundational types: heading, web_link, html_page, file, discussion, lti, quiz. Lessons meaning stays on subtype (video, slides, assignment, quiz, ...). Native Quiz1 items are type quiz with quiz_id. LTI quizzes stay type lti + subtype quiz. Legacy lessons.json maps to web_link (plus subtype), never file or html_page.

Normalization is in-memory only. It does not rewrite stored lessons.json.

Table of Contents

Constants

BUILTIN_DISCUSSION_LAUNCH  : mixed = 'tsugi/tool/tdiscus'
Built-in Tsugi discussion tool path (under $CFG->wwwroot).
FORMAT_VERSION  : mixed = 2
KIND_QUIZ1  : mixed = 'quiz1'
presentationKind for TYPE_QUIZ (LTI subtype quiz stays 'quiz').
SUBTYPE_ASSIGNMENT  : mixed = 'assignment'
SUBTYPE_AUTOGRADE  : mixed = 'autograder'
SUBTYPE_DISCUSSION  : mixed = 'discussion'
SUBTYPE_PEER_GRADE  : mixed = 'peer_grade'
SUBTYPE_QUIZ  : mixed = 'quiz'
SUBTYPE_REFERENCE  : mixed = 'reference'
SUBTYPE_SECTION  : mixed = 'section'
SUBTYPE_SLIDES  : mixed = 'slides'
SUBTYPE_SOLUTION  : mixed = 'solution'
SUBTYPE_VIDEO  : mixed = 'video'
TYPE_DISCUSSION  : mixed = 'discussion'
TYPE_FILE  : mixed = 'file'
TYPE_HEADING  : mixed = 'heading'
TYPE_HTML_PAGE  : mixed = 'html_page'
TYPE_LTI  : mixed = 'lti'
TYPE_QUIZ  : mixed = 'quiz'
Native Quiz1 quiz referenced by quiz_id. Not an LTI launch.
TYPE_WEB_LINK  : mixed = 'web_link'

Properties

$documentKeyOrder  : array<int, string>
$extensionMime  : array<string, string>
$foundationalTypes  : array<int, string>
$inventDiscussionRlid  : mixed
When false, leave a missing discussion resource_link_id empty for a later unique fill.
$itemKeyOrder  : array<int, string>

Methods

allocateDiscussionRlid()  : string
Unused resource_link_id for a discussion title.
asArray()  : array<string, mixed>
builtinDiscussionLaunchUrl()  : string
Absolute URL of the built-in discussion tool ({wwwroot}/tool/tdiscus).
collectItemFields()  : array<int, array{path: string, key: string, value: mixed}>
Collect every scalar/array field under modules[].items[] (and nested items).
discussionRlidBase()  : string
Slug used when inventing a discussion resource_link_id from its title.
iconKey()  : string
Icon resolution: explicit icon, subtype, content_type, then foundational type.
inferContentType()  : string|null
inferLtiSubtype()  : string|null
Infer Lessons subtype from an LTI launch path. Does not override an explicit subtype.
invalidQuizIdError()  : string|null
Authoring-save error when a native quiz item has a quiz_id that is not a positive integer. Load/normalize drops invalid ids instead of failing.
isAssignmentLti()  : bool
Graded LTI assignment rows (excludes discussion).
isBuiltInDiscussionLaunch()  : bool
True when launch is the built-in Tsugi discussion tool (tsugi/tool/tdiscus).
isDiscussion()  : bool
isHeading()  : bool
isLtiLaunch()  : bool
LTI launch item, including discussion (resource_link lookups).
isNativeQuiz()  : bool
Native Quiz1 lesson item (not an LTI Gift quiz).
isV2Document()  : bool
True when a decoded lessons document is Lessons JSON v2.
launchUrlForItem()  : string
LTI endpoint for a lessons item. Type discussion always launches {wwwroot}/tool/tdiscus; other items use their stored launch.
normalizeDocument()  : array<string, mixed>
normalizeItem()  : array<string, mixed>
Normalize one lesson item. Unknown keys are copied through.
normalizeItemObject()  : object
parseQuizId()  : int|null
Positive Quiz1 id: int >= 1, or a digit string with no sign, decimal, or trailing junk.
presentationKind()  : string
Legacy presentation kind for icons, grouping, and getUrlResources.
quizIdOf()  : int
Quiz1 quiz_id on a native quiz item.
sectionGroup()  : string|null
Group key used by the lessons controller when it wraps items in a list.
serializeV2()  : string
subtypeOf()  : string
typeOf()  : string
applyFileIdentity()  : mixed
canonicalizeDiscussion()  : array<string, mixed>
Common Cartridge-shaped discussion: title, resource_link_id, optional description.
coerceLaunchPrivacy()  : void
Keep an explicit privacy choice. An absent key means the launch follows the tool grant.
collectAllResourceLinkIds()  : mixed
collectItemFieldsWalk()  : mixed
enrichCanonical()  : array<string, mixed>
ensureDiscussionResourceLinkIds()  : mixed
Fill missing discussion resource_link_id values and uniquify collisions.
ensurePageHref()  : mixed
Cartridge imports store page_id and logical_key without href.
ensureVideoHref()  : mixed
extensionOf()  : string
filenameFromHref()  : string|null
Human filename from a retrieval URL. Never uses a SHA-256 path segment.
hrefOf()  : string
invalidQuizIdErrorWalk()  : string|null
mapLegacyToWebLink()  : mixed
Legacy lessons.json has no file or html_page items — only href/url resources. Those become web_link plus a Lessons subtype. file and html_page are created only by new Lessons JSON v2 authoring.
mimeFromPath()  : string|null
nonEmptyString()  : bool
orderDocument()  : array<string, mixed>
orderKeys()  : array<string, mixed>
promoteHref()  : mixed
sha256Of()  : string|null

Constants

BUILTIN_DISCUSSION_LAUNCH

Built-in Tsugi discussion tool path (under $CFG->wwwroot).

public mixed BUILTIN_DISCUSSION_LAUNCH = 'tsugi/tool/tdiscus'

KIND_QUIZ1

presentationKind for TYPE_QUIZ (LTI subtype quiz stays 'quiz').

public mixed KIND_QUIZ1 = 'quiz1'

TYPE_QUIZ

Native Quiz1 quiz referenced by quiz_id. Not an LTI launch.

public mixed TYPE_QUIZ = 'quiz'

Properties

$documentKeyOrder

private static array<int, string> $documentKeyOrder = array('lessons_json_version', 'title', 'description', 'count', 'steps', 'required_modules', 'settings', 'headers', 'modules', 'badges', 'launches', 'discussions', 'discussion_order')

$extensionMime

private static array<string, string> $extensionMime = array('pdf' => 'application/pdf', 'pptx' => 'application/vnd.openxmlformats-officedocument.presentationml.presentation', 'ppt' => 'application/vnd.ms-powerpoint', 'docx' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'doc' => 'application/msword', 'xlsx' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'xls' => 'application/vnd.ms-excel', 'odp' => 'application/vnd.oasis.opendocument.presentation', 'odt' => 'application/vnd.oasis.opendocument.text', 'ods' => 'application/vnd.oasis.opendocument.spreadsheet', 'zip' => 'application/zip', 'png' => 'image/png', 'jpg' => 'image/jpeg', 'jpeg' => 'image/jpeg', 'gif' => 'image/gif', 'webp' => 'image/webp', 'mp4' => 'video/mp4', 'm4v' => 'video/x-m4v', 'webm' => 'video/webm', 'mov' => 'video/quicktime', 'mp3' => 'audio/mpeg', 'wav' => 'audio/wav', 'html' => 'text/html', 'htm' => 'text/html', 'md' => 'text/markdown', 'txt' => 'text/plain', 'json' => 'application/json', 'php' => 'text/html')

$foundationalTypes

private static array<int, string> $foundationalTypes = array(self::TYPE_HEADING, self::TYPE_WEB_LINK, self::TYPE_HTML_PAGE, self::TYPE_FILE, self::TYPE_DISCUSSION, self::TYPE_LTI, self::TYPE_QUIZ)

$inventDiscussionRlid

When false, leave a missing discussion resource_link_id empty for a later unique fill.

private static mixed $inventDiscussionRlid = true

$itemKeyOrder

private static array<int, string> $itemKeyOrder = array('type', 'subtype', 'title', 'description', 'text', 'level', 'class', 'tag', 'href', 'url', 'href_source', 'launch', 'resource_link_id', 'content_id', 'tool_deployment_id', 'quiz_id', 'page_id', 'logical_key', 'target', 'send_name', 'send_email', 'send_grade', 'result', 'due', 'custom', 'sha256', 'filename', 'path', 'content_type', 'icon', 'youtube', 'kaltura_id', 'media', 'note', 'notes', 'TODO', 'todo', 'review', 'project', 'FCP', 'FCPX', 'learning_objectives', 'items')

Methods

allocateDiscussionRlid()

Unused resource_link_id for a discussion title.

public static allocateDiscussionRlid(mixed $title, array<string, true> &$used) : string
Parameters
$title : mixed
$used : array<string, true>
Return values
string

asArray()

public static asArray(mixed $value) : array<string, mixed>
Parameters
$value : mixed
Return values
array<string, mixed>

builtinDiscussionLaunchUrl()

Absolute URL of the built-in discussion tool ({wwwroot}/tool/tdiscus).

public static builtinDiscussionLaunchUrl() : string
Return values
string

collectItemFields()

Collect every scalar/array field under modules[].items[] (and nested items).

public static collectItemFields(array<string, mixed> $doc) : array<int, array{path: string, key: string, value: mixed}>
Parameters
$doc : array<string, mixed>
Return values
array<int, array{path: string, key: string, value: mixed}>

discussionRlidBase()

Slug used when inventing a discussion resource_link_id from its title.

public static discussionRlidBase(mixed $title) : string
Parameters
$title : mixed
Return values
string

iconKey()

Icon resolution: explicit icon, subtype, content_type, then foundational type.

public static iconKey(mixed $item) : string
Parameters
$item : mixed
Return values
string —

Type key or fa-* class

inferContentType()

public static inferContentType(array<string, mixed> $item) : string|null
Parameters
$item : array<string, mixed>
Return values
string|null

inferLtiSubtype()

Infer Lessons subtype from an LTI launch path. Does not override an explicit subtype.

public static inferLtiSubtype(array<string, mixed> $item) : string|null
Parameters
$item : array<string, mixed>
Return values
string|null

invalidQuizIdError()

Authoring-save error when a native quiz item has a quiz_id that is not a positive integer. Load/normalize drops invalid ids instead of failing.

public static invalidQuizIdError(array<string, mixed> $doc) : string|null

Missing quiz_id is allowed (unsatisfied FK).

Parameters
$doc : array<string, mixed>
Return values
string|null

isAssignmentLti()

Graded LTI assignment rows (excludes discussion).

public static isAssignmentLti(mixed $item) : bool
Parameters
$item : mixed
Return values
bool

isBuiltInDiscussionLaunch()

True when launch is the built-in Tsugi discussion tool (tsugi/tool/tdiscus).

public static isBuiltInDiscussionLaunch(mixed $launch) : bool

Other tdiscus paths (for example mod/tdiscus/) do not match.

Parameters
$launch : mixed
Return values
bool

isDiscussion()

public static isDiscussion(mixed $item) : bool
Parameters
$item : mixed
Return values
bool

isHeading()

public static isHeading(mixed $item) : bool
Parameters
$item : mixed
Return values
bool

isLtiLaunch()

LTI launch item, including discussion (resource_link lookups).

public static isLtiLaunch(mixed $item) : bool
Parameters
$item : mixed
Return values
bool

isNativeQuiz()

Native Quiz1 lesson item (not an LTI Gift quiz).

public static isNativeQuiz(mixed $item) : bool
Parameters
$item : mixed
Return values
bool

isV2Document()

True when a decoded lessons document is Lessons JSON v2.

public static isV2Document(mixed $doc) : bool
Parameters
$doc : mixed
Return values
bool

launchUrlForItem()

LTI endpoint for a lessons item. Type discussion always launches {wwwroot}/tool/tdiscus; other items use their stored launch.

public static launchUrlForItem(mixed $item) : string
Parameters
$item : mixed
Return values
string

normalizeDocument()

public static normalizeDocument(mixed $doc) : array<string, mixed>
Parameters
$doc : mixed
Return values
array<string, mixed>

normalizeItem()

Normalize one lesson item. Unknown keys are copied through.

public static normalizeItem(array<string, mixed> $item) : array<string, mixed>
Parameters
$item : array<string, mixed>
Return values
array<string, mixed>

normalizeItemObject()

public static normalizeItemObject(mixed $item) : object
Parameters
$item : mixed
Return values
object

parseQuizId()

Positive Quiz1 id: int >= 1, or a digit string with no sign, decimal, or trailing junk.

public static parseQuizId(mixed $value) : int|null
Parameters
$value : mixed
Return values
int|null

presentationKind()

Legacy presentation kind for icons, grouping, and getUrlResources.

public static presentationKind(mixed $item) : string
Parameters
$item : mixed
Return values
string

quizIdOf()

Quiz1 quiz_id on a native quiz item.

public static quizIdOf(mixed $item) : int
Parameters
$item : mixed
Return values
int

sectionGroup()

Group key used by the lessons controller when it wraps items in a list.

public static sectionGroup(mixed $item) : string|null
Parameters
$item : mixed
Return values
string|null

serializeV2()

public static serializeV2(array<string, mixed> $doc) : string
Parameters
$doc : array<string, mixed>
Return values
string

subtypeOf()

public static subtypeOf(mixed $item) : string
Parameters
$item : mixed
Return values
string

typeOf()

public static typeOf(mixed $item) : string
Parameters
$item : mixed
Return values
string

applyFileIdentity()

private static applyFileIdentity(array<string, mixed> &$item) : mixed
Parameters
$item : array<string, mixed>

canonicalizeDiscussion()

Common Cartridge-shaped discussion: title, resource_link_id, optional description.

private static canonicalizeDiscussion(array<string, mixed> $item) : array<string, mixed>

Drop the implied tsugi/tool/tdiscus launch and a redundant discussion subtype.

Parameters
$item : array<string, mixed>
Return values
array<string, mixed>

coerceLaunchPrivacy()

Keep an explicit privacy choice. An absent key means the launch follows the tool grant.

private static coerceLaunchPrivacy(array<string, mixed> &$item) : void
Parameters
$item : array<string, mixed>

collectAllResourceLinkIds()

private static collectAllResourceLinkIds(array<string, mixed> $doc, array<string, true> &$used) : mixed
Parameters
$doc : array<string, mixed>
$used : array<string, true>

collectItemFieldsWalk()

private static collectItemFieldsWalk(array<int, mixed> $items, mixed $prefix, array<int, array{path: string, key: string, value: mixed}> &$out) : mixed
Parameters
$items : array<int, mixed>
$prefix : mixed
$out : array<int, array{path: string, key: string, value: mixed}>

enrichCanonical()

private static enrichCanonical(array<string, mixed> $item) : array<string, mixed>
Parameters
$item : array<string, mixed>
Return values
array<string, mixed>

ensureDiscussionResourceLinkIds()

Fill missing discussion resource_link_id values and uniquify collisions.

private static ensureDiscussionResourceLinkIds(array<string, mixed> &$doc) : mixed
Parameters
$doc : array<string, mixed>

ensurePageHref()

Cartridge imports store page_id and logical_key without href.

private static ensurePageHref(array<string, mixed> &$item) : mixed

The editor stores /pages/{logical_key}; Lessons expands that to the course.

Parameters
$item : array<string, mixed>

ensureVideoHref()

private static ensureVideoHref(array<string|int, mixed> &$item) : mixed
Parameters
$item : array<string|int, mixed>

extensionOf()

private static extensionOf(mixed $href) : string
Parameters
$href : mixed
Return values
string

filenameFromHref()

Human filename from a retrieval URL. Never uses a SHA-256 path segment.

private static filenameFromHref(mixed $href) : string|null
Parameters
$href : mixed
Return values
string|null

hrefOf()

private static hrefOf(array<string, mixed> $item) : string
Parameters
$item : array<string, mixed>
Return values
string

invalidQuizIdErrorWalk()

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

Legacy lessons.json has no file or html_page items — only href/url resources. Those become web_link plus a Lessons subtype. file and html_page are created only by new Lessons JSON v2 authoring.

private static mapLegacyToWebLink(array<string, mixed> &$item, string $subtype) : mixed
Parameters
$item : array<string, mixed>
$subtype : string

mimeFromPath()

private static mimeFromPath(mixed $path) : string|null
Parameters
$path : mixed
Return values
string|null

nonEmptyString()

private static nonEmptyString(array<string, mixed> $item, mixed $key) : bool
Parameters
$item : array<string, mixed>
$key : mixed
Return values
bool

orderDocument()

private static orderDocument(array<string, mixed> $doc) : array<string, mixed>
Parameters
$doc : array<string, mixed>
Return values
array<string, mixed>

orderKeys()

private static orderKeys(array<string, mixed> $data[, array<int, string>|null $preferred = null ]) : array<string, mixed>
Parameters
$data : array<string, mixed>
$preferred : array<int, string>|null = null
Return values
array<string, mixed>

promoteHref()

private static promoteHref(array<string, mixed> &$item) : mixed
Parameters
$item : array<string, mixed>

sha256Of()

private static sha256Of(array<string, mixed> $item, mixed $href) : string|null
Parameters
$item : array<string, mixed>
$href : mixed
Return values
string|null

        
On this page

Search results