phpBB API Documentation
Class

phpbb\user

class user extends session

Base user class

This is the overarching class which contains (through session extend) all methods utilised for user functionality during a session.

Properties

$cookie_data
$page
$data
$browser
$forwarded_for
$host
$session_id
$ip
$load
$time_now
$update_session_page
$lang
$help
$style
$date_format
$timezone DateTimeZone object holding the timezone of the user
$lang_name
$lang_id
$lang_path
$img_lang
$img_array
$keyoptions

Methods

extract_current_hostname()

Get valid hostname/port.

from session
session_begin(bool $update_session_page = true)

Start session management

from session
session_create($user_id = false, $set_admin = false, $persist_login = false, $viewonline = true)

Create a new session

from session
session_kill($new_session = true)

Kills a session

from session
session_gc()

Session garbage collection

from session
set_cookie(string $name, string $cookiedata, int $cookietime, bool $httponly = true)

Sets a cookie

from session
check_ban(int|false $user_id = false, mixed $user_ips = false, string|false $user_email = false, bool $return = false)

Check for banned user

from session
false check_dnsbl(string $mode, string|false $ip = false)

Check if ip is blacklisted This should be called only where absolutely necessary

from session
set_login_key($user_id = false, $key = false, $user_ip = false)

Set/Update a persistent login key

from session
reset_login_keys($user_id = false)

Reset all login keys for the specified user

from session
validate_referer(bool $check_script_path = false)

Check if the request originated from the same page.

from session
unset_admin()

from session
update_session(array $session_data, string $session_id = null)

Update the session data

from session
update_session_infos()

from session
__construct(string $datetime_class)

Constructor to set the lang path

set_custom_lang_path(string $lang_path)

Function to set custom language path (able to use directory outside of phpBB)

setup($lang_set = false, $style_id = false)

Setup basic user-specific items (style, language, ...)

lang()

More advanced language substitution Function to mimic sprintf() with the possibility of using phpBB's language system to substitute nullar/singular/plural forms.

int get_plural_form($number $number, $force_rule $force_rule = false)

Determine which plural form we should use.

add_lang(mixed $lang_set, bool $use_db = false, bool $use_help = false, string $ext_name = '')

Add Language Items - usedb and usehelp are assigned where needed (only use them to force inclusion)

add_lang_ext(string $ext_name, mixed $lang_set, bool $use_db = false, bool $use_help = false)

Add Language Items from an extension - usedb and usehelp are assigned where needed (only use them to force inclusion)

set_lang($lang, $help, $lang_file, $use_db = false, $use_help = false, $ext_name = '')

Set language entry (called by add_lang)

mixed format_date(int $gmepoch, string $format = false, bool $forcedate = false)

Format user date

datetime create_datetime(string $time = 'now', DateTimeZone $timezone = null)

Create a \phpbb\datetime object in the context of the current user

get_timestamp_from_format($format, $time, DateTimeZone $timezone = null)

Get the UNIX timestamp for a datetime in the users timezone, so we can store it in the database.

get_iso_lang_id()

Get language id currently used by the user

get_profile_fields($user_id)

Get users profile fields

img($img, $alt = '')

Specify/Get image

bool optionget(int $key, int $data = false)

Get option bit field from user options.

int|bool optionset(int $key, bool $value, int $data = false)

Set option bit field for user options.

leave_newly_registered()

Funtion to make the user leave the NEWLY_REGISTERED system group.

array get_passworded_forums()

Returns all password protected forum ids the user is currently NOT authenticated for.

Details

in session at line 155
public extract_current_hostname()

Get valid hostname/port.

HTTPHOST is used, SERVERNAME if HTTP_HOST not present.

in session at line 219
public session_begin(bool $update_session_page = true)

Start session management

This is where all session activity begins. We gather various pieces of information from the client and server. We test to see if a session already exists. If it does, fine and dandy. If it doesn't we'll go on to create a new one ... pretty logical heh? We also examine the system load (if we're running on a system which makes such information readily available) and halt if it's above an admin definable limit.

Parameters

bool $update_session_page if true the session page gets updated. This can be set to circumvent certain scripts to update the users last visited page.

in session at line 500
public session_create($user_id = false, $set_admin = false, $persist_login = false, $viewonline = true)

Create a new session

If upon trying to start a session we discover there is nothing existing we jump here. Additionally this method is called directly during login to regenerate the session for the specific user. In this method we carry out a number of tasks; garbage collection, (search)bot checking, banned user comparison. Basically though this method will result in a new session for a specific user.

Parameters

$user_id
$set_admin
$persist_login
$viewonline

in session at line 876
public session_kill($new_session = true)

Kills a session

This method does what it says on the tin. It will delete a pre-existing session. It resets cookie information (destroying any autologin key within that cookie data) and update the users information from the relevant session data. It will then grab guest user information.

Parameters

$new_session

in session at line 967
public session_gc()

Session garbage collection

This looks a lot more complex than it really is. Effectively we are deleting any sessions older than an admin definable limit. Due to the way in which we maintain session data we have to ensure we update user data before those sessions are destroyed. In addition this method removes autologin key information that is older than an admin defined limit.

Sets a cookie

Sets a cookie of the given name with the specified data for the given length of time. If no time is specified, a session cookie will be set.

Parameters

string $name Name of the cookie, will be automatically prefixed with the phpBB cookie name. track becomes [cookiename]track then.
string $cookiedata The data to hold within the cookie
int $cookietime The expiration time as UNIX timestamp. If 0 is provided, a session cookie is set.
bool $httponly Use HttpOnly. Defaults to true. Use false to make cookie accessible by client-side scripts.

in session at line 1081
public check_ban(int|false $user_id = false, mixed $user_ips = false, string|false $user_email = false, bool $return = false)

Check for banned user

Checks whether the supplied user is banned by id, ip or email. If no parameters are passed to the method pre-existing session data is used.

Parameters

int|false $user_id The user id
mixed $user_ips Can contain a string with one IP or an array of multiple IPs
string|false $user_email The user email
bool $return If $return is false this routine does not return on finding a banned user, it outputs a relevant message and stops execution.

in session at line 1313
public false check_dnsbl(string $mode, string|false $ip = false)

Check if ip is blacklisted This should be called only where absolutely necessary

Only IPv4 (rbldns does not support AAAA records/IPv6 lookups)

Parameters

string $mode register/post - spamcop for example is ommitted for posting
string|false $ip the IPv4 address to check

Return Value

false if ip is not blacklisted, else an array([checked server], [lookup])

in session at line 1410
public set_login_key($user_id = false, $key = false, $user_ip = false)

Set/Update a persistent login key

This method creates or updates a persistent session key. When a user makes use of persistent (formerly auto-) logins a key is generated and stored in the DB. When they revisit with the same key it's automatically updated in both the DB and cookie. Multiple keys may exist for each user representing different browsers or locations. As with any non-secure-socket no passphrase login this remains vulnerable to exploit.

Parameters

$user_id
$key
$user_ip

in session at line 1457
public reset_login_keys($user_id = false)

Reset all login keys for the specified user

This method removes all current login keys for a specified (or the current) user. It will be called on password change to render old keys unusable

Parameters

$user_id

in session at line 1506
public validate_referer(bool $check_script_path = false)

Check if the request originated from the same page.

Parameters

bool $check_script_path If true, the path will be checked as well

in session at line 1543
public unset_admin()

in session at line 1558
public update_session(array $session_data, string $session_id = null)

Update the session data

Parameters

array $session_data associative array of session keys to be updated
string $session_id optional sessionid, defaults to current user's sessionid

in session at line 1581
public update_session_infos()

at line 52
public __construct(string $datetime_class)

Constructor to set the lang path

Parameters

string $datetime_class Class name of datetime class

at line 66
public set_custom_lang_path(string $lang_path)

Function to set custom language path (able to use directory outside of phpBB)

Parameters

string $lang_path New language path used.

at line 79
public setup($lang_set = false, $style_id = false)

Setup basic user-specific items (style, language, ...)

Parameters

$lang_set
$style_id

at line 418
public lang()

More advanced language substitution Function to mimic sprintf() with the possibility of using phpBB's language system to substitute nullar/singular/plural forms.

Params are the language key and the parameters to be substituted. This function/functionality is inspired by SHS` and Ashe.

Example call: $user->lang('NUMPOSTSIN_QUEUE', 1);

If the first parameter is an array, the elements are used as keys and subkeys to get the language entry: Example: $user->lang(array('datetime', 'AGO'), 1) uses $user->lang['datetime']['AGO'] as language entry.

at line 525
public int get_plural_form($number $number, $force_rule $force_rule = false)

Determine which plural form we should use.

For some languages this is not as simple as for English.

Parameters

$number $number int|float The number we want to get the plural case for. Float numbers are floored.
$force_rule $force_rule mixed False to use the plural rule of the language package or an integer to force a certain plural rule

Return Value

int The plural-case we need to use for the number plural-rule combination

at line 552
public add_lang(mixed $lang_set, bool $use_db = false, bool $use_help = false, string $ext_name = '')

Add Language Items - usedb and usehelp are assigned where needed (only use them to force inclusion)

Parameters

mixed $lang_set specifies the language entries to include
bool $use_db internal variable for recursion, do not use
bool $use_help internal variable for recursion, do not use
string $ext_name The extension to load language from, or empty for core files Examples: $langset = array('posting', 'help' => 'faq'); $langset = array('posting', 'viewtopic', 'help' => array('bbcode', 'faq')) $langset = array(array('posting', 'viewtopic'), 'help' => array('bbcode', 'faq')) $langset = 'posting' $lang_set = array('help' => 'faq', 'db' => array('help:faq', 'posting'))

at line 597
public add_lang_ext(string $ext_name, mixed $lang_set, bool $use_db = false, bool $use_help = false)

Add Language Items from an extension - usedb and usehelp are assigned where needed (only use them to force inclusion)

Parameters

string $ext_name The extension to load language from, or empty for core files
mixed $lang_set specifies the language entries to include
bool $use_db internal variable for recursion, do not use
bool $use_help internal variable for recursion, do not use

at line 611
public set_lang($lang, $help, $lang_file, $use_db = false, $use_help = false, $ext_name = '')

Set language entry (called by add_lang)

Parameters

$lang
$help
$lang_file
$use_db
$use_help
$ext_name

at line 719
public mixed format_date(int $gmepoch, string $format = false, bool $forcedate = false)

Format user date

Parameters

int $gmepoch unix timestamp
string $format date format in date() notation. | used to indicate relative dates, for example |d m Y|, h:i is translated to Today, h:i.
bool $forcedate force non-relative date format.

Return Value

mixed translated date

at line 742
public datetime create_datetime(string $time = 'now', DateTimeZone $timezone = null)

Create a \phpbb\datetime object in the context of the current user

Parameters

string $time String in a format accepted by strtotime().
DateTimeZone $timezone Time zone of the time.

Return Value

datetime Date time object linked to the current users locale

at line 756
public get_timestamp_from_format($format, $time, DateTimeZone $timezone = null)

Get the UNIX timestamp for a datetime in the users timezone, so we can store it in the database.

Parameters

$format
$time
DateTimeZone $timezone

at line 766
public get_iso_lang_id()

Get language id currently used by the user

at line 793
public get_profile_fields($user_id)

Get users profile fields

Parameters

$user_id

at line 813
public img($img, $alt = '')

Specify/Get image

Parameters

$img
$alt

at line 832
public bool optionget(int $key, int $data = false)

Get option bit field from user options.

Parameters

int $key option key, as defined in $keyoptions property.
int $data bit field value to use, or false to use $this->data['user_options']

Return Value

bool true if the option is set in the bit field, false otherwise

at line 850
public int|bool optionset(int $key, bool $value, int $data = false)

Set option bit field for user options.

Parameters

int $key Option key, as defined in $keyoptions property.
bool $value True to set the option, false to clear the option.
int $data Current bit field value, or false to use $this->data['user_options']

Return Value

int|bool If $data is false, the bit field is modified and written back to $this->data['user_options'], and return value is true if the bit field changed and false otherwise. If $data is not false, the new bitfield value is returned.

at line 878
public leave_newly_registered()

Funtion to make the user leave the NEWLY_REGISTERED system group.

at line 910
public array get_passworded_forums()

Returns all password protected forum ids the user is currently NOT authenticated for.

Return Value

array Array of forum ids