Tsugi

ReqScope
in package

Request-scoped Tsugi runtime state for one PHP request.

This is the non-LTI analogue of the objects an LTI launch leaves in $USER, $CONTEXT, $LINK, and $RESULT. It is not stored in the session and it does not read those globals to discover who the request is about. LTIX::session_start() calls provision() before it returns. The course peel calls replaceCourse() when the URL names a different course.

Table of Contents

Constants

GOOGLE_KEY  : mixed = 'google.com'
Same consumer key as CoursesService::GOOGLE_KEY.
ORIGIN_LTI  : mixed = 'lti'
Filled from a cookieless LTI tool session.
ORIGIN_SITE  : mixed = 'site'
Filled from a cookie site session (COOKIE_SESSION).
SESSION_GOOGLE  : mixed = 'google'
Google site login. Consumer key google.com, no launch post.
SESSION_LTI  : mixed = 'lti'
LTI tool launch. A stored launch post that is not Plus.
SESSION_NONE  : mixed = 'none'
No Google, Plus, or tool launch is stored in this session.
SESSION_PLUS  : mixed = 'plus'
Plus launch. Cookie session with plus_context_launch on the launch row.

Properties

$context  : Context|null
$launchPresentation  : LaunchPresentation|null
LTI launch_presentation for this request. return_url is the back link.
$link  : Link|null
$lti11  : bool
This request's stored launch is an LTI 1.1 launch. False when it is 1.3 or not an LTI launch.
$lti13  : bool
This request's stored launch is an LTI 1.3 launch. False when it is 1.1 or not an LTI launch.
$membership  : Membership|null
$origin  : string|null
How this request was identified. ORIGIN_SITE or ORIGIN_LTI.
$published  : int|null
Null when this request has no link. Otherwise 0 or 1 from lti_link.published.
$result  : Result|null
$user  : User|null
$values  : array<string, mixed>
Key/value pairs stored with set() for this PHP request.
$current  : self|null
$identity  : array<string, mixed>|null
Cached session-or-global user and course ids for this request.
$identityLogged  : bool
$notedContextId  : int
Course id noted before a full hydrate, usually by the /courses/{id} peel.
$returnUrl  : string|null
launch_presentation_return_url for this request. Survives a later hydrate.
$storedLti11  : bool
Whether the stored launch for this request is LTI 1.1. Survives hydrate.
$storedLti13  : bool
Whether the stored launch for this request is LTI 1.3. Survives hydrate.
$storedOrigin  : string|null
site or lti. Kept across replaceCourse() for this request.
$storedValues  : array<string, mixed>
Key/value pairs for this PHP request. Survives a later hydrate.

Methods

anonymousLessonContextId()  : int
Course being read anonymously, or 0.
beginAnonymousLessonView()  : mixed
Read one manifest course's lessons without joining that course.
current()  : self|null
The ReqScope hydrated earlier in this request, or null.
currentContextId()  : int
Course id already stored on this request, or 0.
currentContextIdLegacy()  : int
Current course id, or 0, from the same source as loggedInUserIdLegacy().
endAnonymousLessonView()  : mixed
End the read-only lesson view for this request.
establish()  : self
Load the user, course, and role onto this request. No link.
fromInternalActivity()  : mixed
get()  : mixed
The value stored for $key, or $default when $key was never set.
hydrate()  : self
Install an already-built set of model objects as this request's context.
isAnonymousLessonView()  : bool
True while a read-only lesson view is in effect.
isGoogleSession()  : bool
True for a Google site login.
isLoggedIn()  : bool
True when the user already stored on this request has a non-zero id.
isLoggedInLegacy()  : bool
True when loggedInUserIdLegacy() is non-zero.
isLtiSession()  : bool
True for an LTI tool launch that is not Plus.
isPlusSession()  : bool
True for the Plus launch stored in this session.
keyId()  : int
Tenant key id for this session, or 0.
legacyAccessorNotes()  : array<int, string>
Temporary. Compare loggedInUserIdLegacy(), currentContextIdLegacy(), and isLoggedInLegacy() with the user and course on this object. Remove with ReqScopeDebug around December 2026. LTI tools do not use these readers.
loggedInUserId()  : int
User id already stored on this request, or 0.
loggedInUserIdLegacy()  : int
Current Tsugi user id, or 0.
logSessionDrift()  : mixed
Temporary. Compare this request with the session user and course, and with the course id the caller would have passed to fromInternalActivity.
noteContext()  : mixed
Remember the course for this request.
noteLtiLaunch()  : mixed
Remember whether the stored launch row is LTI 1.1, LTI 1.3, or neither.
provision()  : self
Record as much identity as the caller already has.
replaceCourse()  : self|null
Keep the user session_start already recorded and point this request at $context_id.
reset()  : mixed
Drop the request-scoped object and the globals it installed.
resetIdentity()  : mixed
Drop the cached user and course ids so the next read sees the session again.
scopeWalker()  : array<int, string>
Temporary. Compare this request with a launch and list mismatches.
sessionType()  : string
Which login this session is.
set()  : mixed
Store a value for the rest of this PHP request.
setLink()  : self
Attach the link and result for the user already on this request.
setReturnUrl()  : mixed
Remember launch_presentation_return_url. Applied to the current object and to the next hydrate in this request.
alignLaunchLinkActivity()  : mixed
Launch stores link activity from the session row at launch time.
alignSiteLaunchMembership()  : mixed
A site session's launch membership keeps the role stored at login.
alignSiteLaunchUser()  : mixed
A site session's launch user is built from the stored LTI role.
assignGlobals()  : mixed
attachLtiVersion()  : mixed
attachReturnUrl()  : mixed
attachValues()  : mixed
contextFromRow()  : Context
Course row plus the tenant key Launch stores on context.key.
ensureResult()  : Result
Same insert launch uses: one lti_result row per (link_id, user_id).
existingContextId()  : int
hasLaunchPost()  : bool
True when a launch post is stored. Matches empty() on lti_post.
identity()  : array<string, mixed>
Session pair when a session user id is present, otherwise the global pair.
launchRow()  : array<string, mixed>
loadContext()  : Context|null
loadUser()  : User|null
logContextChange()  : mixed
First course id for this request is kept. A later different id is logged and ignored.
ltiField()  : mixed
ltiFieldInt()  : int
membershipSnapshot()  : array{id: int, role: int, instructor: bool}
Membership and role fromInternalActivity would store for this pair.
normalizePositiveId()  : int
place()  : self
resolveContextId()  : int
Course already on this request wins. Otherwise the id noted by the course peel, then the caller's id, then the session course.
userOwnsContext()  : bool
Course owner or the owner of the course's key. Same check as Membership::ensureInSession().
walkerId()  : string
walkerSame()  : bool
walkerScalar()  : string
walkerScopeId()  : int
walkPair()  : mixed

Constants

GOOGLE_KEY

Same consumer key as CoursesService::GOOGLE_KEY.

public mixed GOOGLE_KEY = 'google.com'

ORIGIN_LTI

Filled from a cookieless LTI tool session.

public mixed ORIGIN_LTI = 'lti'

ORIGIN_SITE

Filled from a cookie site session (COOKIE_SESSION).

public mixed ORIGIN_SITE = 'site'

SESSION_GOOGLE

Google site login. Consumer key google.com, no launch post.

public mixed SESSION_GOOGLE = 'google'

SESSION_LTI

LTI tool launch. A stored launch post that is not Plus.

public mixed SESSION_LTI = 'lti'

SESSION_NONE

No Google, Plus, or tool launch is stored in this session.

public mixed SESSION_NONE = 'none'

SESSION_PLUS

Plus launch. Cookie session with plus_context_launch on the launch row.

public mixed SESSION_PLUS = 'plus'

Properties

$launchPresentation

LTI launch_presentation for this request. return_url is the back link.

public LaunchPresentation|null $launchPresentation

$lti11

This request's stored launch is an LTI 1.1 launch. False when it is 1.3 or not an LTI launch.

public bool $lti11 = false

$lti13

This request's stored launch is an LTI 1.3 launch. False when it is 1.1 or not an LTI launch.

public bool $lti13 = false

$origin

How this request was identified. ORIGIN_SITE or ORIGIN_LTI.

public string|null $origin

$published

Null when this request has no link. Otherwise 0 or 1 from lti_link.published.

public int|null $published

$values

Key/value pairs stored with set() for this PHP request.

public array<string, mixed> $values = array()

$current

private static self|null $current = null

$identity

Cached session-or-global user and course ids for this request.

private static array<string, mixed>|null $identity = null

$identityLogged

private static bool $identityLogged = false

$notedContextId

Course id noted before a full hydrate, usually by the /courses/{id} peel.

private static int $notedContextId = 0

$returnUrl

launch_presentation_return_url for this request. Survives a later hydrate.

private static string|null $returnUrl = null

$storedLti11

Whether the stored launch for this request is LTI 1.1. Survives hydrate.

private static bool $storedLti11 = false

$storedLti13

Whether the stored launch for this request is LTI 1.3. Survives hydrate.

private static bool $storedLti13 = false

$storedOrigin

site or lti. Kept across replaceCourse() for this request.

private static string|null $storedOrigin = null

$storedValues

Key/value pairs for this PHP request. Survives a later hydrate.

private static array<string, mixed> $storedValues = array()

Methods

anonymousLessonContextId()

Course being read anonymously, or 0.

public static anonymousLessonContextId() : int
Return values
int

beginAnonymousLessonView()

Read one manifest course's lessons without joining that course.

public static beginAnonymousLessonView(int $context_id) : mixed

Does not write the session and does not create a membership. Course id readers report $context_id until endAnonymousLessonView().

Parameters
$context_id : int

current()

The ReqScope hydrated earlier in this request, or null.

public static current() : self|null
Return values
self|null

currentContextId()

Course id already stored on this request, or 0.

public static currentContextId() : int

Reads the course on ReqScope::current(). A missing course is 0. A logged-in user does not need a course. During an anonymous lesson view, this is the course being read.

Return values
int

currentContextIdLegacy()

Current course id, or 0, from the same source as loggedInUserIdLegacy().

public static currentContextIdLegacy() : int
Return values
int

endAnonymousLessonView()

End the read-only lesson view for this request.

public static endAnonymousLessonView() : mixed

establish()

Load the user, course, and role onto this request. No link.

public static establish(int $user_id, int $context_id) : self

The course peel calls this. A request that already has a user and a course is left as it is. Does not replace the LTI launch globals.

Parameters
$user_id : int
$context_id : int
Tags
throws
ReqScopeException
Return values
self

fromInternalActivity()

public static fromInternalActivity(mixed $user_id, mixed $context_id[, mixed $link_id = null ][, mixed $installGlobals = true ]) : mixed
Parameters
$user_id : mixed
$context_id : mixed
$link_id : mixed = null
$installGlobals : mixed = true

get()

The value stored for $key, or $default when $key was never set.

public static get(string $key[, mixed $default = null ]) : mixed
Parameters
$key : string
$default : mixed = null

hydrate()

Install an already-built set of model objects as this request's context.

public static hydrate(User $user, Context $context[, Link|null $link = null ][, Result|null $result = null ][, Membership|null $membership = null ][, int|null $published = null ][, mixed $installGlobals = true ]) : self

The globals $USER, $CONTEXT, $LINK, and $RESULT point at these same objects.

Parameters
$user : User
$context : Context
$link : Link|null = null
$result : Result|null = null
$membership : Membership|null = null
$published : int|null = null
$installGlobals : mixed = true
Return values
self

isAnonymousLessonView()

True while a read-only lesson view is in effect.

public static isAnonymousLessonView() : bool
Return values
bool

isGoogleSession()

True for a Google site login.

public static isGoogleSession() : bool

The consumer key is google.com and the session has no launch post. A Plus launch and a tool launch both store a launch post.

Return values
bool

isLoggedIn()

True when the user already stored on this request has a non-zero id.

public static isLoggedIn() : bool

A logged-in user does not need a course.

Return values
bool

isLoggedInLegacy()

True when loggedInUserIdLegacy() is non-zero.

public static isLoggedInLegacy() : bool

A logged-in user does not need a course.

Return values
bool

isLtiSession()

True for an LTI tool launch that is not Plus.

public static isLtiSession() : bool

The session has a stored launch post. Plus also has a launch post; plus_context_launch makes that session Plus instead.

Return values
bool

isPlusSession()

True for the Plus launch stored in this session.

public static isPlusSession() : bool

plus_context_launch is set by PlusShell::remember() and is left in place on site URLs. A Google login has no launch post, so it is not Plus.

Return values
bool

keyId()

Tenant key id for this session, or 0.

public static keyId() : int

Google login, a Plus launch, and a tool launch all store it on $_SESSION['lti']['key_id'] when the session is established. Later course changes leave that field in place. A session with no launch row has no key.

Return values
int

legacyAccessorNotes()

Temporary. Compare loggedInUserIdLegacy(), currentContextIdLegacy(), and isLoggedInLegacy() with the user and course on this object. Remove with ReqScopeDebug around December 2026. LTI tools do not use these readers.

public static legacyAccessorNotes() : array<int, string>
Return values
array<int, string>

loggedInUserId()

User id already stored on this request, or 0.

public static loggedInUserId() : int

Reads the user on ReqScope::current(). A missing user is 0.

Return values
int

loggedInUserIdLegacy()

Current Tsugi user id, or 0.

public static loggedInUserIdLegacy() : int

The session pair wins when $_SESSION['id'] is set. Otherwise $USER and $CONTEXT.

Return values
int

logSessionDrift()

Temporary. Compare this request with the session user and course, and with the course id the caller would have passed to fromInternalActivity.

public static logSessionDrift(int $context_id) : mixed

Logs a drift and does not change the request. Remove once the peel is trusted.

Parameters
$context_id : int

noteContext()

Remember the course for this request.

public static noteContext(int $context_id) : mixed

A course already on the current ReqScope is left as it is.

Parameters
$context_id : int

noteLtiLaunch()

Remember whether the stored launch row is LTI 1.1, LTI 1.3, or neither.

public static noteLtiLaunch(array<string, mixed>|null $row[, array<string, mixed>|null $post = null ]) : mixed

A 1.3 row has issuer_client, the same check Launch::isLTI13() uses. A 1.1 row is the basic launch message and is not 1.3. Anything else, including a site login row, is neither. Applied to the current object and to the next hydrate in this request.

Parameters
$row : array<string, mixed>|null

Session launch row, or null.

$post : array<string, mixed>|null = null

Original launch post, or null.

provision()

Record as much identity as the caller already has.

public static provision(int $user_id, int $context_id[, int|null $link_id = null ][, string|null $origin = null ]) : self

A missing user or a missing course is stored as null. Both ids load membership, role, and instructor. $link_id also loads the link and result. Does not replace the LTI launch globals. A failure is logged and the request keeps a partial object instead of dying.

Parameters
$user_id : int
$context_id : int
$link_id : int|null = null
$origin : string|null = null

ORIGIN_SITE or ORIGIN_LTI

Return values
self

replaceCourse()

Keep the user session_start already recorded and point this request at $context_id.

public static replaceCourse(int $context_id) : self|null

The same course is left as it is. A different course reloads membership, role, and instructor. No user means the call changes nothing.

Parameters
$context_id : int
Return values
self|null

reset()

Drop the request-scoped object and the globals it installed.

public static reset() : mixed

Tests use this. A normal request does not.

resetIdentity()

Drop the cached user and course ids so the next read sees the session again.

public static resetIdentity() : mixed

A course switch writes $_SESSION['context_id'] and then calls this.

scopeWalker()

Temporary. Compare this request with a launch and list mismatches.

public static scopeWalker(object|null $launch) : array<int, string>

Shared slots are user, context, membership, link, and result. A slot on only one side is a mismatch. When both sides have the slot, scalar public fields that differ are mismatches. Remove with ReqScopeDebug around December 2026.

Parameters
$launch : object|null
Return values
array<int, string>

sessionType()

Which login this session is.

public static sessionType() : string

Google, then Plus, then an LTI tool launch. Anything else is SESSION_NONE, including a cookie session that has not logged in.

Return values
string —

SESSION_GOOGLE, SESSION_PLUS, SESSION_LTI, or SESSION_NONE

set()

Store a value for the rest of this PHP request.

public static set(string $key, mixed $value) : mixed

A later provision() or replaceCourse() keeps the pair. reset() drops it.

Parameters
$key : string
$value : mixed

Attach the link and result for the user already on this request.

public static setLink(int|null $link_id) : self
Parameters
$link_id : int|null
throws
ReqScopeException
Return values
self

setReturnUrl()

Remember launch_presentation_return_url. Applied to the current object and to the next hydrate in this request.

public static setReturnUrl(string|null $url) : mixed
Parameters
$url : string|null

alignLaunchLinkActivity()

Launch stores link activity from the session row at launch time.

private static alignLaunchLinkActivity(Link|null $link) : mixed

Copy that snapshot onto this request's link when they are the same link.

Parameters
$link : Link|null

alignSiteLaunchMembership()

A site session's launch membership keeps the role stored at login.

private static alignSiteLaunchMembership(self $rc) : mixed

Copy the membership role loaded for this request when they are the same row.

Parameters
$rc : self

alignSiteLaunchUser()

A site session's launch user is built from the stored LTI role.

private static alignSiteLaunchUser(self $rc) : mixed

Course ownership and site admin live on this request's user, so copy instructor and admin onto the launch user with the same id.

Parameters
$rc : self

assignGlobals()

private static assignGlobals(self|null $rc) : mixed
Parameters
$rc : self|null

attachLtiVersion()

private static attachLtiVersion(self $rc) : mixed
Parameters
$rc : self

attachReturnUrl()

private static attachReturnUrl(self $rc) : mixed
Parameters
$rc : self

attachValues()

private static attachValues(self $rc) : mixed
Parameters
$rc : self

contextFromRow()

Course row plus the tenant key Launch stores on context.key.

private static contextFromRow(array<string, mixed> $row) : Context
Parameters
$row : array<string, mixed>
Return values
Context

ensureResult()

Same insert launch uses: one lti_result row per (link_id, user_id).

private static ensureResult(int $link_id, int $user_id) : Result
Parameters
$link_id : int
$user_id : int
Return values
Result

existingContextId()

private static existingContextId() : int
Return values
int

hasLaunchPost()

True when a launch post is stored. Matches empty() on lti_post.

private static hasLaunchPost() : bool
Return values
bool

identity()

Session pair when a session user id is present, otherwise the global pair.

private static identity() : array<string, mixed>
Return values
array<string, mixed>

launchRow()

private static launchRow() : array<string, mixed>
Return values
array<string, mixed>

loadContext()

private static loadContext(int $context_id) : Context|null
Parameters
$context_id : int
Return values
Context|null

loadUser()

private static loadUser(int $user_id) : User|null
Parameters
$user_id : int
Return values
User|null

logContextChange()

First course id for this request is kept. A later different id is logged and ignored.

private static logContextChange(int $existing, int $passed) : mixed
Parameters
$existing : int
$passed : int

ltiField()

private static ltiField(string $field) : mixed
Parameters
$field : string

ltiFieldInt()

private static ltiFieldInt(string $field) : int
Parameters
$field : string
Return values
int

membershipSnapshot()

Membership and role fromInternalActivity would store for this pair.

private static membershipSnapshot(int $user_id, int $context_id) : array{id: int, role: int, instructor: bool}

Does not change the current request.

Parameters
$user_id : int
$context_id : int
Return values
array{id: int, role: int, instructor: bool}

normalizePositiveId()

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

0 for missing, invalid, or non-positive values.

resolveContextId()

Course already on this request wins. Otherwise the id noted by the course peel, then the caller's id, then the session course.

private static resolveContextId(int $passed) : int
Parameters
$passed : int
Return values
int

userOwnsContext()

Course owner or the owner of the course's key. Same check as Membership::ensureInSession().

private static userOwnsContext(int $context_id, int $user_id) : bool
Parameters
$context_id : int
$user_id : int
Return values
bool

walkerId()

private static walkerId(object $value) : string
Parameters
$value : object
Return values
string

walkerSame()

private static walkerSame(mixed $a, mixed $b) : bool
Parameters
$a : mixed
$b : mixed
Return values
bool

walkerScalar()

private static walkerScalar(mixed $value) : string
Parameters
$value : mixed
Return values
string

walkerScopeId()

private static walkerScopeId(object|null $scope, string $slot) : int
Parameters
$scope : object|null
$slot : string
Return values
int

walkPair()

private static walkPair(mixed $path, object $left, object $right, array<int, string> &$notes) : mixed
Parameters
$path : mixed
$left : object
$right : object
$notes : array<int, string>

        
On this page

Search results