MediaWiki\Preferences\PreferencesFactory Interface Reference

A PreferencesFactory is a MediaWiki service that provides the definitions of preferences for a given user. More...

Inherited by MediaWiki\Preferences\DefaultPreferencesFactory.

Public Member Functions
	getForm (User $user, IContextSource $contextSource, $formClass=PreferencesFormOOUI::class, array $remove=[])
	Get the preferences form for a given user.
	getFormDescriptor (User $user, IContextSource $contextSource)
	Get the preferences form descriptor.
	getOptionNamesForReset (User $user, IContextSource $context, $kinds)
	Get the list of option names which have been saved by the user, thus having non-default values, which match the specified set of kinds.
	getResetKinds (User $user, IContextSource $context, $options=null)
	Return an associative array mapping preferences keys to the kind of a preference they're used for.
	getSaveBlacklist ()
	Get the names of preferences that should never be saved (such as 'realname' and 'emailaddress').
	listResetKinds ()
	Return a list of the types of user options currently returned by getResetKinds().

Detailed Description

A PreferencesFactory is a MediaWiki service that provides the definitions of preferences for a given user.

These definitions are in the form of an HTMLForm descriptor.

PreferencesFormOOUI (a subclass of HTMLForm) is used to generate the Preferences form, and handles generic submission, CSRF protection, layout and other logic in a reusable manner.

In order to generate the form, the HTMLForm object needs an array structure detailing the form fields available, and that's what this implementations of this interface provide. Each element of the array is a basic property-list, including the type of field, the label it is to be given in the form, callbacks for validation and 'filtering', and other pertinent information. Note that the 'default' field is named for generic forms, and does not represent the preference's default (which is stored in $wgDefaultUserOptions), but the default for the form field, which should be whatever the user has set for that preference. There is no need to override it unless you have some special storage logic (for instance, those not presently stored as options, but which are best set from the user preferences view).

Field types are implemented as subclasses of the generic HTMLFormField object, and typically implement at least getInputHTML, which generates the HTML for the input field to be placed in the table.

Once fields have been retrieved and validated, submission logic is handed over to the submitForm() method of this interface.

Stability: stable

to implement

Definition at line 54 of file PreferencesFactory.php.

Member Function Documentation

getForm()

MediaWiki\Preferences\PreferencesFactory::getForm	(	User	$user,
		IContextSource	$contextSource,
			$formClass = PreferencesFormOOUI::class,
		array	$remove = [] )

Get the preferences form for a given user.

This method retrieves the form descriptor for the user, instantiates a new form using the descriptor and returns the instantiated form object.

Parameters

User	$user
IContextSource	$contextSource
string	$formClass
array	$remove

Returns

HTMLForm

Implemented in MediaWiki\Preferences\DefaultPreferencesFactory.

getFormDescriptor()

MediaWiki\Preferences\PreferencesFactory::getFormDescriptor	(	User	$user,
		IContextSource	$contextSource )

Get the preferences form descriptor.

Parameters

User	$user
IContextSource	$contextSource

Returns

mixed[][] An HTMLForm descriptor array.

Implemented in MediaWiki\Preferences\DefaultPreferencesFactory.

getOptionNamesForReset()

MediaWiki\Preferences\PreferencesFactory::getOptionNamesForReset	(	User	$user,
		IContextSource	$context,
			$kinds )

Get the list of option names which have been saved by the user, thus having non-default values, which match the specified set of kinds.

Since

1.43

Parameters

User	$user
IContextSource	$context
string | string[]	$kinds	List of option kinds, which may be any of the kinds returned by listResetKinds(), or "all" for all options.

Returns

string[]

Implemented in MediaWiki\Preferences\DefaultPreferencesFactory.

getResetKinds()

MediaWiki\Preferences\PreferencesFactory::getResetKinds	(	User	$user,
		IContextSource	$context,
			$options = null )

Return an associative array mapping preferences keys to the kind of a preference they're used for.

Different kinds are handled differently when setting or reading preferences.

See PreferencesFactory::listResetKinds for the list of valid option types that can be provided.

Since

1.43

Parameters

User	$user
IContextSource	$context
array | null	$options	Assoc. array with options keys to check as keys. Defaults to all user options.

Returns

string[] The key => kind mapping data

Implemented in MediaWiki\Preferences\DefaultPreferencesFactory.

getSaveBlacklist()

MediaWiki\Preferences\PreferencesFactory::getSaveBlacklist

(

)

Get the names of preferences that should never be saved (such as 'realname' and 'emailaddress').

Returns

string[]

Implemented in MediaWiki\Preferences\DefaultPreferencesFactory.

listResetKinds()

MediaWiki\Preferences\PreferencesFactory::listResetKinds

(

)

Return a list of the types of user options currently returned by getResetKinds().

Currently, the option kinds are:

• 'registered' - preferences which are registered in core MediaWiki or by extensions using the UserGetDefaultOptions hook.
• 'registered-multiselect' - as above, using the 'multiselect' type.
• 'registered-checkmatrix' - as above, using the 'checkmatrix' type.
• 'userjs' - preferences with names starting with 'userjs-', intended to be used by user scripts.
• 'special' - "preferences" that are not accessible via UserOptionsLookup::getOptions or UserOptionsManager::setOptions.
• 'unused' - preferences about which MediaWiki doesn't know anything. These are usually legacy options, removed in newer versions.

The API (and possibly others) use this function to determine the possible option types for validation purposes, so make sure to update this when a new option kind is added.

Since

1.43

Returns

string[] Option kinds

Implemented in MediaWiki\Preferences\DefaultPreferencesFactory.

---

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

• includes/preferences/PreferencesFactory.php