includes/api/ApiOptionsBase.php
<?php
/**
* Copyright © 2012 Szymon Świerkosz beau@adres.pl
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
* http://www.gnu.org/copyleft/gpl.html
*
* @file
*/
namespace MediaWiki\Api;
use MediaWiki\HTMLForm\HTMLForm;
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\Message\Message;
use MediaWiki\Preferences\DefaultPreferencesFactory;
use MediaWiki\Preferences\PreferencesFactory;
use MediaWiki\User\Options\UserOptionsManager;
use MediaWiki\User\User;
use Wikimedia\ParamValidator\ParamValidator;
/**
* The base class for core's ApiOptions and two modules in the GlobalPreferences
* extension.
*
* @ingroup API
*/
abstract class ApiOptionsBase extends ApiBase {
/** @var User User account to modify */
private $userForUpdates;
private UserOptionsManager $userOptionsManager;
private PreferencesFactory $preferencesFactory;
/** @var mixed[][]|null */
private $preferences;
/** @var HTMLForm|null */
private $htmlForm;
/** @var string[]|null */
private $prefsKinds;
/** @var array */
private $params;
/**
* @param ApiMain $main
* @param string $action
* @param UserOptionsManager $userOptionsManager
* @param PreferencesFactory $preferencesFactory
*/
public function __construct(
ApiMain $main,
$action,
UserOptionsManager $userOptionsManager,
PreferencesFactory $preferencesFactory
) {
parent::__construct( $main, $action );
$this->userOptionsManager = $userOptionsManager;
$this->preferencesFactory = $preferencesFactory;
}
/**
* Changes preferences of the current user.
*/
public function execute() {
$user = $this->getUserForUpdatesOrNull();
if ( !$user || !$user->isNamed() ) {
$this->dieWithError(
[ 'apierror-mustbeloggedin', $this->msg( 'action-editmyoptions' ) ], 'notloggedin'
);
}
$this->checkUserRightsAny( 'editmyoptions' );
$params = $this->extractRequestParams();
$changed = false;
if ( isset( $params['optionvalue'] ) && !isset( $params['optionname'] ) ) {
$this->dieWithError( [ 'apierror-missingparam', 'optionname' ] );
}
$resetKinds = $params['resetkinds'];
if ( !$params['reset'] ) {
$resetKinds = [];
}
$changes = [];
if ( $params['change'] ) {
foreach ( $params['change'] as $entry ) {
$array = explode( '=', $entry, 2 );
$changes[$array[0]] = $array[1] ?? null;
}
}
if ( isset( $params['optionname'] ) ) {
$newValue = $params['optionvalue'] ?? null;
$changes[$params['optionname']] = $newValue;
}
$this->runHook( $user, $changes, $resetKinds );
if ( $resetKinds ) {
$this->resetPreferences( $resetKinds );
$changed = true;
}
if ( !$changed && !count( $changes ) ) {
$this->dieWithError( 'apierror-nochanges' );
}
$this->prefsKinds = $this->preferencesFactory->getResetKinds( $user, $this->getContext(), $changes );
foreach ( $changes as $key => $value ) {
if ( $this->shouldIgnoreKey( $key ) ) {
continue;
}
$validation = $this->validate( $key, $value );
if ( $validation === true ) {
$this->setPreference( $key, $value );
$changed = true;
} else {
$this->addWarning( [ 'apiwarn-validationfailed', wfEscapeWikiText( $key ), $validation ] );
}
}
if ( $changed ) {
$this->commitChanges();
}
$this->getResult()->addValue( null, $this->getModuleName(), 'success' );
}
/**
* Run the ApiOptions hook if applicable
*
* @param User $user
* @param string[] $changes
* @param string[] $resetKinds
*/
protected function runHook( $user, $changes, $resetKinds ) {
}
/**
* Check whether a key should be ignored.
*
* This may be overridden to emit a warning as well as returning true.
*
* @param string $key
* @return bool
*/
protected function shouldIgnoreKey( $key ) {
return false;
}
/**
* Get the preference kinds for the current user's options.
* This can only be called after $this->prefsKinds is set in execute()
*
* @return string[]
*/
protected function getPrefsKinds(): array {
return $this->prefsKinds;
}
/**
* Get the HTMLForm for the user's preferences
*
* @return HTMLForm
*/
protected function getHtmlForm() {
if ( !$this->htmlForm ) {
$this->htmlForm = new HTMLForm(
DefaultPreferencesFactory::simplifyFormDescriptor( $this->getPreferences() ),
$this
);
}
return $this->htmlForm;
}
/**
* Validate a proposed change
*
* @param string $key
* @param mixed &$value
* @return bool|\MediaWiki\Message\Message|string
*/
protected function validate( $key, &$value ) {
switch ( $this->getPrefsKinds()[$key] ) {
case 'registered':
// Regular option.
if ( $value === null ) {
// Reset it
$validation = true;
} else {
// Validate
$field = $this->getHtmlForm()->getField( $key );
$validation = $field->validate(
$value,
$this->userOptionsManager->getOptions( $this->getUserForUpdates() )
);
}
break;
case 'registered-multiselect':
case 'registered-checkmatrix':
// A key for a multiselect or checkmatrix option.
// TODO: Apply validation properly.
$validation = true;
$value = $value !== null ? (bool)$value : null;
break;
case 'userjs':
// Allow non-default preferences prefixed with 'userjs-', to be set by user scripts
if ( strlen( $key ) > 255 ) {
$validation = $this->msg( 'apiwarn-validationfailed-keytoolong', Message::numParam( 255 ) );
} elseif ( preg_match( '/[^a-zA-Z0-9_-]/', $key ) !== 0 ) {
$validation = $this->msg( 'apiwarn-validationfailed-badchars' );
} else {
$validation = true;
}
LoggerFactory::getInstance( 'api-warning' )->info(
'ApiOptions: Setting userjs option',
[
'phab' => 'T259073',
'OptionName' => substr( $key, 0, 255 ),
'OptionValue' => substr( $value ?? '', 0, 255 ),
'OptionSize' => strlen( $value ?? '' ),
'OptionValidation' => $validation,
'UserId' => $this->getUserForUpdates()->getId(),
'RequestIP' => $this->getRequest()->getIP(),
'RequestUA' => $this->getRequest()->getHeader( 'User-Agent' )
]
);
break;
case 'special':
$validation = $this->msg( 'apiwarn-validationfailed-cannotset' );
break;
case 'unused':
default:
$validation = $this->msg( 'apiwarn-validationfailed-badpref' );
break;
}
if ( $validation === true && is_string( $value ) &&
strlen( $value ) > UserOptionsManager::MAX_BYTES_OPTION_VALUE
) {
$validation = $this->msg(
'apiwarn-validationfailed-valuetoolong',
Message::numParam( UserOptionsManager::MAX_BYTES_OPTION_VALUE )
);
}
return $validation;
}
/**
* Load the user from the primary to reduce CAS errors on double post (T95839)
* Will throw if the user is anonymous.
*
* @return User
*/
protected function getUserForUpdates(): User {
// @phan-suppress-next-line PhanTypeMismatchReturnNullable
return $this->getUserForUpdatesOrNull();
}
/**
* Get the user for updates, or null if the user is anonymous
*
* @return User|null
*/
protected function getUserForUpdatesOrNull(): ?User {
if ( !$this->userForUpdates ) {
$this->userForUpdates = $this->getUser()->getInstanceForUpdate();
}
return $this->userForUpdates;
}
/**
* Returns preferences form descriptor
* @return mixed[][]
*/
protected function getPreferences() {
if ( !$this->preferences ) {
$this->preferences = $this->preferencesFactory->getFormDescriptor(
$this->getUserForUpdates(),
$this->getContext()
);
}
return $this->preferences;
}
protected function getUserOptionsManager(): UserOptionsManager {
return $this->userOptionsManager;
}
protected function getPreferencesFactory(): PreferencesFactory {
return $this->preferencesFactory;
}
/**
* Reset preferences of the specified kinds
*
* @param string[] $kinds One or more types returned by UserOptionsManager::listOptionKinds() or 'all'
*/
abstract protected function resetPreferences( array $kinds );
/**
* Sets one user preference to be applied by commitChanges()
*
* @param string $preference
* @param mixed $value
*/
abstract protected function setPreference( $preference, $value );
/**
* Applies changes to user preferences
*/
abstract protected function commitChanges();
public function mustBePosted() {
return true;
}
public function isWriteMode() {
return true;
}
public function getAllowedParams() {
$optionKinds = $this->preferencesFactory->listResetKinds();
$optionKinds[] = 'all';
return [
'reset' => false,
'resetkinds' => [
ParamValidator::PARAM_TYPE => $optionKinds,
ParamValidator::PARAM_DEFAULT => 'all',
ParamValidator::PARAM_ISMULTI => true
],
'change' => [
ParamValidator::PARAM_ISMULTI => true,
],
'optionname' => [
ParamValidator::PARAM_TYPE => 'string',
],
'optionvalue' => [
ParamValidator::PARAM_TYPE => 'string',
],
];
}
public function needsToken() {
return 'csrf';
}
}
/** @deprecated class alias since 1.43 */
class_alias( ApiOptionsBase::class, 'ApiOptionsBase' );