includes/api/ApiOptions.php

   1 <?php
   2 /**
   3  *
   4  *
   5  * Created on Apr 15, 2012
   6  *
   7  * Copyright © 2012 Szymon Świerkosz beau@adres.pl
   8  *
   9  * This program is free software; you can redistribute it and/or modify
  10  * it under the terms of the GNU General Public License as published by
  11  * the Free Software Foundation; either version 2 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public License along
  20  * with this program; if not, write to the Free Software Foundation, Inc.,
  21  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  22  * http://www.gnu.org/copyleft/gpl.html
  23  *
  24  * @file
  25  */
  26
  27 /**
  28 * API module that facilitates the changing of user's preferences.
  29 * Requires API write mode to be enabled.
  30 *
  31  * @ingroup API
  32  */
  33 class ApiOptions extends ApiBase {
  34
  35         /**
  36          * Changes preferences of the current user.
  37          */
  38         public function execute() {
  39                 $user = $this->getUser();
  40
  41                 if ( $user->isAnon() ) {
  42                         $this->dieUsage( 'Anonymous users cannot change preferences', 'notloggedin' );
  43                 }
  44
  45                 $params = $this->extractRequestParams();
  46                 $changed = false;
  47
  48                 if ( isset( $params['optionvalue'] ) && !isset( $params['optionname'] ) ) {
  49                         $this->dieUsageMsg( array( 'missingparam', 'optionname' ) );
  50                 }
  51
  52                 if ( $params['reset'] ) {
  53                         $user->resetOptions( $params['resetkinds'] );
  54                         $changed = true;
  55                 }
  56
  57                 $changes = array();
  58                 if ( count( $params['change'] ) ) {
  59                         foreach ( $params['change'] as $entry ) {
  60                                 $array = explode( '=', $entry, 2 );
  61                                 $changes[$array[0]] = isset( $array[1] ) ? $array[1] : null;
  62                         }
  63                 }
  64                 if ( isset( $params['optionname'] ) ) {
  65                         $newValue = isset( $params['optionvalue'] ) ? $params['optionvalue'] : null;
  66                         $changes[$params['optionname']] = $newValue;
  67                 }
  68                 if ( !$changed && !count( $changes ) ) {
  69                         $this->dieUsage( 'No changes were requested', 'nochanges' );
  70                 }
  71
  72                 $prefs = Preferences::getPreferences( $user, $this->getContext() );
  73                 $prefsKinds = $user->getOptionKinds( $this->getContext(), $changes );
  74
  75                 foreach ( $changes as $key => $value ) {
  76                         switch ( $prefsKinds[$key] ) {
  77                                 case 'registered':
  78                                         // Regular option.
  79                                         $field = HTMLForm::loadInputFromParameters( $key, $prefs[$key] );
  80                                         $validation = $field->validate( $value, $user->getOptions() );
  81                                         break;
  82                                 case 'registered-multiselect':
  83                                         // A key for a multiselect option.
  84                                         $validation = true;
  85                                         $value = $value !== null ? (bool) $value : null;
  86                                         break;
  87                                 case 'userjs':
  88                                         // Allow non-default preferences prefixed with 'userjs-', to be set by user scripts
  89                                         if ( strlen( $key ) > 255 ) {
  90                                                 $validation = "key too long (no more than 255 bytes allowed)";
  91                                         } elseif ( preg_match( "/[^a-zA-Z0-9_-]/", $key ) !== 0 ) {
  92                                                 $validation = "invalid key (only a-z, A-Z, 0-9, _, - allowed)";
  93                                         } else {
  94                                                 $validation = true;
  95                                         }
  96                                         break;
  97                                 case 'unused':
  98                                 default:
  99                                         $validation = "not a valid preference";
 100                                         break;
 101                         }
 102                         if ( $validation === true ) {
 103                                 $user->setOption( $key, $value );
 104                                 $changed = true;
 105                         } else {
 106                                 $this->setWarning( "Validation error for '$key': $validation" );
 107                         }
 108                 }
 109
 110                 if ( $changed ) {
 111                         // Commit changes
 112                         $user->saveSettings();
 113                 }
 114
 115                 $this->getResult()->addValue( null, $this->getModuleName(), 'success' );
 116         }
 117
 118         public function mustBePosted() {
 119                 return true;
 120         }
 121
 122         public function isWriteMode() {
 123                 return true;
 124         }
 125
 126         public function getAllowedParams() {
 127                 $optionKinds = User::listOptionKinds();
 128                 $optionKinds[] = 'all';
 129
 130                 return array(
 131                         'token' => array(
 132                                 ApiBase::PARAM_TYPE => 'string',
 133                                 ApiBase::PARAM_REQUIRED => true
 134                         ),
 135                         'reset' => false,
 136                         'resetkinds' => array(
 137                                 ApiBase::PARAM_TYPE => $optionKinds,
 138                                 ApiBase::PARAM_DFLT => 'all',
 139                                 ApiBase::PARAM_ISMULTI => true
 140                         ),
 141                         'change' => array(
 142                                 ApiBase::PARAM_ISMULTI => true,
 143                         ),
 144                         'optionname' => array(
 145                                 ApiBase::PARAM_TYPE => 'string',
 146                         ),
 147                         'optionvalue' => array(
 148                                 ApiBase::PARAM_TYPE => 'string',
 149                         ),
 150                 );
 151         }
 152
 153         public function getResultProperties() {
 154                 return array(
 155                         '' => array(
 156                                 '*' => array(
 157                                         ApiBase::PROP_TYPE => array(
 158                                                 'success'
 159                                         )
 160                                 )
 161                         )
 162                 );
 163         }
 164
 165         public function getParamDescription() {
 166                 return array(
 167                         'token' => 'An options token previously obtained through the action=tokens',
 168                         'reset' => 'Resets preferences to the site defaults',
 169                         'resetkinds' => 'List of types of options to reset when the "reset" option is set',
 170                         'change' => 'List of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters. If no value is given (not even an equals sign), e.g., optionname|otheroption|..., the option will be reset to its default value',
 171                         'optionname' => 'A name of a option which should have an optionvalue set',
 172                         'optionvalue' => 'A value of the option specified by the optionname, can contain pipe characters',
 173                 );
 174         }
 175
 176         public function getDescription() {
 177                 return array(
 178                         'Change preferences of the current user',
 179                         'Only options which are registered in core or in one of installed extensions,',
 180                         'or as options with keys prefixed with \'userjs-\' (intended to be used by user scripts), can be set.'
 181                 );
 182         }
 183
 184         public function getPossibleErrors() {
 185                 return array_merge( parent::getPossibleErrors(), array(
 186                         array( 'code' => 'notloggedin', 'info' => 'Anonymous users cannot change preferences' ),
 187                         array( 'code' => 'nochanges', 'info' => 'No changes were requested' ),
 188                 ) );
 189         }
 190
 191         public function needsToken() {
 192                 return true;
 193         }
 194
 195         public function getTokenSalt() {
 196                 return '';
 197         }
 198
 199         public function getHelpUrls() {
 200                 return 'https://www.mediawiki.org/wiki/API:Options';
 201         }
 202
 203         public function getExamples() {
 204                 return array(
 205                         'api.php?action=options&reset=&token=123ABC',
 206                         'api.php?action=options&change=skin=vector|hideminor=1&token=123ABC',
 207                         'api.php?action=options&reset=&change=skin=monobook&optionname=nickname&optionvalue=[[User:Beau|Beau]]%20([[User_talk:Beau|talk]])&token=123ABC',
 208                 );
 209         }
 210 }