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 User;
  26
  27 /**
  28  * A PreferencesFactory is a MediaWiki service that provides the definitions of preferences for a
  29  * given user. These definitions are in the form of an HTMLForm descriptor.
  30  *
  31  * PreferencesForm (a subclass of HTMLForm) is used to generate the Preferences form, and handles
  32  * generic submission, CSRF protection, layout and other logic in a reusable manner.
  33  *
  34  * In order to generate the form, the HTMLForm object needs an array structure detailing the
  35  * form fields available, and that's what this implementations of this interface provide. Each
  36  * element of the array is a basic property-list, including the type of field, the label it is to be
  37  * given in the form, callbacks for validation and 'filtering', and other pertinent information.
  38  * Note that the 'default' field is named for generic forms, and does not represent the preference's
  39  * default (which is stored in $wgDefaultUserOptions), but the default for the form field, which
  40  * should be whatever the user has set for that preference. There is no need to override it unless
  41  * you have some special storage logic (for instance, those not presently stored as options, but
  42  * which are best set from the user preferences view).
  43  *
  44  * Field types are implemented as subclasses of the generic HTMLFormField object, and typically
  45  * implement at least getInputHTML, which generates the HTML for the input field to be placed in the
  46  * table.
  47  *
  48  * Once fields have been retrieved and validated, submission logic is handed over to the
  49  * submitForm() method of this interface.
  50  */
  51 interface PreferencesFactory {
  52
  53         /**
  54          * Get the preferences form for a given user. This method retrieves the form descriptor for the
  55          * user, instantiates a new form using the descriptor and returns the instantiated form object.
  56          * @param User $user
  57          * @param IContextSource $contextSource
  58          * @param string $formClass
  59          * @param array $remove
  60          * @return HTMLForm
  61          */
  62         public function getForm(
  63                 User $user,
  64                 IContextSource $contextSource,
  65                 $formClass = \PreferencesForm::class,
  66                 array $remove = []
  67         );
  68
  69         /**
  70          * Get the preferences form descriptor.
  71          * @param User $user
  72          * @param IContextSource $contextSource
  73          * @return mixed[][] An HTMLForm descriptor array.
  74          */
  75         public function getFormDescriptor( User $user, IContextSource $contextSource );
  76
  77         /**
  78          * Get the names of preferences that should never be saved
  79          * (such as 'realname' and 'emailaddress').
  80          * @return string[]
  81          */
  82         public function getSaveBlacklist();
  83 }