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
$context
public
Context|null
$context
$launchPresentation
LTI launch_presentation for this request. return_url is the back link.
public
LaunchPresentation|null
$launchPresentation
$link
public
Link|null
$link
$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
$membership
public
Membership|null
$membership
$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
$result
public
Result|null
$result
$user
public
User|null
$user
$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
intbeginAnonymousLessonView()
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|nullcurrentContextId()
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
intcurrentContextIdLegacy()
Current course id, or 0, from the same source as loggedInUserIdLegacy().
public
static currentContextIdLegacy() : int
Return values
intendAnonymousLessonView()
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
Return values
selffromInternalActivity()
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
selfisAnonymousLessonView()
True while a read-only lesson view is in effect.
public
static isAnonymousLessonView() : bool
Return values
boolisGoogleSession()
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
boolisLoggedIn()
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
boolisLoggedInLegacy()
True when loggedInUserIdLegacy() is non-zero.
public
static isLoggedInLegacy() : bool
A logged-in user does not need a course.
Return values
boolisLtiSession()
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
boolisPlusSession()
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
boolkeyId()
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
intlegacyAccessorNotes()
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
intloggedInUserIdLegacy()
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
intlogSessionDrift()
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
selfreplaceCourse()
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|nullreset()
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
setLink()
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
Tags
Return values
selfsetReturnUrl()
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
ContextensureResult()
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
ResultexistingContextId()
private
static existingContextId() : int
Return values
inthasLaunchPost()
True when a launch post is stored. Matches empty() on lti_post.
private
static hasLaunchPost() : bool
Return values
boolidentity()
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|nullloadUser()
private
static loadUser(int $user_id) : User|null
Parameters
- $user_id : int
Return values
User|nulllogContextChange()
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
intmembershipSnapshot()
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.
place()
private
static place(User|null $user, Context|null $context, Link|null $link, Result|null $result, Membership|null $membership, int|null $published) : self
Parameters
- $user : User|null
- $context : Context|null
- $link : Link|null
- $result : Result|null
- $membership : Membership|null
- $published : int|null
Return values
selfresolveContextId()
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
intuserOwnsContext()
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
boolwalkerId()
private
static walkerId(object $value) : string
Parameters
- $value : object
Return values
stringwalkerSame()
private
static walkerSame(mixed $a, mixed $b) : bool
Parameters
- $a : mixed
- $b : mixed
Return values
boolwalkerScalar()
private
static walkerScalar(mixed $value) : string
Parameters
- $value : mixed
Return values
stringwalkerScopeId()
private
static walkerScopeId(object|null $scope, string $slot) : int
Parameters
- $scope : object|null
- $slot : string
Return values
intwalkPair()
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>