includes/preferences/PreferencesFactory.php

   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 HTMLForm;
  24 use IContextSource;
  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 }