[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   *
   4   *
   5   * Created on Apr 15, 2012
   6   *
   7   * Copyright © 2012 Szymon Świerkosz [email protected]
   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              'reset' => false,
 139              'resetkinds' => array(
 140                  ApiBase::PARAM_TYPE => $optionKinds,
 141                  ApiBase::PARAM_DFLT => 'all',
 142                  ApiBase::PARAM_ISMULTI => true
 143              ),
 144              'change' => array(
 145                  ApiBase::PARAM_ISMULTI => true,
 146              ),
 147              'optionname' => array(
 148                  ApiBase::PARAM_TYPE => 'string',
 149              ),
 150              'optionvalue' => array(
 151                  ApiBase::PARAM_TYPE => 'string',
 152              ),
 153          );
 154      }
 155  
 156  	public function getParamDescription() {
 157          return array(
 158              'reset' => 'Resets preferences to the site defaults',
 159              'resetkinds' => 'List of types of options to reset when the "reset" option is set',
 160              'change' => array( 'List of changes, formatted name=value (e.g. skin=vector), ' .
 161                  'value cannot contain pipe characters. If no value is given (not ',
 162                  'even an equals sign), e.g., optionname|otheroption|..., the ' .
 163                  'option will be reset to its default value'
 164              ),
 165              'optionname' => 'A name of a option which should have an optionvalue set',
 166              'optionvalue' => 'A value of the option specified by the optionname, ' .
 167                  'can contain pipe characters',
 168          );
 169      }
 170  
 171  	public function getDescription() {
 172          return array(
 173              'Change preferences of the current user.',
 174              'Only options which are registered in core or in one of installed extensions,',
 175              'or as options with keys prefixed with \'userjs-\' (intended to be used by user',
 176              'scripts), can be set.'
 177          );
 178      }
 179  
 180  	public function needsToken() {
 181          return 'csrf';
 182      }
 183  
 184  	public function getHelpUrls() {
 185          return 'https://www.mediawiki.org/wiki/API:Options';
 186      }
 187  
 188  	public function getExamples() {
 189          return array(
 190              'api.php?action=options&reset=&token=123ABC',
 191              'api.php?action=options&change=skin=vector|hideminor=1&token=123ABC',
 192              'api.php?action=options&reset=&change=skin=monobook&optionname=nickname&' .
 193                  'optionvalue=[[User:Beau|Beau]]%20([[User_talk:Beau|talk]])&token=123ABC',
 194          );
 195      }
 196  }