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'
FORMAT_VERSION
public
mixed
FORMAT_VERSION
= 2
KIND_QUIZ1
presentationKind for TYPE_QUIZ (LTI subtype quiz stays 'quiz').
public
mixed
KIND_QUIZ1
= 'quiz1'
SUBTYPE_ASSIGNMENT
public
mixed
SUBTYPE_ASSIGNMENT
= 'assignment'
SUBTYPE_AUTOGRADE
public
mixed
SUBTYPE_AUTOGRADE
= 'autograder'
SUBTYPE_DISCUSSION
public
mixed
SUBTYPE_DISCUSSION
= 'discussion'
SUBTYPE_PEER_GRADE
public
mixed
SUBTYPE_PEER_GRADE
= 'peer_grade'
SUBTYPE_QUIZ
public
mixed
SUBTYPE_QUIZ
= 'quiz'
SUBTYPE_REFERENCE
public
mixed
SUBTYPE_REFERENCE
= 'reference'
SUBTYPE_SECTION
public
mixed
SUBTYPE_SECTION
= 'section'
SUBTYPE_SLIDES
public
mixed
SUBTYPE_SLIDES
= 'slides'
SUBTYPE_SOLUTION
public
mixed
SUBTYPE_SOLUTION
= 'solution'
SUBTYPE_VIDEO
public
mixed
SUBTYPE_VIDEO
= 'video'
TYPE_DISCUSSION
public
mixed
TYPE_DISCUSSION
= 'discussion'
TYPE_FILE
public
mixed
TYPE_FILE
= 'file'
TYPE_HEADING
public
mixed
TYPE_HEADING
= 'heading'
TYPE_HTML_PAGE
public
mixed
TYPE_HTML_PAGE
= 'html_page'
TYPE_LTI
public
mixed
TYPE_LTI
= 'lti'
TYPE_QUIZ
Native Quiz1 quiz referenced by quiz_id. Not an LTI launch.
public
mixed
TYPE_QUIZ
= 'quiz'
TYPE_WEB_LINK
public
mixed
TYPE_WEB_LINK
= 'web_link'
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
stringasArray()
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
stringcollectItemFields()
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
stringiconKey()
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|nullinferLtiSubtype()
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|nullinvalidQuizIdError()
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|nullisAssignmentLti()
Graded LTI assignment rows (excludes discussion).
public
static isAssignmentLti(mixed $item) : bool
Parameters
- $item : mixed
Return values
boolisBuiltInDiscussionLaunch()
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
boolisDiscussion()
public
static isDiscussion(mixed $item) : bool
Parameters
- $item : mixed
Return values
boolisHeading()
public
static isHeading(mixed $item) : bool
Parameters
- $item : mixed
Return values
boolisLtiLaunch()
LTI launch item, including discussion (resource_link lookups).
public
static isLtiLaunch(mixed $item) : bool
Parameters
- $item : mixed
Return values
boolisNativeQuiz()
Native Quiz1 lesson item (not an LTI Gift quiz).
public
static isNativeQuiz(mixed $item) : bool
Parameters
- $item : mixed
Return values
boolisV2Document()
True when a decoded lessons document is Lessons JSON v2.
public
static isV2Document(mixed $doc) : bool
Parameters
- $doc : mixed
Return values
boollaunchUrlForItem()
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
stringnormalizeDocument()
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
objectparseQuizId()
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|nullpresentationKind()
Legacy presentation kind for icons, grouping, and getUrlResources.
public
static presentationKind(mixed $item) : string
Parameters
- $item : mixed
Return values
stringquizIdOf()
Quiz1 quiz_id on a native quiz item.
public
static quizIdOf(mixed $item) : int
Parameters
- $item : mixed
Return values
intsectionGroup()
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|nullserializeV2()
public
static serializeV2(array<string, mixed> $doc) : string
Parameters
- $doc : array<string, mixed>
Return values
stringsubtypeOf()
public
static subtypeOf(mixed $item) : string
Parameters
- $item : mixed
Return values
stringtypeOf()
public
static typeOf(mixed $item) : string
Parameters
- $item : mixed
Return values
stringapplyFileIdentity()
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
stringfilenameFromHref()
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|nullhrefOf()
private
static hrefOf(array<string, mixed> $item) : string
Parameters
- $item : array<string, mixed>
Return values
stringinvalidQuizIdErrorWalk()
private
static invalidQuizIdErrorWalk(array<int, mixed> $items) : string|null
Parameters
- $items : array<int, mixed>
Return values
string|nullmapLegacyToWebLink()
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|nullnonEmptyString()
private
static nonEmptyString(array<string, mixed> $item, mixed $key) : bool
Parameters
- $item : array<string, mixed>
- $key : mixed
Return values
boolorderDocument()
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