Restore 'PreferencesForm' as alias for 'PreferencesFormLegacy'

In change 4633f4d46a8db46721474e9ffa6a130d8b7a2404 it was changed
to an interface implemented by both PreferencesFormLegacy and
PreferencesFormOOUI so that existing typehints for some functions
parameter would accept them both. Replace those typehints to use
HTMLForm instead. There was really no guarantee in the past that
they would only be given PreferencesForm or its subclasses, either.

Because the typehint change affects some hooks, note it as a
deprecation in MW 1.31 and a breaking change in MW 1.32.

Also add @since tags and correct some typos in code comments.

Follow-up to 4633f4d46a8db46721474e9ffa6a130d8b7a2404.

Change-Id: I61749f1d864cf68afe90cd9e15ba2d7a74252501

diff --git a/.phpcs.xml b/.phpcs.xml
index d36d80d..d22bfae 100644 (file)
--- a/.phpcs.xml
+++ b/.phpcs.xml
@@ -254,6 +254,7 @@
                <exclude-pattern>*/includes/search/SearchEngine\.php</exclude-pattern>
                <exclude-pattern>*/includes/specialpage/LoginSignupSpecialPage\.php</exclude-pattern>
                <exclude-pattern>*/includes/specialpage/RedirectSpecialPage\.php</exclude-pattern>
+               <exclude-pattern>*/includes/specials/forms/PreferencesFormLegacy\.php</exclude-pattern>
                <exclude-pattern>*/includes/specials/SpecialListusers\.php</exclude-pattern>
                <exclude-pattern>*/includes/specials/SpecialMyRedirectPages\.php</exclude-pattern>
                <exclude-pattern>*/includes/specials/SpecialUploadStash\.php</exclude-pattern>

diff --git a/RELEASE-NOTES-1.31 b/RELEASE-NOTES-1.31
index 740535a..bf038a7 100644 (file)
--- a/RELEASE-NOTES-1.31
+++ b/RELEASE-NOTES-1.31
@@ -383,6 +383,9 @@ changes to languages because of Phabricator reports.
   used instead.
 * The function wfShellWikiCmd() has been deprecated, use
   MediaWiki\Shell::makeScriptCommand().
+* In the future, the hooks 'PreferencesFormPreSave' and 'PreferencesGetLegend'
+  will be allowed to provide any HTMLForm object rather than PreferencesForm.
+
 === Other changes in 1.31 ===
 * Browser support for Internet Explorer 10 was lowered from Grade A to Grade C.
 * Browser support for Opera 12 and older was dropped entirely. Opera 15+

diff --git a/RELEASE-NOTES-1.32 b/RELEASE-NOTES-1.32
index 00e43c5..9816451 100644 (file)
--- a/RELEASE-NOTES-1.32
+++ b/RELEASE-NOTES-1.32
@@ -109,6 +109,8 @@ because of Phabricator reports.
 * The jquery.farbtastic module, unused since 1.18, was removed.
 * (T181318) The $wgStyleVersion setting and its appendage to various script and
   style URLs in OutputPage, deprecated in 1.31, was removed.
+* The hooks 'PreferencesFormPreSave' and 'PreferencesGetLegend' may provide
+  any HTMLForm object rather than PreferencesForm.
 
 === Deprecations in 1.32 ===
 * Use of a StartProfiler.php file is deprecated in favour of placing

diff --git a/autoload.php b/autoload.php
index 2006263..fcaa5fa 100644 (file)
--- a/autoload.php
+++ b/autoload.php
@@ -1142,7 +1142,7 @@ $wgAutoloadLocalClasses = [
        'PostgresInstaller' => __DIR__ . '/includes/installer/PostgresInstaller.php',
        'PostgresUpdater' => __DIR__ . '/includes/installer/PostgresUpdater.php',
        'Preferences' => __DIR__ . '/includes/Preferences.php',
-       'PreferencesForm' => __DIR__ . '/includes/specials/forms/PreferencesForm.php',
+       'PreferencesForm' => __DIR__ . '/includes/specials/forms/PreferencesFormLegacy.php',
        'PreferencesFormLegacy' => __DIR__ . '/includes/specials/forms/PreferencesFormLegacy.php',
        'PreferencesFormOOUI' => __DIR__ . '/includes/specials/forms/PreferencesFormOOUI.php',
        'PrefixSearch' => __DIR__ . '/includes/PrefixSearch.php',

diff --git a/docs/hooks.txt b/docs/hooks.txt
index 9404e14..349cd4b 100644 (file)
--- a/docs/hooks.txt
+++ b/docs/hooks.txt
@@ -2716,14 +2716,14 @@ Occurs after signing up or logging in, allows for interception of redirect.
 
 'PreferencesFormPreSave': Override preferences being saved
 $formData: array of user submitted data
-$form: PreferencesForm object, also a ContextSource
+$form: HTMLForm object, also a ContextSource
 $user: User object with preferences to be saved set
 &$result: boolean indicating success
 $oldUserOptions: array with user old options (before save)
 
 'PreferencesGetLegend': Override the text used for the <legend> of a
 preferences section.
-$form: the PreferencesForm object. This is a ContextSource as well
+$form: the HTMLForm object. This is a ContextSource as well
 $key: the section name
 &$legend: the legend text. Defaults to wfMessage( "prefs-$key" )->text() but may
   be overridden

diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php
index e253c83..853315f 100644 (file)
--- a/includes/DefaultSettings.php
+++ b/includes/DefaultSettings.php
@@ -3227,8 +3227,8 @@ $wgHTMLFormAllowTableFormat = true;
 $wgUseMediaWikiUIEverywhere = false;
 
 /**
- * Temporary variable that determines whether the EditPage class should use OOjs UI or not.
- * This will be removed later and OOjs UI will become the only option.
+ * Temporary variable that determines whether Special:Preferences should use OOUI or not.
+ * This will be removed later and OOUI will become the only option.
  *
  * @since 1.32
  */

diff --git a/includes/Preferences.php b/includes/Preferences.php
index 26e28ba..035b494 100644 (file)
--- a/includes/Preferences.php
+++ b/includes/Preferences.php
@@ -306,7 +306,7 @@ class Preferences {
         * @deprecated since 1.31, use PreferencesFactory
         *
         * @param array $formData
-        * @param PreferencesForm $form
+        * @param HTMLForm $form
         * @return bool|Status|string
         */
        public static function tryFormSubmit( $formData, $form ) {
@@ -316,7 +316,7 @@ class Preferences {
 
        /**
         * @param array $formData
-        * @param PreferencesForm $form
+        * @param HTMLForm $form
         * @return Status
         */
        public static function tryUISubmit( $formData, $form ) {

diff --git a/includes/preferences/DefaultPreferencesFactory.php b/includes/preferences/DefaultPreferencesFactory.php
index d5a706a..755d108 100644 (file)
--- a/includes/preferences/DefaultPreferencesFactory.php
+++ b/includes/preferences/DefaultPreferencesFactory.php
@@ -46,7 +46,6 @@ use OutputPage;
 use Parser;
 use ParserOptions;
 use PreferencesForm;
-use PreferencesFormOOUI;
 use Psr\Log\LoggerAwareTrait;
 use Psr\Log\NullLogger;
 use Skin;
@@ -1484,12 +1483,12 @@ class DefaultPreferencesFactory implements PreferencesFactory {
         * @param IContextSource $context
         * @param string $formClass
         * @param array $remove Array of items to remove
-        * @return PreferencesForm
+        * @return HTMLForm
         */
        public function getForm(
                User $user,
                IContextSource $context,
-               $formClass = PreferencesFormOOUI::class,
+               $formClass = PreferencesForm::class,
                array $remove = []
        ) {
                if ( SpecialPreferences::isOouiEnabled( $context ) ) {
@@ -1511,7 +1510,7 @@ class DefaultPreferencesFactory implements PreferencesFactory {
                }
 
                /**
-                * @var $htmlForm PreferencesForm
+                * @var $htmlForm HTMLForm
                 */
                $htmlForm = new $formClass( $formDescriptor, $context, 'prefs' );
 
@@ -1522,7 +1521,7 @@ class DefaultPreferencesFactory implements PreferencesFactory {
                # Used message keys: 'accesskey-preferences-save', 'tooltip-preferences-save'
                $htmlForm->setSubmitTooltip( 'preferences-save' );
                $htmlForm->setSubmitID( 'prefcontrol' );
-               $htmlForm->setSubmitCallback( function ( array $formData, PreferencesForm $form ) {
+               $htmlForm->setSubmitCallback( function ( array $formData, HTMLForm $form ) {
                        return $this->submitForm( $formData, $form );
                } );
 
@@ -1627,10 +1626,10 @@ class DefaultPreferencesFactory implements PreferencesFactory {
         * Handle the form submission if everything validated properly
         *
         * @param array $formData
-        * @param PreferencesForm $form
+        * @param HTMLForm $form
         * @return bool|Status|string
         */
-       protected function saveFormData( $formData, PreferencesForm $form ) {
+       protected function saveFormData( $formData, HTMLForm $form ) {
                $user = $form->getModifiedUser();
                $hiddenPrefs = $this->config->get( 'HiddenPrefs' );
                $result = true;
@@ -1707,10 +1706,10 @@ class DefaultPreferencesFactory implements PreferencesFactory {
         * @deprecated since 1.31, its inception
         *
         * @param array $formData
-        * @param PreferencesForm $form
+        * @param HTMLForm $form
         * @return bool|Status|string
         */
-       public function legacySaveFormData( $formData, PreferencesForm $form ) {
+       public function legacySaveFormData( $formData, HTMLForm $form ) {
                return $this->saveFormData( $formData, $form );
        }
 
@@ -1718,10 +1717,10 @@ class DefaultPreferencesFactory implements PreferencesFactory {
         * Save the form data and reload the page
         *
         * @param array $formData
-        * @param PreferencesForm $form
+        * @param HTMLForm $form
         * @return Status
         */
-       protected function submitForm( array $formData, PreferencesForm $form ) {
+       protected function submitForm( array $formData, HTMLForm $form ) {
                $res = $this->saveFormData( $formData, $form );
 
                if ( $res ) {
@@ -1759,10 +1758,10 @@ class DefaultPreferencesFactory implements PreferencesFactory {
         * @deprecated since 1.31, its inception
         *
         * @param array $formData
-        * @param PreferencesForm $form
+        * @param HTMLForm $form
         * @return Status
         */
-       public function legacySubmitForm( array $formData, PreferencesForm $form ) {
+       public function legacySubmitForm( array $formData, HTMLForm $form ) {
                return $this->submitForm( $formData, $form );
        }
 

diff --git a/includes/specials/SpecialPreferences.php b/includes/specials/SpecialPreferences.php
index 7a4cde9..27b6a07 100644 (file)
--- a/includes/specials/SpecialPreferences.php
+++ b/includes/specials/SpecialPreferences.php
@@ -40,6 +40,8 @@ class SpecialPreferences extends SpecialPage {
 
        /**
         * Check if OOUI mode is enabled, by config or query string
+        *
+        * @since 1.32
         * @param IContextSource $context The context.
         * @return bool
         */

diff --git a/includes/specials/forms/PreferencesForm.php b/includes/specials/forms/PreferencesForm.php
deleted file mode 100644 (file)
index a124410..0000000
--- a/includes/specials/forms/PreferencesForm.php
+++ /dev/null
@@ -1,28 +0,0 @@
-<?php
-/**
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
- * (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License along
- * with this program; if not, write to the Free Software Foundation, Inc.,
- * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
- * http://www.gnu.org/copyleft/gpl.html
- *
- * @file
- */
-
-/**
- * Temporarily define PreferencesForm as an interface, so PreferencesFormOOUI
- * and PreferencesFormLegacy can implement it.
- *
- * When PreferencesFormLegacy we can merge PreferencesFormOOUI with PreferencesForm.
- */
-interface PreferencesForm {
-}

diff --git a/includes/specials/forms/PreferencesFormLegacy.php b/includes/specials/forms/PreferencesFormLegacy.php
index e6bc494..8193c5a 100644 (file)
--- a/includes/specials/forms/PreferencesFormLegacy.php
+++ b/includes/specials/forms/PreferencesFormLegacy.php
@@ -22,8 +22,10 @@ use MediaWiki\MediaWikiServices;
 
 /**
  * Form to edit user preferences.
+ *
+ * @since 1.32
  */
-class PreferencesFormLegacy extends HTMLForm implements PreferencesForm {
+class PreferencesFormLegacy extends HTMLForm {
        // Override default value from HTMLForm
        protected $mSubSectionBeforeFields = false;
 
@@ -141,3 +143,10 @@ class PreferencesFormLegacy extends HTMLForm implements PreferencesForm {
                return array_keys( array_filter( $this->mFieldTree, 'is_array' ) );
        }
 }
+
+// Retain the old class name for backwards compatibility.
+// In the future, this alias will be changed to point to PreferencesFormOOUI.
+class PreferencesForm extends PreferencesFormLegacy {
+}
+// Phan doesn't understand class_alias()?
+// class_alias( PreferencesFormLegacy::class, 'PreferencesForm' );

diff --git a/includes/specials/forms/PreferencesFormOOUI.php b/includes/specials/forms/PreferencesFormOOUI.php
index 3a5adbb..47a595f 100644 (file)
--- a/includes/specials/forms/PreferencesFormOOUI.php
+++ b/includes/specials/forms/PreferencesFormOOUI.php
@@ -20,8 +20,10 @@
 
 /**
  * Form to edit user preferences.
+ *
+ * @since 1.32
  */
-class PreferencesFormOOUI extends OOUIHTMLForm implements PreferencesForm {
+class PreferencesFormOOUI extends OOUIHTMLForm {
        // Override default value from HTMLForm
        protected $mSubSectionBeforeFields = false;
 

diff --git a/resources/src/mediawiki.legacy/oldshared.css b/resources/src/mediawiki.legacy/oldshared.css
index b95a436..ac65ac7 100644 (file)
--- a/resources/src/mediawiki.legacy/oldshared.css
+++ b/resources/src/mediawiki.legacy/oldshared.css
@@ -215,7 +215,7 @@ table.toc td {
 }
 
 /* preference page with js-genrated toc */
-/* TODO: Delete #preftoc when Special:Preference's non-OOUI mode is disabled */
+/* TODO: Delete #preftoc when Special:Preferences's non-OOUI mode is disabled */
 #preftoc {
        float: left;
        margin: 1em 1em 1em 1em;