1	<?php
2	/**
3	* This program is free software; you can redistribute it and/or modify
4	* it under the terms of the GNU General Public License as published by
5	* the Free Software Foundation; either version 2 of the License, or
6	* (at your option) any later version.
7	*
8	* This program is distributed in the hope that it will be useful,
9	* but WITHOUT ANY WARRANTY; without even the implied warranty of
10	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11	* GNU General Public License for more details.
12	*
13	* You should have received a copy of the GNU General Public License along
14	* with this program; if not, write to the Free Software Foundation, Inc.,
15	* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16	* http://www.gnu.org/copyleft/gpl.html
17	*
18	* @file
19	*/
20
21	namespace MediaWiki\Preferences;
22
23	use MediaWiki\Context\IContextSource;
24	use MediaWiki\HTMLForm\HTMLForm;
25	use MediaWiki\User\User;
26	use PreferencesFormOOUI;
27
28	/**
29	* A PreferencesFactory is a MediaWiki service that provides the definitions of preferences for a
30	* given user. These definitions are in the form of an HTMLForm descriptor.
31	*
32	* PreferencesFormOOUI (a subclass of HTMLForm) is used to generate the Preferences form, and
33	* handles generic submission, CSRF protection, layout and other logic in a reusable manner.
34	*
35	* In order to generate the form, the HTMLForm object needs an array structure detailing the
36	* form fields available, and that's what this implementations of this interface provide. Each
37	* element of the array is a basic property-list, including the type of field, the label it is to be
38	* given in the form, callbacks for validation and 'filtering', and other pertinent information.
39	* Note that the 'default' field is named for generic forms, and does not represent the preference's
40	* default (which is stored in $wgDefaultUserOptions), but the default for the form field, which
41	* should be whatever the user has set for that preference. There is no need to override it unless
42	* you have some special storage logic (for instance, those not presently stored as options, but
43	* which are best set from the user preferences view).
44	*
45	* Field types are implemented as subclasses of the generic HTMLFormField object, and typically
46	* implement at least getInputHTML, which generates the HTML for the input field to be placed in the
47	* table.
48	*
49	* Once fields have been retrieved and validated, submission logic is handed over to the
50	* submitForm() method of this interface.
51	*
52	* @stable to implement
53	*/
54	interface PreferencesFactory {
55
56	/**
57	* Get the preferences form for a given user. This method retrieves the form descriptor for the
58	* user, instantiates a new form using the descriptor and returns the instantiated form object.
59	* @param User $user
60	* @param IContextSource $contextSource
61	* @param string $formClass
62	* @param array $remove
63	* @return HTMLForm
64	*/
65	public function getForm(
66	User $user,
67	IContextSource $contextSource,
68	$formClass = PreferencesFormOOUI::class,
69	array $remove = []
70	);
71
72	/**
73	* Get the preferences form descriptor.
74	* @param User $user
75	* @param IContextSource $contextSource
76	* @return mixed[][] An HTMLForm descriptor array.
77	*/
78	public function getFormDescriptor( User $user, IContextSource $contextSource );
79
80	/**
81	* Get the names of preferences that should never be saved
82	* (such as 'realname' and 'emailaddress').
83	* @return string[]
84	*/
85	public function getSaveBlacklist();
86
87	/**
88	* Return an associative array mapping preferences keys to the kind of a
89	* preference they're used for. Different kinds are handled differently
90	* when setting or reading preferences.
91	*
92	* See PreferencesFactory::listResetKinds for the list of valid option
93	* types that can be provided.
94	*
95	* @since 1.43
96	* @param User $user
97	* @param IContextSource $context
98	* @param array|null $options Assoc. array with options keys to check as keys.
99	*   Defaults to all user options.
100	* @return string[] The key => kind mapping data
101	*/
102	public function getResetKinds(
103	User $user,
104	IContextSource $context,
105	$options = null
106	): array;
107
108	/**
109	* Return a list of the types of user options currently returned by
110	* getResetKinds().
111	*
112	* Currently, the option kinds are:
113	* - 'registered' - preferences which are registered in core MediaWiki or
114	*                  by extensions using the UserGetDefaultOptions hook.
115	* - 'registered-multiselect' - as above, using the 'multiselect' type.
116	* - 'registered-checkmatrix' - as above, using the 'checkmatrix' type.
117	* - 'userjs' - preferences with names starting with 'userjs-', intended to
118	*              be used by user scripts.
119	* - 'special' - "preferences" that are not accessible via
120	*              UserOptionsLookup::getOptions or UserOptionsManager::setOptions.
121	* - 'unused' - preferences about which MediaWiki doesn't know anything.
122	*              These are usually legacy options, removed in newer versions.
123	*
124	* The API (and possibly others) use this function to determine the possible
125	* option types for validation purposes, so make sure to update this when a
126	* new option kind is added.
127	*
128	* @since 1.43
129	* @return string[] Option kinds
130	*/
131	public function listResetKinds();
132
133	/**
134	* Get the list of option names which have been saved by the user, thus
135	* having non-default values, which match the specified set of kinds.
136	*
137	* @since 1.43
138	* @param User $user
139	* @param IContextSource $context
140	* @param string|string[] $kinds List of option kinds, which may be any of
141	*   the kinds returned by listResetKinds(), or "all" for all options.
142	* @return string[]
143	*/
144	public function getOptionNamesForReset(
145	User $user,
146	IContextSource $context,
147	$kinds
148	);
149	}