3 * Copyright © 2012 Szymon Świerkosz beau@adres.pl
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
23 use MediaWiki\MediaWikiServices
;
26 * API module that facilitates the changing of user's preferences.
27 * Requires API write mode to be enabled.
31 class ApiOptions
extends ApiBase
{
32 /** @var User User account to modify */
33 private $userForUpdates;
36 * Changes preferences of the current user.
38 public function execute() {
39 $user = $this->getUserForUpdates();
40 if ( !$user ||
$user->isAnon() ) {
42 [ 'apierror-mustbeloggedin', $this->msg( 'action-editmyoptions' ) ], 'notloggedin'
46 $this->checkUserRightsAny( 'editmyoptions' );
48 $params = $this->extractRequestParams();
51 if ( isset( $params['optionvalue'] ) && !isset( $params['optionname'] ) ) {
52 $this->dieWithError( [ 'apierror-missingparam', 'optionname' ] );
55 if ( $params['reset'] ) {
56 $this->resetPreferences( $params['resetkinds'] );
61 if ( $params['change'] ) {
62 foreach ( $params['change'] as $entry ) {
63 $array = explode( '=', $entry, 2 );
64 $changes[$array[0]] = $array[1] ??
null;
67 if ( isset( $params['optionname'] ) ) {
68 $newValue = $params['optionvalue'] ??
null;
69 $changes[$params['optionname']] = $newValue;
71 if ( !$changed && !count( $changes ) ) {
72 $this->dieWithError( 'apierror-nochanges' );
75 $prefs = $this->getPreferences();
76 $prefsKinds = $user->getOptionKinds( $this->getContext(), $changes );
79 foreach ( $changes as $key => $value ) {
80 switch ( $prefsKinds[$key] ) {
83 if ( $value === null ) {
88 if ( $htmlForm === null ) {
89 // We need a dummy HTMLForm for the validate callback...
90 $htmlForm = new HTMLForm( [], $this );
92 $field = HTMLForm
::loadInputFromParameters( $key, $prefs[$key], $htmlForm );
93 $validation = $field->validate( $value, $user->getOptions() );
96 case 'registered-multiselect':
97 case 'registered-checkmatrix':
98 // A key for a multiselect or checkmatrix option.
100 $value = $value !== null ?
(bool)$value : null;
103 // Allow non-default preferences prefixed with 'userjs-', to be set by user scripts
104 if ( strlen( $key ) > 255 ) {
105 $validation = $this->msg( 'apiwarn-validationfailed-keytoolong', Message
::numParam( 255 ) );
106 } elseif ( preg_match( '/[^a-zA-Z0-9_-]/', $key ) !== 0 ) {
107 $validation = $this->msg( 'apiwarn-validationfailed-badchars' );
113 $validation = $this->msg( 'apiwarn-validationfailed-cannotset' );
117 $validation = $this->msg( 'apiwarn-validationfailed-badpref' );
120 if ( $validation === true ) {
121 $this->setPreference( $key, $value );
124 $this->addWarning( [ 'apiwarn-validationfailed', wfEscapeWikiText( $key ), $validation ] );
129 $this->commitChanges();
132 $this->getResult()->addValue( null, $this->getModuleName(), 'success' );
136 * Load the user from the master to reduce CAS errors on double post (T95839)
140 protected function getUserForUpdates() {
141 if ( !$this->userForUpdates
) {
142 $this->userForUpdates
= $this->getUser()->getInstanceForUpdate();
145 return $this->userForUpdates
;
149 * Returns preferences form descriptor
152 protected function getPreferences() {
153 $preferencesFactory = MediaWikiServices
::getInstance()->getPreferencesFactory();
154 return $preferencesFactory->getFormDescriptor( $this->getUserForUpdates(),
155 $this->getContext() );
159 * @param string[] $kinds One or more types returned by User::listOptionKinds() or 'all'
161 protected function resetPreferences( array $kinds ) {
162 $this->getUserForUpdates()->resetOptions( $kinds, $this->getContext() );
166 * Sets one user preference to be applied by commitChanges()
168 * @param string $preference
169 * @param mixed $value
171 protected function setPreference( $preference, $value ) {
172 $this->getUserForUpdates()->setOption( $preference, $value );
176 * Applies changes to user preferences
178 protected function commitChanges() {
179 $this->getUserForUpdates()->saveSettings();
182 public function mustBePosted() {
186 public function isWriteMode() {
190 public function getAllowedParams() {
191 $optionKinds = User
::listOptionKinds();
192 $optionKinds[] = 'all';
197 ApiBase
::PARAM_TYPE
=> $optionKinds,
198 ApiBase
::PARAM_DFLT
=> 'all',
199 ApiBase
::PARAM_ISMULTI
=> true
202 ApiBase
::PARAM_ISMULTI
=> true,
205 ApiBase
::PARAM_TYPE
=> 'string',
208 ApiBase
::PARAM_TYPE
=> 'string',
213 public function needsToken() {
217 public function getHelpUrls() {
218 return 'https://www.mediawiki.org/wiki/Special:MyLanguage/API:Options';
221 protected function getExamplesMessages() {
223 'action=options&reset=&token=123ABC'
224 => 'apihelp-options-example-reset',
225 'action=options&change=skin=vector|hideminor=1&token=123ABC'
226 => 'apihelp-options-example-change',
227 'action=options&reset=&change=skin=monobook&optionname=nickname&' .
228 'optionvalue=[[User:Beau|Beau]]%20([[User_talk:Beau|talk]])&token=123ABC'
229 => 'apihelp-options-example-complex',