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	}