Manifest
in package
Versioned course manifest, keyed by immutable manifest_id.
File-based $CFG->lessons sites are unchanged: a context with no manifest_id keeps using the file. New courses get a manifest row; each save inserts a new row and points lti_context.manifest_id at it.
The lessons JSON (column manifest) is the course outline. New courses
start as Lessons JSON v2 (lessons_json_version: 2). File-backed
$CFG->lessons sites stay classic and are not authored. Do not grow that
blob with new course-setup features. New course-settings fields are independent
columns on this row (theme is a VARCHAR key; navigation is JSON).
The PHP session holds only the integer manifest_id. The immutable row (lessons JSON plus sibling columns) is loaded on demand and cached in Memcached (MCache) under a key derived from manifest_id, not context_id. Tsugi\Core\Cache is session-based and must not be used for this document. Older cache entries that stored a JSON string only are still accepted.
A resource-link read (store install, peer-grade inherit, Autograder, Google Classroom rlid) uses currentLessons(): the course manifest when this context has one, otherwise $CFG->lessons. CC export and admin install repos stay on the site file. Discussion items in the lessons page open the discussions controller for that resource_link_id.
Every new version is test-loaded with LessonsService::tryFromJson() before insert. After that version is stored and lti_context.manifest_id points at it, older versions for the course are deleted so only the ten newest rows remain. Authoring can export/import a lessons.json file; import is the same save path.
Outbound LTI launches from the lessons/discussions catalog (file vs manifest resource_link_id, custom, launch URL) are a later pass. Do not mix those behaviors in casually; parent-site launches and new-course launches will need an explicit design.
Table of Contents
Constants
- CACHE_TTL : mixed = 86400
- Memcached TTL in seconds; 0 means no expiry. Rows are immutable.
- RETAIN_VERSIONS : mixed = 10
- Newest manifest versions kept for a course. Older rows are deleted after a successful save.
- SHORT_TITLE_MAX : mixed = 64
- Stored length of lti_context.short_title.
Properties
- $mcache : MCache|object|null
- $requestJson : array<int, string>
- $requestRows : array<int, array<string, mixed>>
Methods
- activeId() : mixed
- Active manifest_id for this request (session only; 0 if file-backed or none).
-
appendDiscussion()
: array{data: array
, resource_link_id: string} - Append a course-level discussion to a decoded lessons document.
- cacheKey() : mixed
- Memcached key for an immutable manifest row.
- canAuthorCurrent() : mixed
- Authoring is only for a database-backed v2 course created via Courses.
- collectResourceLinkIds() : array<string, true>
- resource_link_id values already used in a decoded lessons document.
- createCourse() : array{ok: bool, context_id?: int, manifest_id?: int, error?: string}
- Create an LTI context, instructor membership, and a v2 starter manifest.
- currentDocument() : array{json: string, label: string, manifest_id: int, version: int}|false
- Raw JSON for authoring: manifest row or $CFG->lessons file.
- currentIsV2() : mixed
- True when the active course manifest is Lessons JSON v2 in the database.
- currentLessons() : LessonsService|false
- Lessons for the current context: manifest JSON if active, else $CFG->lessons file.
- currentThemeArray() : array<string, string>|null
- Raw palette for the active named theme, or null to keep $CFG->theme.
- currentThemeKey() : mixed
- Theme key stored on the active manifest row (empty string = site default).
- documentIsV2() : bool
- True when the decoded document is Lessons JSON v2.
- encode() : mixed
- Encode manifest JSON the same way file authoring does.
- exportFilename() : mixed
- Download filename for an exported lessons.json.
- hasCurrent() : mixed
- True if this request has a course document (active manifest or readable $CFG->lessons).
- idForContext() : mixed
- lti_context.manifest_id for a course, or 0.
- idsPastRetention() : array<int, int>
- Manifest ids to delete so a course keeps the newest versions.
- loadJson() : string|false
- JSON string for a manifest_id, or false if missing.
- loadRow() : array<string, mixed>|false
- navigationDocumentForContext() : array<string, mixed>
- Decoded navigation document for a context (CourseNav default if missing).
- navigationJsonForContext() : string|null
- Raw navigation JSON for a context's active manifest, or null if missing.
- normalizeShortTitle() : string|null|false
- Trim a short title. Null when absent. False when longer than SHORT_TITLE_MAX.
- normalizeThemeKey() : string|null|false
- Validate a posted theme key.
- palette() : array<string, string>|null
- Palette array for a theme key, without the display label. Null if unknown or site default.
- palettes() : array<string, array<string, string>>
- Named course palettes (legacy $CFG->theme shape).
- profileThemeKey() : string|null
- Palette key from a profile theme_override, or null to keep site/course theme.
- rememberInSession() : mixed
- Copy manifest_id into the session LTI blob (integer only).
- reorderDiscussions() : array<string, mixed>
- Reorder course discussions to match a list of resource_link_id values.
- requireCurrentLessons() : LessonsService
- Like {@see currentLessons()} but dies if neither a manifest nor a file is available.
- resetRequestCache() : mixed
- Drop request-local memoization (tests / identity switch).
- resolvedId() : mixed
- Manifest id for the current course: session, else lti_context.manifest_id.
- saveNewVersion() : int
- Insert an immutable new version and point lti_context.manifest_id at it.
- setActive() : mixed
- Point a context at an existing manifest row (must belong to that context).
- setMCache() : mixed
- Replace the MCache used by loadJson (tests). Pass null to rebuild from $CFG.
- siteDefaultPrimary() : mixed
- Nav primary color for the site default (no named course theme).
- starter() : array<string, mixed>
- Minimal Lessons JSON v2 document for a newly created course.
- syncContextTitle() : mixed
- Copy a course title onto lti_context.title (/courses reads this column).
- themeKeyForContext() : string|null
- Theme key currently pointed at by a context, or null.
- validateJson() : string|null
- Test-load a JSON string as Lessons. Returns an error message, or null if valid.
- collectRlidsFromList() : mixed
- discussionRlidBase() : mixed
- forgetCachedRow() : mixed
- Drop request memo and Memcached for a manifest row that was just deleted.
- hasDuplicateResourceLinkIds() : bool
- loadJsonFromDatabase() : string|false
- mcache() : MCache|object|null
- positiveId() : int
- pruneOldVersions() : mixed
- Drop versions beyond {@see RETAIN_VERSIONS} for one course.
- rememberCachedRow() : mixed
- Request memo plus MCache. Payload is the immutable row (JSON + theme).
- rememberRequest() : mixed
- rowFromCacheValue() : array<string, mixed>|false
- Cached MCache payload is a row array; older entries were a JSON string.
Constants
CACHE_TTL
Memcached TTL in seconds; 0 means no expiry. Rows are immutable.
public
mixed
CACHE_TTL
= 86400
RETAIN_VERSIONS
Newest manifest versions kept for a course. Older rows are deleted after a successful save.
public
mixed
RETAIN_VERSIONS
= 10
SHORT_TITLE_MAX
Stored length of lti_context.short_title.
public
mixed
SHORT_TITLE_MAX
= 64
Properties
$mcache
private
static MCache|object|null
$mcache
= null
Injected or lazy MCache; false means "constructed empty".
$requestJson
private
static array<int, string>
$requestJson
= array()
Request-local JSON strings keyed by manifest_id.
$requestRows
private
static array<int, array<string, mixed>>
$requestRows
= array()
Request-local manifest rows keyed by manifest_id.
Methods
activeId()
Active manifest_id for this request (session only; 0 if file-backed or none).
public
static activeId() : mixed
Use resolvedId() for the course document. This stays session-only so restoreSiteLoginContext() can tell a leftover sandbox from none.
appendDiscussion()
Append a course-level discussion to a decoded lessons document.
public
static appendDiscussion(array<string, mixed> $data, mixed $title[, mixed $launch = null ]) : array{data: array, resource_link_id: string}
Parameters
- $data : array<string, mixed>
- $title : mixed
- $launch : mixed = null
Return values
array{data: arraycacheKey()
Memcached key for an immutable manifest row.
public
static cacheKey(mixed $manifest_id) : mixed
Parameters
- $manifest_id : mixed
canAuthorCurrent()
Authoring is only for a database-backed v2 course created via Courses.
public
static canAuthorCurrent() : mixed
collectResourceLinkIds()
resource_link_id values already used in a decoded lessons document.
public
static collectResourceLinkIds(array<string, mixed> $data) : array<string, true>
Parameters
- $data : array<string, mixed>
Return values
array<string, true>createCourse()
Create an LTI context, instructor membership, and a v2 starter manifest.
public
static createCourse(mixed $title, mixed $user_id, mixed $key_id[, mixed $short_title = null ]) : array{ok: bool, context_id?: int, manifest_id?: int, error?: string}
When $short_title is set, the first six characters become the course navigation home label.
Parameters
- $title : mixed
- $user_id : mixed
- $key_id : mixed
- $short_title : mixed = null
Return values
array{ok: bool, context_id?: int, manifest_id?: int, error?: string}currentDocument()
Raw JSON for authoring: manifest row or $CFG->lessons file.
public
static currentDocument() : array{json: string, label: string, manifest_id: int, version: int}|false
Return values
array{json: string, label: string, manifest_id: int, version: int}|falsecurrentIsV2()
True when the active course manifest is Lessons JSON v2 in the database.
public
static currentIsV2() : mixed
File-backed $CFG->lessons and classic/v1 manifests are never authorable.
currentLessons()
Lessons for the current context: manifest JSON if active, else $CFG->lessons file.
public
static currentLessons([mixed $anchor = null ]) : LessonsService|false
Parameters
- $anchor : mixed = null
Return values
LessonsService|falsecurrentThemeArray()
Raw palette for the active named theme, or null to keep $CFG->theme.
public
static currentThemeArray() : array<string, string>|null
Return values
array<string, string>|nullcurrentThemeKey()
Theme key stored on the active manifest row (empty string = site default).
public
static currentThemeKey() : mixed
documentIsV2()
True when the decoded document is Lessons JSON v2.
public
static documentIsV2(mixed $decoded) : bool
Parameters
- $decoded : mixed
Return values
boolencode()
Encode manifest JSON the same way file authoring does.
public
static encode(array<string, mixed>|object $data) : mixed
Parameters
- $data : array<string, mixed>|object
exportFilename()
Download filename for an exported lessons.json.
public
static exportFilename(mixed $title[, mixed $version = 0 ][, mixed $date = null ]) : mixed
Includes V{n} when a manifest version is known, and the export date.
Parameters
- $title : mixed
- $version : mixed = 0
- $date : mixed = null
hasCurrent()
True if this request has a course document (active manifest or readable $CFG->lessons).
public
static hasCurrent() : mixed
idForContext()
lti_context.manifest_id for a course, or 0.
public
static idForContext(mixed $context_id) : mixed
Does not open a database connection. Callers that already have $PDOX (nested /courses/{id}, LTIX setup) get a lookup; unit tests do not.
Parameters
- $context_id : mixed
idsPastRetention()
Manifest ids to delete so a course keeps the newest versions.
public
static idsPastRetention(array<int, array<string, mixed>> $rows, int $protect_id[, int $keep = self::RETAIN_VERSIONS ]) : array<int, int>
$protect_id is the row just saved and activated. It is never deleted, even when that leaves one extra row.
Parameters
- $rows : array<int, array<string, mixed>>
-
Rows with manifest_id and version
- $protect_id : int
- $keep : int = self::RETAIN_VERSIONS
Return values
array<int, int>loadJson()
JSON string for a manifest_id, or false if missing.
public
static loadJson(mixed $manifest_id) : string|false
Lookup: request memo, then MCache, then database. Does not parse into Lessons.
Parameters
- $manifest_id : mixed
Return values
string|falseloadRow()
public
static loadRow(mixed $manifest_id) : array<string, mixed>|false
Parameters
- $manifest_id : mixed
Return values
array<string, mixed>|falsenavigationDocumentForContext()
Decoded navigation document for a context (CourseNav default if missing).
public
static navigationDocumentForContext(mixed $context_id) : array<string, mixed>
Parameters
- $context_id : mixed
Return values
array<string, mixed>navigationJsonForContext()
Raw navigation JSON for a context's active manifest, or null if missing.
public
static navigationJsonForContext(mixed $context_id) : string|null
Empty string and whitespace are treated as missing. A stored
{"items":[]} is returned as-is (teacher turned optional items off).
Parameters
- $context_id : mixed
Return values
string|nullnormalizeShortTitle()
Trim a short title. Null when absent. False when longer than SHORT_TITLE_MAX.
public
static normalizeShortTitle(mixed $short_title) : string|null|false
Parameters
- $short_title : mixed
Return values
string|null|falsenormalizeThemeKey()
Validate a posted theme key.
public
static normalizeThemeKey(mixed $key) : string|null|false
Parameters
- $key : mixed
Return values
string|null|false —Named key, null for site default, false if unknown.
palette()
Palette array for a theme key, without the display label. Null if unknown or site default.
public
static palette(mixed $key) : array<string, string>|null
Parameters
- $key : mixed
Return values
array<string, string>|nullpalettes()
Named course palettes (legacy $CFG->theme shape).
public
static palettes() : array<string, array<string, string>>
Keys are stored in manifest.theme. NULL / empty means the site $CFG->theme. Samples taken from peer tsugi_settings.php files (DJ4E, PG4E/CC4E, WS2), PY4E-AI ($CFG->theme_base / --ai-accent), plus the Tsugi default primary from Theme::defaults().
Return values
array<string, array<string, string>>profileThemeKey()
Palette key from a profile theme_override, or null to keep site/course theme.
public
static profileThemeKey(mixed $override) : string|null
Maps legacy light/dark overrides to the high-contrast palettes.
Parameters
- $override : mixed
Return values
string|nullrememberInSession()
Copy manifest_id into the session LTI blob (integer only).
public
static rememberInSession(mixed $manifest_id) : mixed
Parameters
- $manifest_id : mixed
reorderDiscussions()
Reorder course discussions to match a list of resource_link_id values.
public
static reorderDiscussions(array<string, mixed> $data, array<int, mixed> $ordered_rlids) : array<string, mixed>
Sets discussion_order (catalog display) and permutes the top-level discussions array. Unknown ids are ignored; discussions not in the list keep their relative order at the end.
Parameters
- $data : array<string, mixed>
- $ordered_rlids : array<int, mixed>
Return values
array<string, mixed>requireCurrentLessons()
Like {@see currentLessons()} but dies if neither a manifest nor a file is available.
public
static requireCurrentLessons([mixed $anchor = null ]) : LessonsService
Parameters
- $anchor : mixed = null
Return values
LessonsServiceresetRequestCache()
Drop request-local memoization (tests / identity switch).
public
static resetRequestCache() : mixed
resolvedId()
Manifest id for the current course: session, else lti_context.manifest_id.
public
static resolvedId() : mixed
Hydrates the session so later activeId() calls match. Nested /courses/{id} can already have the right context_id (Pages/Files work) while the session still has no manifest_id from Google login.
saveNewVersion()
Insert an immutable new version and point lti_context.manifest_id at it.
public
static saveNewVersion(mixed $context_id, array<string, mixed>|object|string $data[, mixed $user_id = null ][, mixed $comment = null ][, string|null $theme = null ][, mixed $navigation = null ]) : int
Versions older than RETAIN_VERSIONS are deleted only after this insert and setActive() succeed.
Parameters
- $context_id : mixed
- $data : array<string, mixed>|object|string
-
Decoded document or JSON string
- $user_id : mixed = null
- $comment : mixed = null
- $theme : string|null = null
-
Theme key. Null copies the previous version for this context. Empty string stores NULL (site $CFG->theme).
- $navigation : mixed = null
-
Navigation document or JSON. Null copies the previous version (or the CourseNav default when the previous value is empty).
Return values
int —New manifest_id
setActive()
Point a context at an existing manifest row (must belong to that context).
public
static setActive(mixed $context_id, mixed $manifest_id) : mixed
Parameters
- $context_id : mixed
- $manifest_id : mixed
setMCache()
Replace the MCache used by loadJson (tests). Pass null to rebuild from $CFG.
public
static setMCache(MCache|object|null $mcache) : mixed
Parameters
- $mcache : MCache|object|null
siteDefaultPrimary()
Nav primary color for the site default (no named course theme).
public
static siteDefaultPrimary() : mixed
Matches Output::get_theme() when manifest.theme is NULL: theme_base, then $CFG->theme primary, then the Tsugi default.
starter()
Minimal Lessons JSON v2 document for a newly created course.
public
static starter(mixed $title) : array<string, mixed>
Parameters
- $title : mixed
Return values
array<string, mixed>syncContextTitle()
Copy a course title onto lti_context.title (/courses reads this column).
public
static syncContextTitle(mixed $context_id, mixed $title) : mixed
When $context_id is the active context, also refresh session titles used by Tool::outboundContextTitle().
PDOX rewrites INSERT into ON DUPLICATE KEY UPDATE and only refreshes the primary key, so a colliding insert can leave the old title in place.
Parameters
- $context_id : mixed
- $title : mixed
themeKeyForContext()
Theme key currently pointed at by a context, or null.
public
static themeKeyForContext(mixed $context_id) : string|null
Parameters
- $context_id : mixed
Return values
string|nullvalidateJson()
Test-load a JSON string as Lessons. Returns an error message, or null if valid.
public
static validateJson(mixed $json) : string|null
Parameters
- $json : mixed
Return values
string|nullcollectRlidsFromList()
private
static collectRlidsFromList(mixed $list, array<string, true> &$ids[, mixed &$duplicate = false ]) : mixed
Parameters
- $list : mixed
- $ids : array<string, true>
- $duplicate : mixed = false
discussionRlidBase()
private
static discussionRlidBase(mixed $title) : mixed
Parameters
- $title : mixed
forgetCachedRow()
Drop request memo and Memcached for a manifest row that was just deleted.
private
static forgetCachedRow(int $manifest_id) : mixed
Parameters
- $manifest_id : int
hasDuplicateResourceLinkIds()
private
static hasDuplicateResourceLinkIds(array<string, mixed> $data) : bool
Parameters
- $data : array<string, mixed>
Return values
boolloadJsonFromDatabase()
private
static loadJsonFromDatabase(mixed $manifest_id) : string|false
Parameters
- $manifest_id : mixed
Return values
string|falsemcache()
private
static mcache() : MCache|object|null
Return values
MCache|object|nullpositiveId()
private
static positiveId(mixed $value) : int
Parameters
- $value : mixed
Return values
intpruneOldVersions()
Drop versions beyond {@see RETAIN_VERSIONS} for one course.
private
static pruneOldVersions(int $context_id, int $protect_id) : mixed
Runs only after the new version is validated, inserted, and set active.
Parameters
- $context_id : int
- $protect_id : int
rememberCachedRow()
Request memo plus MCache. Payload is the immutable row (JSON + theme).
private
static rememberCachedRow(array<string, mixed> $row) : mixed
Parameters
- $row : array<string, mixed>
rememberRequest()
private
static rememberRequest(mixed $id, array<string, mixed> $row) : mixed
Parameters
- $id : mixed
- $row : array<string, mixed>
rowFromCacheValue()
Cached MCache payload is a row array; older entries were a JSON string.
private
static rowFromCacheValue(mixed $cached) : array<string, mixed>|false
Parameters
- $cached : mixed