Tsugi

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: array, resource_link_id: string}

cacheKey()

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

currentIsV2()

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

currentThemeArray()

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

currentThemeKey()

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
bool

encode()

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

loadRow()

public static loadRow(mixed $manifest_id) : array<string, mixed>|false
Parameters
$manifest_id : mixed
Return values
array<string, mixed>|false

navigationDocumentForContext()

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

normalizeShortTitle()

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

normalizeThemeKey()

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

palettes()

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

rememberInSession()

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
LessonsService

resetRequestCache()

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

validateJson()

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

collectRlidsFromList()

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
bool

loadJsonFromDatabase()

private static loadJsonFromDatabase(mixed $manifest_id) : string|false
Parameters
$manifest_id : mixed
Return values
string|false

positiveId()

private static positiveId(mixed $value) : int
Parameters
$value : mixed
Return values
int

pruneOldVersions()

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
Return values
array<string, mixed>|false

        
On this page

Search results