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          * Changes preferences of the current user.
  36          */
  37         public function execute() {
  38                 $user = $this->getUser();
  39
  40                 if ( $user->isAnon() ) {
  41                         $this->dieUsage( 'Anonymous users cannot change preferences', 'notloggedin' );
  42                 }
  43
  44                 if ( !$user->isAllowed( 'editmyoptions' ) ) {
  45                         $this->dieUsage( 'You don\'t have permission to edit your options', 'permissiondenied' );
  46                 }
  47
  48                 $params = $this->extractRequestParams();
  49                 $changed = false;
  50
  51                 if ( isset( $params['optionvalue'] ) && !isset( $params['optionname'] ) ) {
  52                         $this->dieUsageMsg( array( 'missingparam', 'optionname' ) );
  53                 }
  54
  55                 if ( $params['reset'] ) {
  56                         $user->resetOptions( $params['resetkinds'], $this->getContext() );
  57                         $changed = true;
  58                 }
  59
  60                 $changes = array();
  61                 if ( count( $params['change'] ) ) {
  62                         foreach ( $params['change'] as $entry ) {
  63                                 $array = explode( '=', $entry, 2 );
  64                                 $changes[$array[0]] = isset( $array[1] ) ? $array[1] : null;
  65                         }
  66                 }
  67                 if ( isset( $params['optionname'] ) ) {
  68                         $newValue = isset( $params['optionvalue'] ) ? $params['optionvalue'] : null;
  69                         $changes[$params['optionname']] = $newValue;
  70                 }
  71                 if ( !$changed && !count( $changes ) ) {
  72                         $this->dieUsage( 'No changes were requested', 'nochanges' );
  73                 }
  74
  75                 $prefs = Preferences::getPreferences( $user, $this->getContext() );
  76                 $prefsKinds = $user->getOptionKinds( $this->getContext(), $changes );
  77
  78                 foreach ( $changes as $key => $value ) {
  79                         switch ( $prefsKinds[$key] ) {
  80                                 case 'registered':
  81                                         // Regular option.
  82                                         $field = HTMLForm::loadInputFromParameters( $key, $prefs[$key] );
  83                                         $validation = $field->validate( $value, $user->getOptions() );
  84                                         break;
  85                                 case 'registered-multiselect':
  86                                 case 'registered-checkmatrix':
  87                                         // A key for a multiselect or checkmatrix option.
  88                                         $validation = true;
  89                                         $value = $value !== null ? (bool)$value : null;
  90                                         break;
  91                                 case 'userjs':
  92                                         // Allow non-default preferences prefixed with 'userjs-', to be set by user scripts
  93                                         if ( strlen( $key ) > 255 ) {
  94                                                 $validation = "key too long (no more than 255 bytes allowed)";
  95                                         } elseif ( preg_match( "/[^a-zA-Z0-9_-]/", $key ) !== 0 ) {
  96                                                 $validation = "invalid key (only a-z, A-Z, 0-9, _, - allowed)";
  97                                         } else {
  98                                                 $validation = true;
  99                                         }
 100                                         break;
 101                                 case 'special':
 102                                         $validation = "cannot be set by this module";
 103                                         break;
 104                                 case 'unused':
 105                                 default:
 106                                         $validation = "not a valid preference";
 107                                         break;
 108                         }
 109                         if ( $validation === true ) {
 110                                 $user->setOption( $key, $value );
 111                                 $changed = true;
 112                         } else {
 113                                 $this->setWarning( "Validation error for '$key': $validation" );
 114                         }
 115                 }
 116
 117                 if ( $changed ) {
 118                         // Commit changes
 119                         $user->saveSettings();
 120                 }
 121
 122                 $this->getResult()->addValue( null, $this->getModuleName(), 'success' );
 123         }
 124
 125         public function mustBePosted() {
 126                 return true;
 127         }
 128
 129         public function isWriteMode() {
 130                 return true;
 131         }
 132
 133         public function getAllowedParams() {
 134                 $optionKinds = User::listOptionKinds();
 135                 $optionKinds[] = 'all';
 136
 137                 return array(
 138                         'token' => array(
 139                                 ApiBase::PARAM_TYPE => 'string',
 140                                 ApiBase::PARAM_REQUIRED => true
 141                         ),
 142                         'reset' => false,
 143                         'resetkinds' => array(
 144                                 ApiBase::PARAM_TYPE => $optionKinds,
 145                                 ApiBase::PARAM_DFLT => 'all',
 146                                 ApiBase::PARAM_ISMULTI => true
 147                         ),
 148                         'change' => array(
 149                                 ApiBase::PARAM_ISMULTI => true,
 150                         ),
 151                         'optionname' => array(
 152                                 ApiBase::PARAM_TYPE => 'string',
 153                         ),
 154                         'optionvalue' => array(
 155                                 ApiBase::PARAM_TYPE => 'string',
 156                         ),
 157                 );
 158         }
 159
 160         public function getResultProperties() {
 161                 return array(
 162                         '' => array(
 163                                 '*' => array(
 164                                         ApiBase::PROP_TYPE => array(
 165                                                 'success'
 166                                         )
 167                                 )
 168                         )
 169                 );
 170         }
 171
 172         public function getParamDescription() {
 173                 return array(
 174                         'token' => 'An options token previously obtained through the action=tokens',
 175                         'reset' => 'Resets preferences to the site defaults',
 176                         'resetkinds' => 'List of types of options to reset when the "reset" option is set',
 177                         'change' => array( 'List of changes, formatted name=value (e.g. skin=vector), ' .
 178                                 'value cannot contain pipe characters. If no value is given (not ',
 179                                 'even an equals sign), e.g., optionname|otheroption|..., the ' .
 180                                 'option will be reset to its default value'
 181                         ),
 182                         'optionname' => 'A name of a option which should have an optionvalue set',
 183                         'optionvalue' => 'A value of the option specified by the optionname, ' .
 184                                 'can contain pipe characters',
 185                 );
 186         }
 187
 188         public function getDescription() {
 189                 return array(
 190                         'Change preferences of the current user.',
 191                         'Only options which are registered in core or in one of installed extensions,',
 192                         'or as options with keys prefixed with \'userjs-\' (intended to be used by user',
 193                         'scripts), can be set.'
 194                 );
 195         }
 196
 197         public function getPossibleErrors() {
 198                 return array_merge( parent::getPossibleErrors(), array(
 199                         array( 'code' => 'notloggedin', 'info' => 'Anonymous users cannot change preferences' ),
 200                         array( 'code' => 'nochanges', 'info' => 'No changes were requested' ),
 201                 ) );
 202         }
 203
 204         public function needsToken() {
 205                 return true;
 206         }
 207
 208         public function getTokenSalt() {
 209                 return '';
 210         }
 211
 212         public function getHelpUrls() {
 213                 return 'https://www.mediawiki.org/wiki/API:Options';
 214         }
 215
 216         public function getExamples() {
 217                 return array(
 218                         'api.php?action=options&reset=&token=123ABC',
 219                         'api.php?action=options&change=skin=vector|hideminor=1&token=123ABC',
 220                         'api.php?action=options&reset=&change=skin=monobook&optionname=nickname&' .
 221                                 'optionvalue=[[User:Beau|Beau]]%20([[User_talk:Beau|talk]])&token=123ABC',
 222                 );
 223         }
 224 }