Search moodle.org's
Developer Documentation

See Release Notes

  • Bug fixes for general core bugs in 3.10.x will end 8 November 2021 (12 months).
  • Bug fixes for security issues in 3.10.x will end 9 May 2022 (18 months).
  • PHP version: minimum PHP 7.2.0 Note: minimum PHP version has increased since Moodle 3.8. PHP 7.3.x and 7.4.x are supported too.

Differences Between: [Versions 310 and 311] [Versions 310 and 400] [Versions 310 and 401] [Versions 310 and 402] [Versions 310 and 403]

Session manager class.

Copyright: 2013 Petr Skoda {@link http://skodak.org}
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1407 lines (52 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class


Class: manager  - X-Ref

Session manager, this is the public Moodle API for sessions.

Following PHP functions MUST NOT be used directly:
- session_start() - not necessary, lib/setup.php starts session automatically,
use define('NO_MOODLE_COOKIE', true) if session not necessary.
- session_write_close() - use \core\session\manager::write_close() instead.
- session_destroy() - use require_logout() instead.

restart_with_write_lock()   X-Ref
If the current session is not writeable, abort it, and re-open it
requesting (and blocking) until a write lock is acquired.
If current session was already opened with an intentional write lock,
this call will not do anything.
NOTE: Even when using a session handler that does not support non-locking sessions,
if the original session was not opened with the explicit intention of being locked,
this will still restart your session so that code behaviour matches as closely
as practical across environments.


start()   X-Ref
Start user session.

Note: This is intended to be called only from lib/setup.php!

start_session(bool $requireslock)   X-Ref
Handles starting a session.

param: bool $requireslock If this is false then no write lock will be acquired,

get_performance_info()   X-Ref
Returns current page performance info.

return: array perf info

get_handler_class()   X-Ref
Get fully qualified name of session handler class.

return: string The name of the handler class

load_handler()   X-Ref
Create handler instance.


init_empty_session()   X-Ref
Empty current session, fill it with not-logged-in user info.

This is intended for installation scripts, unit tests and other
special areas. Do NOT use for logout and session termination
in normal requests!

prepare_cookies()   X-Ref
Make sure all cookie and session related stuff is configured properly before session start.


initialise_user_session($newsid)   X-Ref
Initialise $_SESSION, handles google access
and sets up not-logged-in user properly.

WARNING: $USER and $SESSION are set up later, do not use them yet!

param: bool $newsid is this a new session in first http request?

add_session_record($userid)   X-Ref
Insert new empty session record.

param: int $userid
return: \stdClass the new record

check_security()   X-Ref
Do various session security checks.

WARNING: $USER and $SESSION are set up later, do not use them yet!

login_user(\stdClass $user)   X-Ref
Login user, to be called from complete_user_login() only.

param: \stdClass $user

should_use_samesite_none()   X-Ref
Returns a valid setting for the SameSite cookie attribute.

return: string The desired setting for the SameSite attribute on the cookie. Empty string indicates the SameSite attribute

append_samesite_cookie_attribute()   X-Ref
Conditionally append the SameSite attribute to the session cookie if necessary.

Contains a hack for versions of PHP lower than 7.3 as there is no API built into PHP cookie API
for adding the SameSite setting.

This won't change the Set-Cookie headers if:
- PHP 7.3 or higher is being used. That already adds the SameSite attribute without any hacks.
- If the samesite setting is empty.
- If the samesite setting is None but the browser is not compatible with that setting.

terminate_current()   X-Ref
Terminate current user session.

return: void

write_close()   X-Ref
No more changes in session expected.
Unblocks the sessions, other scripts may start executing in parallel.


session_exists($sid)   X-Ref
Does the PHP session with given id exist?

The session must exist both in session table and actual
session backend and the session must not be timed out.

Timeout evaluation is simplified, the auth hooks are not executed.

param: string $sid
return: bool

time_remaining($sid)   X-Ref
Return the number of seconds remaining in the current session.

param: string $sid

touch_session($sid)   X-Ref
Fake last access for given session, this prevents session timeout.

param: string $sid

kill_all_sessions()   X-Ref
Terminate all sessions unconditionally.


kill_session($sid)   X-Ref
Terminate give session unconditionally.

param: string $sid

kill_user_sessions($userid, $keepsid = null)   X-Ref
Terminate all sessions of given user unconditionally.

param: int $userid
param: string $keepsid keep this sid if present

apply_concurrent_login_limit($userid, $sid = null)   X-Ref
Terminate other sessions of current user depending
on $CFG->limitconcurrentlogins restriction.

This is expected to be called right after complete_user_login().

NOTE:
* Do not use from SSO auth plugins, this would not work.
* Do not use from web services because they do not have sessions.

param: int $userid
param: string $sid session id to be always keep, usually the current one
return: void

set_user(\stdClass $user)   X-Ref
Set current user.

param: \stdClass $user record

gc()   X-Ref
Periodic timed-out session cleanup.


is_loggedinas()   X-Ref
Is current $USER logged-in-as somebody else?

return: bool

get_realuser()   X-Ref
Returns the $USER object ignoring current login-as session

return: \stdClass user object

loginas($userid, \context $context, $generateevent = true)   X-Ref
Login as another user - no security checks here.

param: int $userid
param: \context $context
param: bool $generateevent Set to false to prevent the loginas event to be generated
return: void

keepalive($identifier = 'sessionerroruser', $component = 'error', $frequency = null, $timeout = 0)   X-Ref
Add a JS session keepalive to the page.

A JS session keepalive script will be called to update the session modification time every $frequency seconds.

Upon failure, the specified error message will be shown to the user.

param: string $identifier The string identifier for the message to show on failure.
param: string $component The string component for the message to show on failure.
param: int $frequency The update frequency in seconds.
param: int $timeout The timeout of each request in seconds.

create_login_token()   X-Ref
Generate a new login token and store it in the session.

return: array The current login state.

get_login_token()   X-Ref
Get the current login token or generate a new one.

All login forms generated from Moodle must include a login token
named "logintoken" with the value being the result of this function.
Logins will be rejected if they do not include this token as well as
the username and password fields.

return: string The current login token.

validate_login_token($token = false)   X-Ref
Check the submitted value against the stored login token.

param: mixed $token The value submitted in the login form that we are validating.
return: boolean If the submitted token is valid.

get_recent_session_locks()   X-Ref
Get the recent session locks array.

return: array Recent session locks array.

update_recent_session_locks($sessionlock)   X-Ref
Updates the recent session locks.

This function will store session lock info of all the pages visited.

param: array $sessionlock Session lock array.

cleanup_recent_session_locks()   X-Ref
Reset recent session locks array if there is a time gap more than SESSION_RESET_GAP_THRESHOLD.


get_locked_page_at($time)   X-Ref
Get the page that blocks other pages at a specific timestamp.

Look for a page whose lock was gained before that timestamp, and released after that timestamp.

param: float $time Time before session lock starts.
return: array|null

display_blocking_page()   X-Ref
Display the page which blocks other pages.

return: string

get_session_lock_info()   X-Ref
Get session lock info of the current page.

return: array

sessionlock_debugging()   X-Ref
Display debugging info about slow and blocked script.


array_session_diff(array $array1, array $array2)   X-Ref
Compares two arrays outputs the difference.

Note this does not use array_diff_assoc due to
the use of stdClasses in Moodle sessions.

param: array $array1
param: array $array2
return: array