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                 $changes = 0;
  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                         $changes++;
  59                 }
  60                 if ( count( $params['change'] ) ) {
  61                         foreach ( $params['change'] as $entry ) {
  62                                 $array = explode( '=', $entry, 2 );
  63                                 $user->setOption( $array[0], isset( $array[1] ) ? $array[1] : null );
  64                                 $changes++;
  65                         }
  66                 }
  67                 if ( isset( $params['optionname'] ) ) {
  68                         $newValue = isset( $params['optionvalue'] ) ? $params['optionvalue'] : null;
  69                         $user->setOption( $params['optionname'], $newValue );
  70                         $changes++;
  71                 }
  72
  73                 if ( $changes ) {
  74                         // Commit changes
  75                         $user->saveSettings();
  76                 } else {
  77                         $this->dieUsage( 'No changes were requested', 'nochanges' );
  78                 }
  79
  80                 $this->getResult()->addValue( null, $this->getModuleName(), 'success' );
  81         }
  82
  83         public function mustBePosted() {
  84                 return true;
  85         }
  86
  87         public function isWriteMode() {
  88                 return true;
  89         }
  90
  91         public function getAllowedParams() {
  92                 return array(
  93                         'token' => array(
  94                                 ApiBase::PARAM_TYPE => 'string',
  95                                 ApiBase::PARAM_REQUIRED => true
  96                         ),
  97                         'reset' => false,
  98                         'change' => array(
  99                                 ApiBase::PARAM_ISMULTI => true,
 100                         ),
 101                         'optionname' => array(
 102                                 ApiBase::PARAM_TYPE => 'string',
 103                         ),
 104                         'optionvalue' => array(
 105                                 ApiBase::PARAM_TYPE => 'string',
 106                         ),
 107                 );
 108         }
 109
 110         public function getResultProperties() {
 111                 return array(
 112                         '' => array(
 113                                 '*' => array(
 114                                         ApiBase::PROP_TYPE => array(
 115                                                 'success'
 116                                         )
 117                                 )
 118                         )
 119                 );
 120         }
 121
 122         public function getParamDescription() {
 123                 return array(
 124                         'token' => 'An options token previously obtained through the action=tokens',
 125                         'reset' => 'Resets all preferences to the site defaults',
 126                         'change' => 'Pipe-separated list of changes, formatted name=value (e.g. skin=vector), value cannot contain pipe characters',
 127                         'optionname' => 'A name of a option which should have an optionvalue set',
 128                         'optionvalue' => 'A value of the option specified by the optionname, can contain pipe characters',
 129                 );
 130         }
 131
 132         public function getDescription() {
 133                 return 'Change preferences of the current user';
 134         }
 135
 136         public function getPossibleErrors() {
 137                 return array_merge( parent::getPossibleErrors(), array(
 138                         array( 'notloggedin' ),
 139                         array( 'nochanges' ),
 140                 ) );
 141         }
 142
 143         public function needsToken() {
 144                 return true;
 145         }
 146
 147         public function getTokenSalt() {
 148                 return '';
 149         }
 150
 151         public function getHelpUrls() {
 152                 return 'https://www.mediawiki.org/wiki/API:Options';
 153         }
 154
 155         public function getExamples() {
 156                 return array(
 157                         'api.php?action=options&reset=&token=123ABC',
 158                         'api.php?action=options&change=skin=vector|hideminor=1&token=123ABC',
 159                         'api.php?action=options&reset=&change=skin=monobook&optionname=nickname&optionvalue=[[User:Beau|Beau]]%20([[User_talk:Beau|talk]])&token=123ABC',
 160                 );
 161         }
 162
 163         public function getVersion() {
 164                 return __CLASS__ . ': $Id$';
 165         }
 166 }