Settings
extends Tool
in package
Instructor settings: site-wide at /settings, course-mounted at /courses/{id}/settings.
Site-wide (wwwroot/settings): keys, contexts, PII expiry. Login is required; a course context is not. Do not call requireAuth() on those pages.
Course-mounted (/courses/{id}/settings): theme, navigation, images, badges, this course's configuration (course title, anonymous lessons), add, edit, and delete an LTI 1.1 tool for this course, Common Cartridge import/export, copy from another owned course, and delete course for the active manifest. Instructor + manifest only. Nested dispatch from Courses keeps REQUEST_URI prefixed, so isCourseRoute() can tell the two families apart. File-based $CFG->lessons sites keep using the site $CFG->theme.
Parent menus (site URLs only; instructors of a manifest course): if ( \Tsugi\Controllers\Settings::showInMenu() ) { $set->addLink('Settings', rtrim($CFG->apphome, '/') . '/settings'); }
Table of Contents
Constants
- CARTRIDGE_UPLOAD_MAX : mixed = '128M'
- Keep in sync with Controllers/util/upload/.user.ini and .htaccess
- CARTRIDGE_UPLOAD_PATH : mixed = '/lib/src/Controllers/util/upload/'
- COURSE_TITLE_MAX : mixed = 255
- Stored course title. lti_context.title is TEXT; this caps the form.
- NAME : mixed = 'Settings'
- REDIRECT : mixed = 'tsugi_controllers_settings'
- ROUTE : mixed = '/settings'
- SESSION_LESSONS_GRADE_REFRESH_AFTER_LAUNCH : mixed = 'tsugi_lessons_refresh_grades_on_view'
- When set after an outbound LTI 1.1 launch, the next {@see \Tsugi\Controllers\Lessons::get()} or {@see \Tsugi\Controllers\LaunchController::returnFromTool()} run clears the grade cache via {@see applyGradeRefreshAfterLaunchReturn()}.
Methods
- applyGradeRefreshAfterLaunchReturn() : mixed
- After an outbound LTI launch, if {@see SESSION_LESSONS_GRADE_REFRESH_AFTER_LAUNCH} is set, invalidate the current user's grade cache and clear the flag (next page load / return handler).
- badges() : mixed
- Course-mounted Settings: author the badges array on this manifest.
- cartridgeImportPageUrl() : string
- Course-mounted Settings import page (not derived from the uploader REQUEST_URI).
- cartridgeImportReturnUrl() : mixed
- Settings import page to return to after upload (session course if possible).
- cartridgeUploadContextIdFromRequest() : int
- Target course id from the uploader query, POST, or return URL.
- cartridgeUploadUrl() : mixed
- URL of the dedicated cartridge uploader (own PHP upload limits).
- checkCsrf() : bool
- True when the CSRF token is valid (fail closed). Flashes on failure.
- configuration() : mixed
- This course's title and anonymous-lessons switch.
- configuredHomeUrl() : string
- Site home for redirects: {@see ConfigInfo::$apphome} when set and non-empty, else {@see ConfigInfo::$wwwroot}.
- contextAdministrable() : array<string|int, mixed>|false
- Context row when the current user owns the context or its key.
- contextIndex() : mixed
- contextMailingList() : mixed
- contextMemberDetail() : mixed
- contextMembership() : mixed
- contextSettings() : mixed
- copy() : mixed
- Copy into this course: export another course to a cartridge, then import it.
- copyTabUrl() : string
- Course Copy tab URL derived from the Export tab URL (same session query).
- courseHeadingTitle() : string
- H1 for course-mounted Settings pages: current course title, else Settings.
- courseLocalPrefixes() : array<string|int, string>
- First path segments under the course base that are course content.
- csrfField() : string
- Hidden CSRF_TOKEN input for cookie-session HTML forms that POST to Tsugi.
- csrfOk() : bool
- True when POST CSRF_TOKEN (or X-CSRF-TOKEN) matches the session token, or the browser marks this POST as same-origin.
- csrfRedirect() : bool
- For classic PHP tools that redirect with header('Location').
- deleteCourse() : mixed
- Delete this course after the same domain, title, and member-count check as import wipe.
- deleteCourseInputError() : string|null
- Error when the typed domain, title, or member count does not match, else null.
- determineParentPath() : string
- Static helper to determine the parent path dynamically from the request
- determineToolHome() : string
- Static form of {@see toolHome()} for launch methods that have no instance.
- encrypt() : mixed
- exitPlusLeftCourse() : mixed
- Stop a Plus launch that opened a site tool.
- expireIndex() : mixed
- expirePiiDetail() : mixed
- expirePiiExpire() : mixed
- export() : mixed
- Common Cartridge export form for the current manifest course.
- exportDownload() : mixed
- Download a Common Cartridge built from the current course manifest.
- gclassLogin() : mixed
- handleCartridgeUploadPost() : RedirectResponse
- POST handler for Controllers/util/upload/index.php (large cartridge body).
- images() : mixed
- Course 16×9 hero and square icon (stored on context_images).
- import() : mixed
- Common Cartridge import form and upload for the current manifest course.
- importReplaceContent() : bool
- True when the instructor chose to wipe this course before import.
- importReplaceCourseTitle() : string
- Course title that must be typed to confirm a wipe-before-import.
- importReplaceDomainConfirmed() : bool
- True when $typed is this site's domain (scheme/path optional).
- importReplaceMemberCount() : int|null
- lti_membership rows for the current course, or null when unknown.
- importReplaceMembersConfirmed() : bool
- True when $typed is this course's membership count.
- importReplaceMembersMatch() : bool
- True when $typed is $count (commas and spaces ignored).
- importReplaceTitleConfirmed() : bool
- True when $typed is this course's title (trim, case, extra spaces ignored).
- importSiteDomain() : string
- Host of this site (apphome, else wwwroot), lowercase, no port.
- index() : mixed
- isCartridgeUploadRequest() : mixed
- True when this request is the dedicated Settings cartridge uploader.
- isCourseRoute() : mixed
- True when this request is /courses/{id}{route}... (not the unprefixed tool URL).
- isSafeImportReturn() : bool
- Same-site Settings import URL only (hidden form return field).
- joinToolHome() : string
- Join a mounted tool home and a suffix without producing `//path`.
- keyAuto() : mixed
- keyCount() : mixed
- keyDetail() : mixed
- keyIndex() : mixed
- keyRequestDetail() : mixed
- keyRequests() : mixed
- keyUsing() : mixed
- navigation() : mixed
- Course-mounted Settings: teacher-edited top navigation.
- normalizeCourseTitle() : string|null|false
- Trim a posted course title. Null when blank. False when longer than COURSE_TITLE_MAX.
- normalizeImportDomain() : string
- normalizeImportMembers() : int|null
- normalizeImportTitle() : string
- outboundContextTitle() : mixed
- Course title for an outbound LTI launch.
- plusLeftCourseApplies() : mixed
- True when this request is a Plus launch on a site URL.
- privacy() : mixed
- recent() : mixed
- requestPath() : string
- REQUEST_URI path with query stripped and a single leading slash.
- requireCsrf() : RedirectResponse|null
- Redirect back to $redirect when the CSRF token is missing or invalid.
- requireCsrfJson() : JsonResponse|null
- JSON 403 when the CSRF token is missing or invalid (no flash).
- requireOutboundLti11LaunchSession() : RedirectResponse|null
- Require LTI consumer session fields needed to sign an outbound LTI 1.1 launch.
- routes() : mixed
- sameOriginPost() : bool
- True when this request is a same-origin navigation (not a cross-site CSRF POST).
- selectedExportAnchors() : array<int, string>|false
- Module anchors selected on the export form, or false to include every module.
- selectedImportModules() : array<int, string>|false
- Organization keys from the import Select Content form, or false if none match.
- sendLti11LaunchFromContent() : RedirectResponse|string
- Sign a lesson launch from an lti_content row.
- sendLti11LaunchFromLessonsItem() : RedirectResponse|string
- Build and print the auto-submit HTML for an LTI 1.1 basic-lti-launch-request to a tool URL described by a lessons.json / lessons-items item (same shape as {@see \Tsugi\Services\Lessons\LessonsService::getLtiByRlid()}).
- settingsUrl() : mixed
- Absolute Settings URL under $CFG->wwwroot (not apphome).
- showInMenu() : mixed
- True when the current user may open course Settings (instructor of a manifest course).
- siteHomeCourseDeleteBlocked() : bool
- The Google site-login course is the app's home context. Do not delete it.
- statusHtml() : string
- HTML status blurb for the App Store (and similar).
- tools() : mixed
- Course-mounted Settings: add, edit, or delete an LTI 1.1 tool on this course.
- toolsAdd() : mixed
- Course-mounted Settings: the add and edit form for one LTI 1.1 tool.
- toolsDynamic() : mixed
- Course-mounted Settings: start IMS Dynamic Registration, or show the tool iframe.
- toolsDynamicDone() : mixed
- Leave the iframe page for the installed tool once registration is stored.
- toolsDynamicStatus() : mixed
- The iframe asks this after the tool sends org.imsglobal.lti.close.
- toolsEdit() : mixed
- Course-mounted Settings: edit one LTI 1.3 tool this course owns.
- toolsLaunchUrl() : mixed
- How many other tools in this tenant already use a launch URL.
- toolsLinks() : mixed
- Course-mounted Settings: every lti_content row, plus lesson links that are not provisioned yet.
- toolsManual() : mixed
- Course-mounted Settings: create an LTI 1.3 tool without dynamic registration.
- toolsTest() : mixed
- Course-mounted Settings: send a test launch for one tool on this course.
- toolsView() : mixed
- Course-mounted Settings: read-only view of one LTI 1.3 tool.
- tsugiRoot() : mixed
- appHomeUrl() : string
- App home (home_path, else apphome, else wwwroot).
- assetUrl() : mixed
- Alias for staticUrl() for backward compatibility
- controllerUrl() : string
- Generate URL to another controller
- courseFileBaseUrl() : string
- Current course base URL for Common Cartridge file-base rewriting.
- courseRequiredHtml() : string
- exitCourseRequired() : mixed
- A site tool such as grades was opened with no course.
- externalLinkAttrs() : array<string|int, mixed>
- Get link attributes for external vs same-site URLs
- isAdmin() : bool
- Check if the current user is a site administrator
- isInstructor() : bool
- Check if the current logged-in user is an instructor/admin for the current context
- leavePageReturnScript() : string
- Point Continue at this tab's launch return before footer scripts replace TSUGI_SESSION_DATA with the current page.
- lmsAnalyticsKey() : string
- Build a stable key for LMS analytics, distinct from LTI resource_link_id values.
- lmsAnalyticsPath() : string
- Build a stable path identifier for LMS tools (no query/session params).
- lmsEnsureAnalyticsLink() : int|false
- Ensure there is an `lti_link` row for a local LMS page/tool and return link_id.
- lmsRecordLaunchAnalytics() : int|false
- Record LMS page/tool "launch" into Tsugi internal analytics, mirroring LTIX behavior.
- pageUrl() : mixed
- plusLeftCourseHtml() : string
- renderLeavePage() : string
- Error page with Close Tab and Continue.
- requireAuth() : mixed
- Check authentication and context
- requireGlobalRoute() : RedirectResponse|null
- Bounce a course-mounted URL to a global (unprefixed) URL.
- requireInstructor() : bool
- Check if user is instructor/admin, redirect if not
- requireKeysEnabled() : RedirectResponse|null
- requireLogin() : RedirectResponse|null
- Login required, course context not required.
- requireSiteRoute() : RedirectResponse|null
- Site-wide Settings pages always live at wwwroot/settings.
- showAnalytics() : string
- Display analytics for an LMS tool
- staticUrl() : string
- Generate URL for a controller-specific static file (JS, CSS, etc.)
- toolHome() : string
- Get the base path for this tool (e.g., '/py4e/pages' or '/courses/2/pages')
- toolParent() : string
- Get the parent path one level above the tool home
- viewDueDates() : bool
- Whether the current user may see due dates in this context (lti_membership.viewDueDates).
- anonymousLessonsColumnReady() : mixed
- True when lti_context.anonymous_lessons exists.
- badgesPost() : mixed
- Save the badges array onto a new manifest version.
- classroomConnectionLabel() : mixed
- Account and class names for the settings line. Null when Classroom is not connected.
- configurationPost() : mixed
- Save this course's title or its anonymous lessons flag.
- configurationTitlePost() : RedirectResponse
- Save the course title onto a new manifest version and lti_context.title.
- copyPost() : RedirectResponse
- Export the chosen course into the copy stash, or run the import on that stash.
- courseGate() : RedirectResponse|null
- courseGet() : mixed
- Course-mounted Settings: theme picker for the current manifest.
- coursePost() : mixed
- Save the course theme onto a new manifest version.
- deleteCoursePost() : RedirectResponse
- POST: re-check the typed confirmation, delete the course, go to app home.
- echoImportPendingScript() : mixed
- Replace-confirmation script shared by Import and Course Copy.
- editWantsJson() : bool
- Turn off and delete on the LTI 1.3 editor post in place.
-
externalLinkPage()
: array{document: array
, rows: list >} - One row per placement. A content row used in two lesson items is two lines. Unplaced content is one line. Pages and assignments are not scanned yet.
- imagesPost() : mixed
- Save or clear one course image after server-side JPEG reconstruction.
- importPendingPost() : RedirectResponse
- Confirm, subset, or cancel a stashed cartridge (second request after upload or copy).
- importPost() : mixed
- Persist an uploaded Common Cartridge into this course.
- keyNav() : mixed
- mapPage() : mixed
- GET (and optional POST) plus trailing-slash and legacy .php URLs.
- navigationPost() : mixed
- Save course navigation onto a new manifest version.
- sameOriginParts() : bool
- Scheme, host, and effective port (not host alone).
- settingsContextId() : mixed
- Course the instructor is editing.
- toolEditUrl() : string
- toolQueryUrl() : string
- Session-bearing Settings URL plus the one-time registration token.
- toolsDynamicPost() : RedirectResponse
- toolsEditPost() : RedirectResponse|JsonResponse
- toolsManualPost() : RedirectResponse
- toolsPost() : mixed
- Add, update, or delete an LTI 1.1 tool on this course.
- toolViewUrl() : string
- Session-bearing URL for the read-only LTI 1.3 tool page.
Constants
CARTRIDGE_UPLOAD_MAX
Keep in sync with Controllers/util/upload/.user.ini and .htaccess
public
mixed
CARTRIDGE_UPLOAD_MAX
= '128M'
CARTRIDGE_UPLOAD_PATH
public
mixed
CARTRIDGE_UPLOAD_PATH
= '/lib/src/Controllers/util/upload/'
COURSE_TITLE_MAX
Stored course title. lti_context.title is TEXT; this caps the form.
public
mixed
COURSE_TITLE_MAX
= 255
NAME
public
mixed
NAME
= 'Settings'
REDIRECT
public
mixed
REDIRECT
= 'tsugi_controllers_settings'
ROUTE
public
mixed
ROUTE
= '/settings'
SESSION_LESSONS_GRADE_REFRESH_AFTER_LAUNCH
When set after an outbound LTI 1.1 launch, the next {@see \Tsugi\Controllers\Lessons::get()} or {@see \Tsugi\Controllers\LaunchController::returnFromTool()} run clears the grade cache via {@see applyGradeRefreshAfterLaunchReturn()}.
public
mixed
SESSION_LESSONS_GRADE_REFRESH_AFTER_LAUNCH
= 'tsugi_lessons_refresh_grades_on_view'
Methods
applyGradeRefreshAfterLaunchReturn()
After an outbound LTI launch, if {@see SESSION_LESSONS_GRADE_REFRESH_AFTER_LAUNCH} is set, invalidate the current user's grade cache and clear the flag (next page load / return handler).
public
static applyGradeRefreshAfterLaunchReturn() : mixed
badges()
Course-mounted Settings: author the badges array on this manifest.
public
badges(Request $request) : mixed
Parameters
- $request : Request
cartridgeImportPageUrl()
Course-mounted Settings import page (not derived from the uploader REQUEST_URI).
public
static cartridgeImportPageUrl(int $contextId) : string
Parameters
- $contextId : int
Return values
stringcartridgeImportReturnUrl()
Settings import page to return to after upload (session course if possible).
public
cartridgeImportReturnUrl() : mixed
cartridgeUploadContextIdFromRequest()
Target course id from the uploader query, POST, or return URL.
public
static cartridgeUploadContextIdFromRequest() : int
Return values
intcartridgeUploadUrl()
URL of the dedicated cartridge uploader (own PHP upload limits).
public
static cartridgeUploadUrl([int $contextId = 0 ]) : mixed
Parameters
- $contextId : int = 0
-
Course to import into (query string survives a discarded POST)
checkCsrf()
True when the CSRF token is valid (fail closed). Flashes on failure.
public
static checkCsrf() : bool
Return values
boolconfiguration()
This course's title and anonymous-lessons switch.
public
configuration(Request $request) : mixed
Parameters
- $request : Request
configuredHomeUrl()
Site home for redirects: {@see ConfigInfo::$apphome} when set and non-empty, else {@see ConfigInfo::$wwwroot}.
public
static configuredHomeUrl() : string
Return values
string —Non-empty path or URL (defaults to '/')
contextAdministrable()
Context row when the current user owns the context or its key.
public
static contextAdministrable(mixed $context_id) : array<string|int, mixed>|false
Parameters
- $context_id : mixed
Return values
array<string|int, mixed>|falsecontextIndex()
public
contextIndex(Request $request) : mixed
Parameters
- $request : Request
contextMailingList()
public
contextMailingList(Request $request) : mixed
Parameters
- $request : Request
contextMemberDetail()
public
contextMemberDetail(Request $request) : mixed
Parameters
- $request : Request
contextMembership()
public
contextMembership(Request $request) : mixed
Parameters
- $request : Request
contextSettings()
public
contextSettings(Request $request) : mixed
Parameters
- $request : Request
copy()
Copy into this course: export another course to a cartridge, then import it.
public
copy(Request $request) : mixed
Parameters
- $request : Request
copyTabUrl()
Course Copy tab URL derived from the Export tab URL (same session query).
public
static copyTabUrl(mixed $export_url) : string
Parameters
- $export_url : mixed
Return values
stringcourseHeadingTitle()
H1 for course-mounted Settings pages: current course title, else Settings.
public
static courseHeadingTitle() : string
Session first, then lti_context.title. Does not use $CFG->context_title.
Return values
stringcourseLocalPrefixes()
First path segments under the course base that are course content.
public
static courseLocalPrefixes() : array<string|int, string>
Passed into CCFileBase so that util does not know about controllers. Login, logout, admin, profile, and similar non-content routes are omitted.
Return values
array<string|int, string>csrfField()
Hidden CSRF_TOKEN input for cookie-session HTML forms that POST to Tsugi.
public
static csrfField() : string
Mints a session token if the current session does not have one yet (Google site login historically did not set CSRF_TOKEN; LTI launch does). Do not use this on LTI launches or signed webhooks.
Return values
stringcsrfOk()
True when POST CSRF_TOKEN (or X-CSRF-TOKEN) matches the session token, or the browser marks this POST as same-origin.
public
static csrfOk() : bool
Cookie-session pages (admin unlock) can lose the GET session cookie on the following POST; Chrome still sends Sec-Fetch-Site/Origin, which is enough to reject cross-site CSRF. LTI launches must not use this helper.
Return values
boolcsrfRedirect()
For classic PHP tools that redirect with header('Location').
public
static csrfRedirect(string $url) : bool
Parameters
- $url : string
-
Already session-bearing Location target.
Return values
bool —True when the caller should return (token was bad).
deleteCourse()
Delete this course after the same domain, title, and member-count check as import wipe.
public
deleteCourse(Request $request) : mixed
Parameters
- $request : Request
deleteCourseInputError()
Error when the typed domain, title, or member count does not match, else null.
public
static deleteCourseInputError(mixed $domain, mixed $title, mixed $members) : string|null
Same checks as wipe-before-import. Empty input never matches.
Parameters
- $domain : mixed
- $title : mixed
- $members : mixed
Return values
string|nulldetermineParentPath()
Static helper to determine the parent path dynamically from the request
public
static determineParentPath([string|null $route = null ]) : string
This is useful for static methods that need to determine the base path without having a Tool instance. It uses the same logic as toolParent() but works as a static method.
Parameters
- $route : string|null = null
-
Optional route to look for (if null, tries to detect from request)
Return values
string —The parent path (e.g., '/py4e' or '/ca4e/tsugi')
determineToolHome()
Static form of {@see toolHome()} for launch methods that have no instance.
public
static determineToolHome(string $route) : string
On a course-mounted page, a sibling tool keeps /courses/{id} even when
$route is not in this REQUEST_URI (Lessons → Quiz1).
Parameters
- $route : string
-
The route constant (e.g., '/discussions')
Return values
string —The mounted tool path (e.g., '/courses/2/discussions')
encrypt()
public
encrypt(Request $request) : mixed
Parameters
- $request : Request
exitPlusLeftCourse()
Stop a Plus launch that opened a site tool.
public
static exitPlusLeftCourse() : mixed
The Tsugi router calls this before every Tool action. A route that is a closure has to call it itself. The page offers the launch course, Log out, and Close Tab. Close Tab is disabled while the browser tries to close the window. If the tab is still open after three seconds, that button is removed and the page says it could not close.
expireIndex()
public
expireIndex(Request $request) : mixed
Parameters
- $request : Request
expirePiiDetail()
public
expirePiiDetail(Request $request) : mixed
Parameters
- $request : Request
expirePiiExpire()
public
expirePiiExpire(Request $request) : mixed
Parameters
- $request : Request
export()
Common Cartridge export form for the current manifest course.
public
export(Request $request) : mixed
Parameters
- $request : Request
exportDownload()
Download a Common Cartridge built from the current course manifest.
public
exportDownload(Request $request) : mixed
Parameters
- $request : Request
gclassLogin()
public
gclassLogin(Request $request) : mixed
Parameters
- $request : Request
handleCartridgeUploadPost()
POST handler for Controllers/util/upload/index.php (large cartridge body).
public
handleCartridgeUploadPost() : RedirectResponse
Re-binds the sandbox course because this URL is not /courses/{id}/...
Return values
RedirectResponseimages()
Course 16×9 hero and square icon (stored on context_images).
public
images(Request $request) : mixed
Parameters
- $request : Request
import()
Common Cartridge import form and upload for the current manifest course.
public
import(Request $request) : mixed
Parameters
- $request : Request
importReplaceContent()
True when the instructor chose to wipe this course before import.
public
static importReplaceContent(mixed $posted) : bool
Parameters
- $posted : mixed
-
Value of cc_replace from the pending-import form
Return values
boolimportReplaceCourseTitle()
Course title that must be typed to confirm a wipe-before-import.
public
static importReplaceCourseTitle() : string
Empty when the heading is missing or the Settings fallback.
Return values
stringimportReplaceDomainConfirmed()
True when $typed is this site's domain (scheme/path optional).
public
static importReplaceDomainConfirmed(mixed $typed) : bool
Parameters
- $typed : mixed
Return values
boolimportReplaceMemberCount()
lti_membership rows for the current course, or null when unknown.
public
static importReplaceMemberCount() : int|null
Zero is a real empty roster. Null means no course or the count could not be loaded.
Return values
int|nullimportReplaceMembersConfirmed()
True when $typed is this course's membership count.
public
static importReplaceMembersConfirmed(mixed $typed) : bool
Parameters
- $typed : mixed
Return values
boolimportReplaceMembersMatch()
True when $typed is $count (commas and spaces ignored).
public
static importReplaceMembersMatch(mixed $typed, int $count) : bool
Empty input never matches, including when $count is 0 — they must type 0.
Parameters
- $typed : mixed
- $count : int
Return values
boolimportReplaceTitleConfirmed()
True when $typed is this course's title (trim, case, extra spaces ignored).
public
static importReplaceTitleConfirmed(mixed $typed) : bool
Parameters
- $typed : mixed
Return values
boolimportSiteDomain()
Host of this site (apphome, else wwwroot), lowercase, no port.
public
static importSiteDomain() : string
Return values
stringindex()
public
index(Request $request) : mixed
Parameters
- $request : Request
isCartridgeUploadRequest()
True when this request is the dedicated Settings cartridge uploader.
public
static isCartridgeUploadRequest() : mixed
That script is a site URL, so restoreSiteLoginContext() would otherwise drop the sandbox course/manifest before import runs.
isCourseRoute()
True when this request is /courses/{id}{route}... (not the unprefixed tool URL).
public
static isCourseRoute([string|null $route = null ]) : mixed
Nested course dispatch rewrites pathInfo to $route but leaves REQUEST_URI unchanged, so this is the reliable split between a global tool URL and a course-mounted one. Do not use ReqScope::currentContextId() here — a global visit can still have a course in session.
Uses static::ROUTE unless $route is passed. Controllers without ROUTE return false unless $route is given.
Parameters
- $route : string|null = null
-
Tool path including leading slash (e.g. '/settings')
isSafeImportReturn()
Same-site Settings import URL only (hidden form return field).
public
static isSafeImportReturn(mixed $url) : bool
Parameters
- $url : mixed
Return values
booljoinToolHome()
Join a mounted tool home and a suffix without producing `//path`.
public
static joinToolHome(string $home, string $suffix) : string
Parameters
- $home : string
-
toolHome() result
- $suffix : string
-
id or extra path (leading slash optional)
Return values
stringkeyAuto()
public
keyAuto(Request $request) : mixed
Parameters
- $request : Request
keyCount()
public
static keyCount() : mixed
keyDetail()
public
keyDetail(Request $request) : mixed
Parameters
- $request : Request
keyIndex()
public
keyIndex(Request $request) : mixed
Parameters
- $request : Request
keyRequestDetail()
public
keyRequestDetail(Request $request) : mixed
Parameters
- $request : Request
keyRequests()
public
keyRequests(Request $request) : mixed
Parameters
- $request : Request
keyUsing()
public
keyUsing(Request $request) : mixed
Parameters
- $request : Request
navigation()
Course-mounted Settings: teacher-edited top navigation.
public
navigation(Request $request) : mixed
Parameters
- $request : Request
normalizeCourseTitle()
Trim a posted course title. Null when blank. False when longer than COURSE_TITLE_MAX.
public
static normalizeCourseTitle(mixed $raw) : string|null|false
Parameters
- $raw : mixed
Return values
string|null|falsenormalizeImportDomain()
public
static normalizeImportDomain(mixed $raw) : string
Parameters
- $raw : mixed
Return values
stringnormalizeImportMembers()
public
static normalizeImportMembers(mixed $raw) : int|null
Parameters
- $raw : mixed
Return values
int|nullnormalizeImportTitle()
public
static normalizeImportTitle(mixed $raw) : string
Parameters
- $raw : mixed
Return values
stringoutboundContextTitle()
Course title for an outbound LTI launch.
public
static outboundContextTitle() : mixed
Precedence: $_SESSION['context_title'], then the LTI session context_title, then $CFG->context_title.
Sending the site default here used to overwrite lti_context.title via adjustData.
plusLeftCourseApplies()
True when this request is a Plus launch on a site URL.
public
static plusLeftCourseApplies() : mixed
/courses/{id}/… still belongs to the launch. The course id stays in the session. A site tool that needs a course does not use it.
privacy()
public
privacy(Request $request) : mixed
Parameters
- $request : Request
recent()
public
recent(Request $request) : mixed
Parameters
- $request : Request
requestPath()
REQUEST_URI path with query stripped and a single leading slash.
public
static requestPath() : string
//courses is a protocol-relative URL (host "courses"). Apache/proxies
sometimes leave a doubled slash in REQUEST_URI; collapse it so tool
links stay /courses/123 instead of //courses/123.
Return values
stringrequireCsrf()
Redirect back to $redirect when the CSRF token is missing or invalid.
public
static requireCsrf(string $redirect) : RedirectResponse|null
Parameters
- $redirect : string
Return values
RedirectResponse|null —Null when the token is valid.
requireCsrfJson()
JSON 403 when the CSRF token is missing or invalid (no flash).
public
static requireCsrfJson([array<string|int, mixed>|null $payload = null ]) : JsonResponse|null
Parameters
- $payload : array<string|int, mixed>|null = null
Return values
JsonResponse|null —Null when the token is valid.
requireOutboundLti11LaunchSession()
Require LTI consumer session fields needed to sign an outbound LTI 1.1 launch.
public
static requireOutboundLti11LaunchSession(Application $app, mixed $redirect_path) : RedirectResponse|null
Parameters
- $app : Application
- $redirect_path : mixed
Return values
RedirectResponse|null —Null if session is sufficient; redirect with flash otherwise.
routes()
public
static routes(Application $app[, mixed $prefix = self::ROUTE ]) : mixed
Parameters
- $app : Application
- $prefix : mixed = self::ROUTE
sameOriginPost()
True when this request is a same-origin navigation (not a cross-site CSRF POST).
public
static sameOriginPost() : bool
Return values
boolselectedExportAnchors()
Module anchors selected on the export form, or false to include every module.
public
static selectedExportAnchors(object $l, mixed $anchor_str) : array<int, string>|false
Same rule as /cc/export: a missing, empty, or unmatched list is a full export.
Parameters
- $l : object
-
Lessons
- $anchor_str : mixed
-
Comma-separated anchors from ?anchors=
Return values
array<int, string>|falseselectedImportModules()
Organization keys from the import Select Content form, or false if none match.
public
static selectedImportModules(array<int, array{key: string}> $described, mixed $module_str) : array<int, string>|false
Parameters
- $described : array<int, array{key: string}>
- $module_str : mixed
Return values
array<int, string>|falsesendLti11LaunchFromContent()
Sign a lesson launch from an lti_content row.
public
static sendLti11LaunchFromContent(Application $app, array<string, mixed> $row, string $launch_presentation_return_url, string $redirect_path_on_error[, string|null $grade_refresh_session_key = null ]) : RedirectResponse|string
Parameters
- $app : Application
- $row : array<string, mixed>
- $launch_presentation_return_url : string
- $redirect_path_on_error : string
- $grade_refresh_session_key : string|null = null
Return values
RedirectResponse|stringsendLti11LaunchFromLessonsItem()
Build and print the auto-submit HTML for an LTI 1.1 basic-lti-launch-request to a tool URL described by a lessons.json / lessons-items item (same shape as {@see \Tsugi\Services\Lessons\LessonsService::getLtiByRlid()}).
public
static sendLti11LaunchFromLessonsItem(Application $app, object $lti, string $launch_presentation_return_url, string $redirect_path_on_error[, string $fallback_resource_link_title = '' ][, string|null $grade_refresh_session_key = null ]) : RedirectResponse|string
Parameters
- $app : Application
- $lti : object
-
Must have resource_link_id; launch is required for LTI tools (discussions POST to {wwwroot}/tool/tdiscus)
- $launch_presentation_return_url : string
-
Return URL after the external tool
- $redirect_path_on_error : string
-
Session addSession path for flash+redirect on failure
- $fallback_resource_link_title : string = ''
-
Used when $lti->title is missing
- $grade_refresh_session_key : string|null = null
-
If non-null, GradeUtil::invalidateGradesCurrentUser() and set this session key (typically self::SESSION_LESSONS_GRADE_REFRESH_AFTER_LAUNCH)
Return values
RedirectResponse|string —Empty string after HTML is printed; RedirectResponse on session failure only (caller handles other errors)
settingsUrl()
Absolute Settings URL under $CFG->wwwroot (not apphome).
public
static settingsUrl([mixed $suffix = '' ]) : mixed
Parameters
- $suffix : mixed = ''
showInMenu()
True when the current user may open course Settings (instructor of a manifest course).
public
static showInMenu() : mixed
siteHomeCourseDeleteBlocked()
The Google site-login course is the app's home context. Do not delete it.
public
static siteHomeCourseDeleteBlocked(int $context_id) : bool
Parameters
- $context_id : int
Return values
boolstatusHtml()
HTML status blurb for the App Store (and similar).
public
static statusHtml(mixed $key_count) : string
Parameters
- $key_count : mixed
Return values
stringtools()
Course-mounted Settings: add, edit, or delete an LTI 1.1 tool on this course.
public
tools(Request $request) : mixed
Parameters
- $request : Request
toolsAdd()
Course-mounted Settings: the add and edit form for one LTI 1.1 tool.
public
toolsAdd(Request $request) : mixed
Parameters
- $request : Request
toolsDynamic()
Course-mounted Settings: start IMS Dynamic Registration, or show the tool iframe.
public
toolsDynamic(Request $request) : mixed
Parameters
- $request : Request
toolsDynamicDone()
Leave the iframe page for the installed tool once registration is stored.
public
toolsDynamicDone(Request $request) : mixed
Parameters
- $request : Request
toolsDynamicStatus()
The iframe asks this after the tool sends org.imsglobal.lti.close.
public
toolsDynamicStatus(Request $request) : mixed
Parameters
- $request : Request
toolsEdit()
Course-mounted Settings: edit one LTI 1.3 tool this course owns.
public
toolsEdit(Request $request) : mixed
Parameters
- $request : Request
toolsLaunchUrl()
How many other tools in this tenant already use a launch URL.
public
toolsLaunchUrl(Request $request) : mixed
The course form uses this as a note. A matching URL is still saved.
Parameters
- $request : Request
toolsLinks()
Course-mounted Settings: every lti_content row, plus lesson links that are not provisioned yet.
public
toolsLinks(Request $request) : mixed
Choosing a deployment on a lesson placement posts place-lti, then saves content_id onto that item. Grades and the other launch fields post patch-lti. Pages and assignments will add placements the same way.
Parameters
- $request : Request
toolsManual()
Course-mounted Settings: create an LTI 1.3 tool without dynamic registration.
public
toolsManual(Request $request) : mixed
Parameters
- $request : Request
toolsTest()
Course-mounted Settings: send a test launch for one tool on this course.
public
toolsTest(Request $request) : mixed
Parameters
- $request : Request
toolsView()
Course-mounted Settings: read-only view of one LTI 1.3 tool.
public
toolsView(Request $request) : mixed
Parameters
- $request : Request
tsugiRoot()
public
static tsugiRoot() : mixed
appHomeUrl()
App home (home_path, else apphome, else wwwroot).
protected
static appHomeUrl() : string
Return values
stringassetUrl()
Alias for staticUrl() for backward compatibility
protected
assetUrl(mixed $filename[, mixed $controllerName = null ]) : mixed
Use staticUrl() instead
Parameters
- $filename : mixed
- $controllerName : mixed = null
controllerUrl()
Generate URL to another controller
protected
controllerUrl(string $controllerRoute[, string|null $currentRoute = null ]) : string
Parameters
- $controllerRoute : string
-
The route of the target controller (e.g., '/pages', '/announcements')
- $currentRoute : string|null = null
-
Optional current route (defaults to detecting from context)
Return values
string —Full URL to the controller
courseFileBaseUrl()
Current course base URL for Common Cartridge file-base rewriting.
protected
courseFileBaseUrl(string $route) : string
Example: https://host/py4e or https://host/courses/2
Parameters
- $route : string
-
The route constant for this tool (e.g. '/pages')
Return values
string —Course base with no trailing slash
courseRequiredHtml()
protected
courseRequiredHtml() : string
Return values
stringexitCourseRequired()
A site tool such as grades was opened with no course.
protected
exitCourseRequired() : mixed
Continue uses this tab's LTI return URL when one is stored, and the app home when it is not. A Plus launch never reaches this: the router stops it before the tool action.
externalLinkAttrs()
Get link attributes for external vs same-site URLs
protected
externalLinkAttrs(string $url[, string $linkLabel = 'Learn more' ]) : array<string|int, mixed>
Same-site links open in the current tab; external links get target="_blank" and rel="noopener noreferrer". Uses $CFG->apphome to determine same-site.
Parameters
- $url : string
-
The link URL
- $linkLabel : string = 'Learn more'
-
Optional label for aria-label (default: 'Learn more')
Return values
array<string|int, mixed> —['attrs' => string, 'aria_label' => string, 'external' => bool]
isAdmin()
Check if the current user is a site administrator
protected
isAdmin() : bool
Return values
bool —True if user is admin, false otherwise
isInstructor()
Check if the current logged-in user is an instructor/admin for the current context
protected
isInstructor() : bool
This method checks:
- If user is site admin (passphrase session)
- If user has instructor role or role_override in lti_membership table
- If user owns the context or its key
Reads context via ReqScope::currentContextId(); user id via ReqScope::loggedInUserId() (session or globals). Delegates to Membership::ensureInSession(), which caches a Membership instance in context-scoped session cache via Membership::ensureInSession() (single lti_membership SELECT when missing; ownership query only when role must be resolved).
Return values
bool —True if user is instructor/admin for the context, false otherwise
leavePageReturnScript()
Point Continue at this tab's launch return before footer scripts replace TSUGI_SESSION_DATA with the current page.
protected
static leavePageReturnScript(string $detail) : string
Same read and preference as Output::htmlError: error return, then return URL.
Parameters
- $detail : string
Return values
stringlmsAnalyticsKey()
Build a stable key for LMS analytics, distinct from LTI resource_link_id values.
protected
lmsAnalyticsKey([string|null $path = null ]) : string
Parameters
- $path : string|null = null
Return values
stringlmsAnalyticsPath()
Build a stable path identifier for LMS tools (no query/session params).
protected
lmsAnalyticsPath() : string
Examples:
- /lms/pages
- /lms/assignments
Return values
stringlmsEnsureAnalyticsLink()
Ensure there is an `lti_link` row for a local LMS page/tool and return link_id.
protected
lmsEnsureAnalyticsLink(int $context_id, string $link_key[, string|null $title = null ][, string|null $path = null ]) : int|false
We intentionally store LMS "tools" as synthetic lti_link records scoped to the
already-selected lti_context, so we can reuse the existing analytics tables
(lti_link_activity, lti_link_user_activity) without schema changes.
Parameters
- $context_id : int
- $link_key : string
- $title : string|null = null
- $path : string|null = null
Return values
int|falselmsRecordLaunchAnalytics()
Record LMS page/tool "launch" into Tsugi internal analytics, mirroring LTIX behavior.
protected
lmsRecordLaunchAnalytics(string $analytics_path[, string|null $title = null ]) : int|false
- Only records for learners (i.e., not instructors/admins)
- Stores data in lti_link_activity / lti_link_user_activity with event=0
Parameters
- $analytics_path : string
-
Required stable path for this tool (e.g., '/lms/pages')
- $title : string|null = null
-
Optional display title for this synthetic link
Return values
int|false —The link_id if successful, false otherwise
pageUrl()
protected
pageUrl([mixed $suffix = '' ]) : mixed
Parameters
- $suffix : mixed = ''
plusLeftCourseHtml()
protected
static plusLeftCourseHtml() : string
Return values
stringrenderLeavePage()
Error page with Close Tab and Continue.
protected
static renderLeavePage(array{title: string, paragraphs: array, home: string} $copy) : string
Continue starts at the app home. The page script points it at this tab's launch return when session storage has one.
Parameters
-
$copy
: array{title: string, paragraphs: array
, home: string}
Return values
stringrequireAuth()
Check authentication and context
protected
requireAuth() : mixed
Tags
requireGlobalRoute()
Bounce a course-mounted URL to a global (unprefixed) URL.
protected
requireGlobalRoute(string $globalUrl) : RedirectResponse|null
Parameters
- $globalUrl : string
-
Already session-bearing when the caller wants a session cookie
Return values
RedirectResponse|nullrequireInstructor()
Check if user is instructor/admin, redirect if not
protected
requireInstructor([string $redirectUrl = null ]) : bool
Parameters
- $redirectUrl : string = null
-
URL to redirect to if not authorized
Return values
bool —True if user is instructor/admin, false otherwise (and redirects)
requireKeysEnabled()
protected
requireKeysEnabled([mixed $instructorOnly = false ]) : RedirectResponse|null
Parameters
- $instructorOnly : mixed = false
Return values
RedirectResponse|nullrequireLogin()
Login required, course context not required.
protected
requireLogin([mixed $suffix = '' ]) : RedirectResponse|null
Parameters
- $suffix : mixed = ''
Return values
RedirectResponse|nullrequireSiteRoute()
Site-wide Settings pages always live at wwwroot/settings.
protected
requireSiteRoute([mixed $suffix = '' ]) : RedirectResponse|null
Parameters
- $suffix : mixed = ''
Return values
RedirectResponse|nullshowAnalytics()
Display analytics for an LMS tool
protected
showAnalytics(string $route[, string|null $title = null ]) : string
Automatically derives back_url and stable_path from the route.
Parameters
- $route : string
-
The route constant (e.g., '/pages', '/announcements')
- $title : string|null = null
-
Optional display title (defaults to route without leading slash, capitalized)
Return values
string —Empty string (outputs HTML directly)
staticUrl()
Generate URL for a controller-specific static file (JS, CSS, etc.)
protected
staticUrl(string $filename[, string|null $controllerName = null ]) : string
Static files are served from tsugi/lib/src/Controllers/static/{ControllerName}/ This method generates the proper URL for accessing these static files.
Parameters
- $filename : string
-
Static filename (e.g., 'tsugi-announce.js')
- $controllerName : string|null = null
-
Optional controller name (defaults to current controller)
Return values
string —Full URL to the static file
toolHome()
Get the base path for this tool (e.g., '/py4e/pages' or '/courses/2/pages')
protected
toolHome(string $route) : string
Looks at the current request URI and finds the tool's route within it, so nested mounts keep generating nested URLs.
Parameters
- $route : string
-
The route constant for this tool (e.g., '/pages', '/announcements')
Return values
string —The base path including the route (e.g., '/py4e/pages')
toolParent()
Get the parent path one level above the tool home
protected
toolParent([string $route = null ]) : string
This is useful for shared resources like static files that are mounted at a common path above individual controllers.
Parameters
- $route : string = null
-
The route constant for this tool (e.g., '/pages', '/announcements')
Return values
string —The parent path (e.g., '/py4e' if toolHome is '/py4e/pages')
viewDueDates()
Whether the current user may see due dates in this context (lti_membership.viewDueDates).
protected
viewDueDates() : bool
Loads Membership via ensureInSession(); for non-admins also calls isInstructor() so the same cached object is used for role checks in mixed call order.
Return values
boolanonymousLessonsColumnReady()
True when lti_context.anonymous_lessons exists.
private
static anonymousLessonsColumnReady() : mixed
badgesPost()
Save the badges array onto a new manifest version.
private
badgesPost(Request $request) : mixed
Parameters
- $request : Request
classroomConnectionLabel()
Account and class names for the settings line. Null when Classroom is not connected.
private
classroomConnectionLabel() : mixed
configurationPost()
Save this course's title or its anonymous lessons flag.
private
configurationPost() : mixed
configurationTitlePost()
Save the course title onto a new manifest version and lti_context.title.
private
configurationTitlePost(string $configuration_url) : RedirectResponse
Parameters
- $configuration_url : string
Return values
RedirectResponsecopyPost()
Export the chosen course into the copy stash, or run the import on that stash.
private
copyPost() : RedirectResponse
Return values
RedirectResponsecourseGate()
private
courseGate() : RedirectResponse|null
Return values
RedirectResponse|nullcourseGet()
Course-mounted Settings: theme picker for the current manifest.
private
courseGet(Request $request) : mixed
Parameters
- $request : Request
coursePost()
Save the course theme onto a new manifest version.
private
coursePost(Request $request) : mixed
Parameters
- $request : Request
deleteCoursePost()
POST: re-check the typed confirmation, delete the course, go to app home.
private
deleteCoursePost(Request $request) : RedirectResponse
Parameters
- $request : Request
Return values
RedirectResponseechoImportPendingScript()
Replace-confirmation script shared by Import and Course Copy.
private
echoImportPendingScript(bool $copyMode) : mixed
Parameters
- $copyMode : bool
editWantsJson()
Turn off and delete on the LTI 1.3 editor post in place.
private
static editWantsJson(Request $request) : bool
Add and the text saves still reload so the new markup can be rendered.
Parameters
- $request : Request
Return values
boolexternalLinkPage()
One row per placement. A content row used in two lesson items is two lines. Unplaced content is one line. Pages and assignments are not scanned yet.
private
static externalLinkPage(int $contextId) : array{document: array, rows: list>}
Parameters
- $contextId : int
Return values
array{document: arrayimagesPost()
Save or clear one course image after server-side JPEG reconstruction.
private
imagesPost(Request $request) : mixed
Parameters
- $request : Request
importPendingPost()
Confirm, subset, or cancel a stashed cartridge (second request after upload or copy).
private
importPendingPost(mixed $import_url, mixed $action[, string|null $sessionKey = null ]) : RedirectResponse
Parameters
- $import_url : mixed
- $action : mixed
- $sessionKey : string|null = null
-
Pending bucket. Course copy uses its own key.
Return values
RedirectResponseimportPost()
Persist an uploaded Common Cartridge into this course.
private
importPost(Request $request) : mixed
Parameters
- $request : Request
keyNav()
private
keyNav(mixed $active) : mixed
Parameters
- $active : mixed
mapPage()
GET (and optional POST) plus trailing-slash and legacy .php URLs.
private
static mapPage(Application $app, mixed $path, mixed $method, mixed $alsoPost) : mixed
Parameters
- $app : Application
- $path : mixed
- $method : mixed
- $alsoPost : mixed
navigationPost()
Save course navigation onto a new manifest version.
private
navigationPost(Request $request) : mixed
Parameters
- $request : Request
sameOriginParts()
Scheme, host, and effective port (not host alone).
private
static sameOriginParts(array<string, mixed> $a, array<string, mixed> $b) : bool
Parameters
- $a : array<string, mixed>
- $b : array<string, mixed>
Return values
boolsettingsContextId()
Course the instructor is editing.
private
static settingsContextId() : mixed
toolEditUrl()
private
static toolEditUrl(string $toolsUrl, int $registrationId) : string
Parameters
- $toolsUrl : string
- $registrationId : int
Return values
stringtoolQueryUrl()
Session-bearing Settings URL plus the one-time registration token.
private
toolQueryUrl(string $suffix, string $token) : string
Parameters
- $suffix : string
- $token : string
Return values
stringtoolsDynamicPost()
private
toolsDynamicPost(Request $request) : RedirectResponse
Parameters
- $request : Request
Return values
RedirectResponsetoolsEditPost()
private
toolsEditPost(Request $request) : RedirectResponse|JsonResponse
Parameters
- $request : Request
Return values
RedirectResponse|JsonResponsetoolsManualPost()
private
toolsManualPost(Request $request) : RedirectResponse
Parameters
- $request : Request
Return values
RedirectResponsetoolsPost()
Add, update, or delete an LTI 1.1 tool on this course.
private
toolsPost(Request $request) : mixed
Parameters
- $request : Request
toolViewUrl()
Session-bearing URL for the read-only LTI 1.3 tool page.
private
toolViewUrl(int $registrationId) : string
Parameters
- $registrationId : int