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 ( !count( $changes ) ) {
  73                         $this->dieUsage( 'No changes were requested', 'nochanges' );
  74                 }
  75
  76                 $prefs = Preferences::getPreferences( $user, $this->getContext() );
  77                 foreach ( $changes as $key => $value ) {
  78                         if ( !isset( $prefs[$key] ) ) {
  79                                 $this->setWarning( "Not a valid preference: $key" );
  80                                 continue;
  81                         }
  82                         $field = HTMLForm::loadInputFromParameters( $key, $prefs[$key] );
  83                         $validation = $field->validate( $value, $user->getOptions() );
  84                         if ( $validation === true ) {
  85                                 $user->setOption( $key, $value );
  86                                 $changed = true;
  87                         } else {
  88                                 $this->setWarning( "Validation error for '$key': $validation" );
  89                         }
  90                 }
  91
  92                 if ( $changed ) {
  93                         // Commit changes
  94                         $user->saveSettings();
  95                 }
  96
  97                 $this->getResult()->addValue( null, $this->getModuleName(), 'success' );
  98         }
  99
 100         public function mustBePosted() {
 101                 return true;
 102         }
 103
 104         public function isWriteMode() {
 105                 return true;
 106         }
 107
 108         public function getAllowedParams() {
 109                 return array(
 110                         'token' => array(
 111                                 ApiBase::PARAM_TYPE => 'string',
 112                                 ApiBase::PARAM_REQUIRED => true
 113                         ),
 114                         'reset' => false,
 115                         'change' => array(
 116                                 ApiBase::PARAM_ISMULTI => true,
 117                         ),
 118                         'optionname' => array(
 119                                 ApiBase::PARAM_TYPE => 'string',
 120                         ),
 121                         'optionvalue' => array(
 122                                 ApiBase::PARAM_TYPE => 'string',
 123                         ),
 124                 );
 125         }
 126
 127         public function getResultProperties() {
 128                 return array(
 129                         '' => array(
 130                                 '*' => array(
 131                                         ApiBase::PROP_TYPE => array(
 132                                                 'success'
 133                                         )
 134                                 )
 135                         )
 136                 );
 137         }
 138
 139         public function getParamDescription() {
 140                 return array(
 141                         'token' => 'An options token previously obtained through the action=tokens',
 142                         'reset' => 'Resets all preferences to the site defaults',
 143                         'change' => 'List of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters',
 144                         'optionname' => 'A name of a option which should have an optionvalue set',
 145                         'optionvalue' => 'A value of the option specified by the optionname, can contain pipe characters',
 146                 );
 147         }
 148
 149         public function getDescription() {
 150                 return 'Change preferences of the current user';
 151         }
 152
 153         public function getPossibleErrors() {
 154                 return array_merge( parent::getPossibleErrors(), array(
 155                         array( 'code' => 'notloggedin', 'info' => 'Anonymous users cannot change preferences' ),
 156                         array( 'code' => 'nochanges', 'info' => 'No changes were requested' ),
 157                 ) );
 158         }
 159
 160         public function needsToken() {
 161                 return true;
 162         }
 163
 164         public function getTokenSalt() {
 165                 return '';
 166         }
 167
 168         public function getHelpUrls() {
 169                 return 'https://www.mediawiki.org/wiki/API:Options';
 170         }
 171
 172         public function getExamples() {
 173                 return array(
 174                         'api.php?action=options&reset=&token=123ABC',
 175                         'api.php?action=options&change=skin=vector|hideminor=1&token=123ABC',
 176                         'api.php?action=options&reset=&change=skin=monobook&optionname=nickname&optionvalue=[[User:Beau|Beau]]%20([[User_talk:Beau|talk]])&token=123ABC',
 177                 );
 178         }
 179
 180         public function getVersion() {
 181                 return __CLASS__ . ': $Id$';
 182         }
 183 }