A service class to control user options. More...

Inherits MediaWiki\User\Options\UserOptionsLookup.

Collaboration diagram for MediaWiki\User\Options\UserOptionsManager:

Public Member Functions

__construct (ServiceOptions $options, DefaultOptionsLookup $defaultOptionsLookup, LanguageConverterFactory $languageConverterFactory, IConnectionProvider $dbProvider, LoggerInterface $logger, HookContainer $hookContainer, UserFactory $userFactory, UserNameUtils $userNameUtils, ObjectFactory $objectFactory)

clearUserOptionsCache (UserIdentity $user)

Clears cached user options.

getDefaultOption (string $opt, ?UserIdentity $userIdentity=null)

Get a given default option value.

Parameters

string	$opt	Name of option to retrieve
UserIdentity \| null	$userIdentity	User to look the defaults up for; set to null to ignore any user-specific defaults (since 1.42)

Returns: mixed|null Default option value

getDefaultOptions (?UserIdentity $userIdentity=null)

Combine the language default options with any site-specific and user-specific defaults and add the default language variants.

Parameters

UserIdentity | null $userIdentity User to look the default up for; set to null to ignore any user-specific defaults (since 1.42)

Returns: array

getOption (UserIdentity $user, string $oname, $defaultOverride=null, bool $ignoreHidden=false, int $queryFlags=IDBAccessObject::READ_NORMAL)

Get the user's current setting for a given option.

Parameters

UserIdentity	$user	The user to get the option for
string	$oname	The option to check
mixed \| null	$defaultOverride	A default value returned if the option does not exist
bool	$ignoreHidden	Whether to ignore the effects of $wgHiddenPrefs
int	$queryFlags	A bit field composed of READ_XXX flags

Returns: mixed|null User's current value for the option, Note that while option values retrieved from the database are always strings, default values and values set within the current request and not yet saved may be of another type.

See also: getBoolOption(); getIntOption()

getOptionKinds (UserIdentity $userIdentity, IContextSource $context, $options=null)

getOptions (UserIdentity $user, int $flags=0, int $queryFlags=IDBAccessObject::READ_NORMAL)

Get all user's options.

Parameters

UserIdentity	$user	The user to get the option for
int	$flags	Bitwise combination of: UserOptionsManager::EXCLUDE_DEFAULTS Exclude user options that are set to the default value. Options that are set to their conditionally default value are not excluded.
int	$queryFlags	A bit field composed of READ_XXX flags

Returns: array

isOptionGlobal (UserIdentity $user, string $key)

Determine if a user option came from a source other than the local store or the defaults.

listOptionKinds ()

loadUserOptions (UserIdentity $user, int $queryFlags=IDBAccessObject::READ_NORMAL)

Loads user options either from cache or from the database.

resetAllOptions (UserIdentity $user)

Reset all options that were set to a non-default value by the given user.

resetOptions (UserIdentity $user, IContextSource $context, $resetKinds=[ 'registered', 'registered-multiselect', 'registered-checkmatrix', 'unused'])

Reset certain (or all) options to the site defaults.

resetOptionsByName (UserIdentity $user, array $optionNames)

Reset a list of options to the site defaults.

saveOptions (UserIdentity $user)

Saves the non-default options for this user, as previously set e.g.

saveOptionsInternal (UserIdentity $user)

Saves the non-default options for this user, as previously set e.g.

setOption (UserIdentity $user, string $oname, $val, $global=self::GLOBAL_IGNORE)

Set the given option for a user.

Public Member Functions inherited from MediaWiki\User\Options\UserOptionsLookup

getBoolOption (UserIdentity $user, string $oname, int $queryFlags=IDBAccessObject::READ_NORMAL)

Get the user's current setting for a given option, as a boolean value.

getIntOption (UserIdentity $user, string $oname, int $defaultOverride=0, int $queryFlags=IDBAccessObject::READ_NORMAL)

Get the user's current setting for a given option, as an integer value.

Static Public Member Functions
static	isValueEqual ( $a, $b)
	Determines whether two values are sufficiently similar that the database does not need to be updated to reflect the change.

Public Attributes
const	CONSTRUCTOR_OPTIONS

const	GLOBAL_IGNORE = 'ignore'
	If the option was set globally, ignore the update.

const	GLOBAL_OVERRIDE = 'override'
	If the option was set globally, add a local override.

const	GLOBAL_UPDATE = 'update'
	If the option was set globally, update the global value.

const	MAX_BYTES_OPTION_VALUE = 65530

Public Attributes inherited from MediaWiki\User\Options\UserOptionsLookup
const	EXCLUDE_DEFAULTS = 1
	Exclude user options that are set to their default value.

const	LOCAL_EXCEPTION_SUFFIX = '-local-exception'
	The suffix appended to preference names for the associated preference that tracks whether they have a local override.

Detailed Description

A service class to control user options.

Since: 1.35

Definition at line 47 of file UserOptionsManager.php.

Constructor & Destructor Documentation

◆ __construct()

MediaWiki\User\Options\UserOptionsManager::__construct	(	ServiceOptions	$options,
		DefaultOptionsLookup	$defaultOptionsLookup,
		LanguageConverterFactory	$languageConverterFactory,
		IConnectionProvider	$dbProvider,
		LoggerInterface	$logger,
		HookContainer	$hookContainer,
		UserFactory	$userFactory,
		UserNameUtils	$userNameUtils,
		ObjectFactory	$objectFactory )

Parameters

ServiceOptions	$options
DefaultOptionsLookup	$defaultOptionsLookup
LanguageConverterFactory	$languageConverterFactory
IConnectionProvider	$dbProvider
LoggerInterface	$logger
HookContainer	$hookContainer
UserFactory	$userFactory
UserNameUtils	$userNameUtils
ObjectFactory	$objectFactory

Definition at line 109 of file UserOptionsManager.php.

References MediaWiki\Config\ServiceOptions\assertRequiredOptions().

Member Function Documentation

◆ clearUserOptionsCache()

MediaWiki\User\Options\UserOptionsManager::clearUserOptionsCache ( UserIdentity $user )

Clears cached user options.

Access: internal: To be used by User::clearInstanceCache

Parameters

UserIdentity $user

Definition at line 472 of file UserOptionsManager.php.

References getCacheKey().

◆ getDefaultOption()

MediaWiki\User\Options\UserOptionsManager::getDefaultOption	(	string	$opt,
		?UserIdentity	$userIdentity = null )

Get a given default option value.

Parameters

string	$opt	Name of option to retrieve
UserIdentity \| null	$userIdentity	User to look the defaults up for; set to null to ignore any user-specific defaults (since 1.42)

Returns: mixed|null Default option value

Reimplemented from MediaWiki\User\Options\UserOptionsLookup.

Definition at line 142 of file UserOptionsManager.php.

◆ getDefaultOptions()

MediaWiki\User\Options\UserOptionsManager::getDefaultOptions ( ?UserIdentity $userIdentity = null )

Combine the language default options with any site-specific and user-specific defaults and add the default language variants.

Parameters

UserIdentity | null $userIdentity User to look the default up for; set to null to ignore any user-specific defaults (since 1.42)

Returns: array

Reimplemented from MediaWiki\User\Options\UserOptionsLookup.

Definition at line 135 of file UserOptionsManager.php.

◆ getOption()

MediaWiki\User\Options\UserOptionsManager::getOption	(	UserIdentity	$user,
		string	$oname,
			$defaultOverride = null,
		bool	$ignoreHidden = false,
		int	$queryFlags = IDBAccessObject::READ_NORMAL )

Get the user's current setting for a given option.

Parameters

UserIdentity	$user	The user to get the option for
string	$oname	The option to check
mixed \| null	$defaultOverride	A default value returned if the option does not exist
bool	$ignoreHidden	Whether to ignore the effects of $wgHiddenPrefs
int	$queryFlags	A bit field composed of READ_XXX flags

Returns: mixed|null User's current value for the option, Note that while option values retrieved from the database are always strings, default values and values set within the current request and not yet saved may be of another type.

See also: getBoolOption(); getIntOption()

Reimplemented from MediaWiki\User\Options\UserOptionsLookup.

Definition at line 149 of file UserOptionsManager.php.

References MediaWiki\MainConfigNames\HiddenPrefs.

◆ getOptionKinds()

MediaWiki\User\Options\UserOptionsManager::getOptionKinds	(	UserIdentity	$userIdentity,
		IContextSource	$context,
			$options = null )

Deprecated: since 1.43 use PreferencesFactory::getResetKinds

Parameters

UserIdentity	$userIdentity
IContextSource	$context
array \| null	$options

Returns: string[]

Definition at line 343 of file UserOptionsManager.php.

◆ getOptions()

MediaWiki\User\Options\UserOptionsManager::getOptions	(	UserIdentity	$user,
		int	$flags = 0,
		int	$queryFlags = IDBAccessObject::READ_NORMAL )

Get all user's options.

Parameters

UserIdentity	$user	The user to get the option for
int	$flags	Bitwise combination of: UserOptionsManager::EXCLUDE_DEFAULTS Exclude user options that are set to the default value. Options that are set to their conditionally default value are not excluded.
int	$queryFlags	A bit field composed of READ_XXX flags

Returns: array

Reimplemented from MediaWiki\User\Options\UserOptionsLookup.

Definition at line 175 of file UserOptionsManager.php.

◆ isOptionGlobal()

MediaWiki\User\Options\UserOptionsManager::isOptionGlobal	(	UserIdentity	$user,
		string	$key )

Determine if a user option came from a source other than the local store or the defaults.

If this is true, setting the option will be ignored unless GLOBAL_OVERRIDE or GLOBAL_UPDATE is passed to setOption().

Parameters

UserIdentity	$user
string	$key

Returns: bool

Reimplemented from MediaWiki\User\Options\UserOptionsLookup.

Definition at line 210 of file UserOptionsManager.php.

References $source, and getCacheKey().

◆ isValueEqual()

static MediaWiki\User\Options\UserOptionsManager::isValueEqual	(		$a,
			$b )

static

Determines whether two values are sufficiently similar that the database does not need to be updated to reflect the change.

This is basically the same as comparing the result of Database::addQuotes().

Since: 1.43

Parameters

mixed	$a
mixed	$b

Returns: bool

Definition at line 622 of file UserOptionsManager.php.

Referenced by MediaWiki\User\Options\LocalUserOptionsStore\store().

◆ listOptionKinds()

MediaWiki\User\Options\UserOptionsManager::listOptionKinds ( )

Deprecated: since 1.43 use PreferencesFactory::listResetKinds()

Returns: string[] Option kinds

Definition at line 329 of file UserOptionsManager.php.

◆ loadUserOptions()

MediaWiki\User\Options\UserOptionsManager::loadUserOptions	(	UserIdentity	$user,
		int	$queryFlags = IDBAccessObject::READ_NORMAL )

Loads user options either from cache or from the database.

Note: Query flags are ignored for anons, since they do not have any options stored in the database. If the UserIdentity was itself obtained from a replica and doesn't have ID set due to replication lag, it will be treated as anon regardless of the query flags passed here.

Access: internal

Parameters

UserIdentity	$user
int	$queryFlags

Returns: array

Definition at line 453 of file UserOptionsManager.php.

◆ resetAllOptions()

MediaWiki\User\Options\UserOptionsManager::resetAllOptions ( UserIdentity $user )

Reset all options that were set to a non-default value by the given user.

Note: You need to call saveOptions() to actually write to the database.

Parameters

UserIdentity $user

Definition at line 318 of file UserOptionsManager.php.

◆ resetOptions()

MediaWiki\User\Options\UserOptionsManager::resetOptions	(	UserIdentity	$user,
		IContextSource	$context,
			$resetKinds = [ 'registered', 'registered-multiselect', 'registered-checkmatrix', 'unused' ] )

Reset certain (or all) options to the site defaults.

The optional parameter determines which kinds of preferences will be reset. Supported values are everything that can be reported by getOptionKinds() and 'all', which forces a reset of all preferences and overrides everything else.

Note: You need to call saveOptions() to actually write to the database.

Deprecated: since 1.43 use resetOptionsByName() with PreferencesFactory::getOptionNamesForReset()

Parameters

UserIdentity	$user
IContextSource	$context	Context source used when $resetKinds does not contain 'all'.
array \| string	$resetKinds	Which kinds of preferences to reset. Defaults to [ 'registered', 'registered-multiselect', 'registered-checkmatrix', 'unused' ]

Definition at line 282 of file UserOptionsManager.php.

References wfDeprecated().

◆ resetOptionsByName()

MediaWiki\User\Options\UserOptionsManager::resetOptionsByName	(	UserIdentity	$user,
		array	$optionNames )

Reset a list of options to the site defaults.

Note: You need to call saveOptions() to actually write to the database.

Parameters

UserIdentity	$user
string[]	$optionNames

Definition at line 302 of file UserOptionsManager.php.

◆ saveOptions()

MediaWiki\User\Options\UserOptionsManager::saveOptions ( UserIdentity $user )

Saves the non-default options for this user, as previously set e.g.

via setOption(), in the database's "user_properties" (preferences) table.

Since: 1.38, this method was internal before that.

Parameters

UserIdentity $user

Definition at line 361 of file UserOptionsManager.php.

◆ saveOptionsInternal()

MediaWiki\User\Options\UserOptionsManager::saveOptionsInternal ( UserIdentity $user )

Saves the non-default options for this user, as previously set e.g.

via setOption(), in the database's "user_properties" (preferences) table.

Parameters

UserIdentity $user

Returns: bool true if options were changed and new options successfully saved.

Access: internal: only public for use in User::saveSettings

Definition at line 386 of file UserOptionsManager.php.

◆ setOption()

MediaWiki\User\Options\UserOptionsManager::setOption	(	UserIdentity	$user,
		string	$oname,
			$val,
			$global = self::GLOBAL_IGNORE )

Set the given option for a user.

You need to call saveOptions() to actually write to the database.

$val should be null or a string. Other types are accepted for B/C with legacy code but can result in surprising behavior and are discouraged. Values are always stored as strings in the database, so if you pass a non-string value, it will be eventually converted; but before the call to saveOptions(), getOption() will return the passed value from instance cache without any type conversion.

A null value means resetting the option to its default value (removing the user_properties row). Passing in the same value as the default value fo the user has the same result. This behavior supports some level of type juggling - e.g. if the default value is 1, and you pass in '1', the option will be reset to its default value.

When an option is reset to its default value, that means whenever the default value is changed in the site configuration, the user preference for this user will also change. There is no way to set a user preference to be the same as the default but avoid it changing when the default changes. You can instead use $wgConditionalUserOptions to split the default based on user registration date.

If a global user option exists with the given name, the behaviour depends on the value of $global.

Parameters

UserIdentity	$user
string	$oname	The option to set
mixed	$val	New value to set.
string	$global	Since 1.43. What to do if the option was set globally using the GlobalPreferences extension. One of the self::GLOBAL_* constants: GLOBAL_IGNORE: Do nothing. The option remains with its previous value. GLOBAL_OVERRIDE: Add a local override. GLOBAL_UPDATE: Update the option globally. The UI should typically ask for the user's consent before setting a global option.

Definition at line 253 of file UserOptionsManager.php.

References getCacheKey().

Member Data Documentation

◆ CONSTRUCTOR_OPTIONS

const MediaWiki\User\Options\UserOptionsManager::CONSTRUCTOR_OPTIONS

Initial value:

= [
        MainConfigNames::HiddenPrefs,
        MainConfigNames::LocalTZoffset,
    ]

Access: internal: For use by ServiceWiring

Definition at line 52 of file UserOptionsManager.php.

◆ GLOBAL_IGNORE

const MediaWiki\User\Options\UserOptionsManager::GLOBAL_IGNORE = 'ignore'

If the option was set globally, ignore the update.

Since: 1.43

Definition at line 66 of file UserOptionsManager.php.

◆ GLOBAL_OVERRIDE

const MediaWiki\User\Options\UserOptionsManager::GLOBAL_OVERRIDE = 'override'

If the option was set globally, add a local override.

Since: 1.43

Definition at line 72 of file UserOptionsManager.php.

◆ GLOBAL_UPDATE

const MediaWiki\User\Options\UserOptionsManager::GLOBAL_UPDATE = 'update'

If the option was set globally, update the global value.

Since: 1.43

Definition at line 78 of file UserOptionsManager.php.

◆ MAX_BYTES_OPTION_VALUE

const MediaWiki\User\Options\UserOptionsManager::MAX_BYTES_OPTION_VALUE = 65530

Since: 1.39.5, 1.40

Definition at line 60 of file UserOptionsManager.php.

Referenced by MediaWiki\User\Options\LocalUserOptionsStore\store().

The documentation for this class was generated from the following file:

includes/user/Options/UserOptionsManager.php

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ __construct()

Member Function Documentation

◆ clearUserOptionsCache()

◆ getDefaultOption()

◆ getDefaultOptions()

◆ getOption()

◆ getOptionKinds()

◆ getOptions()

◆ isOptionGlobal()

◆ isValueEqual()

◆ listOptionKinds()

◆ loadUserOptions()

◆ resetAllOptions()

◆ resetOptions()

◆ resetOptionsByName()

◆ saveOptions()

◆ saveOptionsInternal()

◆ setOption()

Member Data Documentation

◆ CONSTRUCTOR_OPTIONS

◆ GLOBAL_IGNORE

◆ GLOBAL_OVERRIDE

◆ GLOBAL_UPDATE

◆ MAX_BYTES_OPTION_VALUE