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         public function __construct( $main, $action ) {
  36                 parent::__construct( $main, $action );
  37         }
  38
  39         /**
  40          * Changes preferences of the current user.
  41          */
  42         public function execute() {
  43                 $user = $this->getUser();
  44
  45                 if ( $user->isAnon() ) {
  46                         $this->dieUsage( 'Anonymous users cannot change preferences', 'notloggedin' );
  47                 }
  48
  49                 $params = $this->extractRequestParams();
  50                 $changed = false;
  51
  52                 if ( isset( $params['optionvalue'] ) && !isset( $params['optionname'] ) ) {
  53                         $this->dieUsageMsg( array( 'missingparam', 'optionname' ) );
  54                 }
  55
  56                 if ( $params['reset'] ) {
  57                         $user->resetOptions();
  58                         $changed = true;
  59                 }
  60
  61                 $changes = array();
  62                 if ( count( $params['change'] ) ) {
  63                         foreach ( $params['change'] as $entry ) {
  64                                 $array = explode( '=', $entry, 2 );
  65                                 $changes[$array[0]] = isset( $array[1] ) ? $array[1] : null;
  66                         }
  67                 }
  68                 if ( isset( $params['optionname'] ) ) {
  69                         $newValue = isset( $params['optionvalue'] ) ? $params['optionvalue'] : null;
  70                         $changes[$params['optionname']] = $newValue;
  71                 }
  72                 if ( !$changed && !count( $changes ) ) {
  73                         $this->dieUsage( 'No changes were requested', 'nochanges' );
  74                 }
  75
  76                 $prefs = Preferences::getPreferences( $user, $this->getContext() );
  77
  78                 // Multiselect options are stored in the database with one key per
  79                 // option, each having a boolean value. Extract those keys.
  80                 $multiselectOptions = array();
  81                 foreach ( $prefs as $name => $info ) {
  82                         if ( ( isset( $info['type'] ) && $info['type'] == 'multiselect' ) ||
  83                                         ( isset( $info['class'] ) && $info['class'] == 'HTMLMultiSelectField' ) ) {
  84                                 $options = HTMLFormField::flattenOptions( $info['options'] );
  85                                 $prefix = isset( $info['prefix'] ) ? $info['prefix'] : $name;
  86
  87                                 foreach ( $options as $value ) {
  88                                         $multiselectOptions["$prefix$value"] = true;
  89                                 }
  90
  91                                 unset( $prefs[$name] );
  92                         }
  93                 }
  94
  95                 foreach ( $changes as $key => $value ) {
  96                         if ( isset( $prefs[$key] ) ) {
  97                                 $field = HTMLForm::loadInputFromParameters( $key, $prefs[$key] );
  98                                 $validation = $field->validate( $value, $user->getOptions() );
  99                         } elseif( isset( $multiselectOptions[$key] ) ) {
 100                                 // A key for a multiselect option.
 101                                 $validation = true;
 102                                 $value = (bool)$value;
 103                         } else {
 104                                 $this->setWarning( "Not a valid preference: $key" );
 105                                 continue;
 106                         }
 107                         if ( $validation === true ) {
 108                                 $user->setOption( $key, $value );
 109                                 $changed = true;
 110                         } else {
 111                                 $this->setWarning( "Validation error for '$key': $validation" );
 112                         }
 113                 }
 114
 115                 if ( $changed ) {
 116                         // Commit changes
 117                         $user->saveSettings();
 118                 }
 119
 120                 $this->getResult()->addValue( null, $this->getModuleName(), 'success' );
 121         }
 122
 123         public function mustBePosted() {
 124                 return true;
 125         }
 126
 127         public function isWriteMode() {
 128                 return true;
 129         }
 130
 131         public function getAllowedParams() {
 132                 return array(
 133                         'token' => array(
 134                                 ApiBase::PARAM_TYPE => 'string',
 135                                 ApiBase::PARAM_REQUIRED => true
 136                         ),
 137                         'reset' => false,
 138                         'change' => array(
 139                                 ApiBase::PARAM_ISMULTI => true,
 140                         ),
 141                         'optionname' => array(
 142                                 ApiBase::PARAM_TYPE => 'string',
 143                         ),
 144                         'optionvalue' => array(
 145                                 ApiBase::PARAM_TYPE => 'string',
 146                         ),
 147                 );
 148         }
 149
 150         public function getResultProperties() {
 151                 return array(
 152                         '' => array(
 153                                 '*' => array(
 154                                         ApiBase::PROP_TYPE => array(
 155                                                 'success'
 156                                         )
 157                                 )
 158                         )
 159                 );
 160         }
 161
 162         public function getParamDescription() {
 163                 return array(
 164                         'token' => 'An options token previously obtained through the action=tokens',
 165                         'reset' => 'Resets all preferences to the site defaults',
 166                         'change' => 'List of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters',
 167                         'optionname' => 'A name of a option which should have an optionvalue set',
 168                         'optionvalue' => 'A value of the option specified by the optionname, can contain pipe characters',
 169                 );
 170         }
 171
 172         public function getDescription() {
 173                 return 'Change preferences of the current user';
 174         }
 175
 176         public function getPossibleErrors() {
 177                 return array_merge( parent::getPossibleErrors(), array(
 178                         array( 'code' => 'notloggedin', 'info' => 'Anonymous users cannot change preferences' ),
 179                         array( 'code' => 'nochanges', 'info' => 'No changes were requested' ),
 180                 ) );
 181         }
 182
 183         public function needsToken() {
 184                 return true;
 185         }
 186
 187         public function getTokenSalt() {
 188                 return '';
 189         }
 190
 191         public function getHelpUrls() {
 192                 return 'https://www.mediawiki.org/wiki/API:Options';
 193         }
 194
 195         public function getExamples() {
 196                 return array(
 197                         'api.php?action=options&reset=&token=123ABC',
 198                         'api.php?action=options&change=skin=vector|hideminor=1&token=123ABC',
 199                         'api.php?action=options&reset=&change=skin=monobook&optionname=nickname&optionvalue=[[User:Beau|Beau]]%20([[User_talk:Beau|talk]])&token=123ABC',
 200                 );
 201         }
 202
 203         public function getVersion() {
 204                 return __CLASS__ . ': $Id$';
 205         }
 206 }