- wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) );
-
- return $desc;
- }
-
- /**
- * Formerly used to fetch a list of possible properites in the result,
- * somehow organized with respect to the prop parameter that causes them to
- * be returned. The specific semantics of the return value was never
- * specified. Since this was never possible to be accurately updated, it
- * has been removed.
- *
- * @deprecated since 1.24
- * @return array|bool
- */
- protected function getResultProperties() {
- wfDeprecated( __METHOD__, '1.24' );
- return false;
- }
-
- /**
- * @see self::getResultProperties()
- * @deprecated since 1.24
- * @return array|bool
- */
- public function getFinalResultProperties() {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
- /**
- * @see self::getResultProperties()
- * @deprecated since 1.24
- */
- protected static function addTokenProperties( &$props, $tokenFunctions ) {
- wfDeprecated( __METHOD__, '1.24' );
- }
-
- /**
- * Get final module description, after hooks have had a chance to tweak it as
- * needed.
- *
- * @return array|bool False on no parameters
- */
- public function getFinalDescription() {
- $desc = $this->getDescription();
- wfRunHooks( 'APIGetDescription', array( &$this, &$desc ) );
-
- return $desc;
- }
-
- /**
- * This method mangles parameter name based on the prefix supplied to the constructor.
- * Override this method to change parameter name during runtime
- * @param string $paramName Parameter name
- * @return string Prefixed parameter name
- */
- public function encodeParamName( $paramName ) {
- return $this->mModulePrefix . $paramName;
- }
-
- /**
- * Using getAllowedParams(), this function makes an array of the values
- * provided by the user, with key being the name of the variable, and
- * value - validated value from user or default. limits will not be
- * parsed if $parseLimit is set to false; use this when the max
- * limit is not definitive yet, e.g. when getting revisions.
- * @param bool $parseLimit True by default
- * @return array
- */
- public function extractRequestParams( $parseLimit = true ) {
- // Cache parameters, for performance and to avoid bug 24564.
- if ( !isset( $this->mParamCache[$parseLimit] ) ) {
- $params = $this->getFinalParams();
- $results = array();
-
- if ( $params ) { // getFinalParams() can return false
- foreach ( $params as $paramName => $paramSettings ) {
- $results[$paramName] = $this->getParameterFromSettings(
- $paramName, $paramSettings, $parseLimit );
- }
- }
- $this->mParamCache[$parseLimit] = $results;
- }
-
- return $this->mParamCache[$parseLimit];
- }
-
- /**
- * Get a value for the given parameter
- * @param string $paramName Parameter name
- * @param bool $parseLimit See extractRequestParams()
- * @return mixed Parameter value
- */
- protected function getParameter( $paramName, $parseLimit = true ) {
- $params = $this->getFinalParams();
- $paramSettings = $params[$paramName];
-
- return $this->getParameterFromSettings( $paramName, $paramSettings, $parseLimit );
- }
-
- /**
- * Die if none or more than one of a certain set of parameters is set and not false.
- *
- * @param array $params User provided set of parameters, as from $this->extractRequestParams()
- * @param string $required,... Names of parameters of which exactly one must be set
- */
- public function requireOnlyOneParameter( $params, $required /*...*/ ) {
- $required = func_get_args();
- array_shift( $required );
- $p = $this->getModulePrefix();
-
- $intersection = array_intersect( array_keys( array_filter( $params,
- array( $this, "parameterNotEmpty" ) ) ), $required );
-
- if ( count( $intersection ) > 1 ) {
- $this->dieUsage(
- "The parameters {$p}" . implode( ", {$p}", $intersection ) . ' can not be used together',
- 'invalidparammix' );
- } elseif ( count( $intersection ) == 0 ) {
- $this->dieUsage(
- "One of the parameters {$p}" . implode( ", {$p}", $required ) . ' is required',
- 'missingparam'
- );
- }
- }
-
- /**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
- */
- public function getRequireOnlyOneParameterErrorMessages( $params ) {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
- /**
- * Die if more than one of a certain set of parameters is set and not false.
- *
- * @param array $params User provided set of parameters, as from $this->extractRequestParams()
- * @param string $required,... Names of parameters of which at most one must be set
- */
- public function requireMaxOneParameter( $params, $required /*...*/ ) {
- $required = func_get_args();
- array_shift( $required );
- $p = $this->getModulePrefix();
-
- $intersection = array_intersect( array_keys( array_filter( $params,
- array( $this, "parameterNotEmpty" ) ) ), $required );
-
- if ( count( $intersection ) > 1 ) {
- $this->dieUsage(
- "The parameters {$p}" . implode( ", {$p}", $intersection ) . ' can not be used together',
- 'invalidparammix'
- );
- }
- }
-
- /**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
- */
- public function getRequireMaxOneParameterErrorMessages( $params ) {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
- /**
- * Die if none of a certain set of parameters is set and not false.
- *
- * @since 1.23
- * @param array $params User provided set of parameters, as from $this->extractRequestParams()
- * @param string $required,... Names of parameters of which at least one must be set
- */
- public function requireAtLeastOneParameter( $params, $required /*...*/ ) {
- $required = func_get_args();
- array_shift( $required );
- $p = $this->getModulePrefix();
-
- $intersection = array_intersect(
- array_keys( array_filter( $params, array( $this, "parameterNotEmpty" ) ) ),
- $required
- );
-
- if ( count( $intersection ) == 0 ) {
- $this->dieUsage( "At least one of the parameters {$p}" .
- implode( ", {$p}", $required ) . ' is required', "{$p}missingparam" );
- }
- }
-
- /**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
- */
- public function getRequireAtLeastOneParameterErrorMessages( $params ) {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
- /**
- * Get a WikiPage object from a title or pageid param, if possible.
- * Can die, if no param is set or if the title or page id is not valid.
- *
- * @param array $params
- * @param bool|string $load Whether load the object's state from the database:
- * - false: don't load (if the pageid is given, it will still be loaded)
- * - 'fromdb': load from a slave database
- * - 'fromdbmaster': load from the master database
- * @return WikiPage
- */
- public function getTitleOrPageId( $params, $load = false ) {
- $this->requireOnlyOneParameter( $params, 'title', 'pageid' );
-
- $pageObj = null;
- if ( isset( $params['title'] ) ) {
- $titleObj = Title::newFromText( $params['title'] );
- if ( !$titleObj || $titleObj->isExternal() ) {
- $this->dieUsageMsg( array( 'invalidtitle', $params['title'] ) );
- }
- if ( !$titleObj->canExist() ) {
- $this->dieUsage( "Namespace doesn't allow actual pages", 'pagecannotexist' );
- }
- $pageObj = WikiPage::factory( $titleObj );
- if ( $load !== false ) {
- $pageObj->loadPageData( $load );
- }
- } elseif ( isset( $params['pageid'] ) ) {
- if ( $load === false ) {
- $load = 'fromdb';
- }
- $pageObj = WikiPage::newFromID( $params['pageid'], $load );
- if ( !$pageObj ) {
- $this->dieUsageMsg( array( 'nosuchpageid', $params['pageid'] ) );
- }
- }
-
- return $pageObj;
- }
-
- /**
- * @see self::getPossibleErrors()
- * @deprecated since 1.24
- * @return array
- */
- public function getTitleOrPageIdErrorMessage() {
- wfDeprecated( __METHOD__, '1.24' );
- return array();
- }
-
- /**
- * Callback function used in requireOnlyOneParameter to check whether required parameters are set
- *
- * @param object $x Parameter to check is not null/false
- * @return bool
- */
- private function parameterNotEmpty( $x ) {
- return !is_null( $x ) && $x !== false;
- }
-
- /**
- * Return true if we're to watch the page, false if not, null if no change.
- * @param string $watchlist Valid values: 'watch', 'unwatch', 'preferences', 'nochange'
- * @param Title $titleObj The page under consideration
- * @param string $userOption The user option to consider when $watchlist=preferences.
- * If not set will use watchdefault always and watchcreations if $titleObj doesn't exist.
- * @return bool
- */
- protected function getWatchlistValue( $watchlist, $titleObj, $userOption = null ) {
-
- $userWatching = $this->getUser()->isWatched( $titleObj, WatchedItem::IGNORE_USER_RIGHTS );
-
- switch ( $watchlist ) {
- case 'watch':
- return true;
-
- case 'unwatch':
- return false;
-
- case 'preferences':
- # If the user is already watching, don't bother checking
- if ( $userWatching ) {
- return true;
- }
- # If no user option was passed, use watchdefault and watchcreations
- if ( is_null( $userOption ) ) {
- return $this->getUser()->getBoolOption( 'watchdefault' ) ||
- $this->getUser()->getBoolOption( 'watchcreations' ) && !$titleObj->exists();
- }
-
- # Watch the article based on the user preference
- return $this->getUser()->getBoolOption( $userOption );
-
- case 'nochange':
- return $userWatching;
-
- default:
- return $userWatching;
- }
- }
-
- /**
- * Set a watch (or unwatch) based the based on a watchlist parameter.
- * @param string $watch Valid values: 'watch', 'unwatch', 'preferences', 'nochange'
- * @param Title $titleObj The article's title to change
- * @param string $userOption The user option to consider when $watch=preferences
- */
- protected function setWatch( $watch, $titleObj, $userOption = null ) {
- $value = $this->getWatchlistValue( $watch, $titleObj, $userOption );
- if ( $value === null ) {
- return;
- }
-
- WatchAction::doWatchOrUnwatch( $value, $titleObj, $this->getUser() );
- }
-
- /**
- * Using the settings determine the value for the given parameter
- *
- * @param string $paramName Parameter name
- * @param array|mixed $paramSettings Default value or an array of settings
- * using PARAM_* constants.
- * @param bool $parseLimit Parse limit?
- * @return mixed Parameter value
- */
- protected function getParameterFromSettings( $paramName, $paramSettings, $parseLimit ) {
- // Some classes may decide to change parameter names
- $encParamName = $this->encodeParamName( $paramName );
-
- if ( !is_array( $paramSettings ) ) {
- $default = $paramSettings;
- $multi = false;
- $type = gettype( $paramSettings );
- $dupes = false;
- $deprecated = false;
- $required = false;
- } else {
- $default = isset( $paramSettings[self::PARAM_DFLT] )
- ? $paramSettings[self::PARAM_DFLT]
- : null;
- $multi = isset( $paramSettings[self::PARAM_ISMULTI] )
- ? $paramSettings[self::PARAM_ISMULTI]
- : false;
- $type = isset( $paramSettings[self::PARAM_TYPE] )
- ? $paramSettings[self::PARAM_TYPE]
- : null;
- $dupes = isset( $paramSettings[self::PARAM_ALLOW_DUPLICATES] )
- ? $paramSettings[self::PARAM_ALLOW_DUPLICATES]
- : false;
- $deprecated = isset( $paramSettings[self::PARAM_DEPRECATED] )
- ? $paramSettings[self::PARAM_DEPRECATED]
- : false;
- $required = isset( $paramSettings[self::PARAM_REQUIRED] )
- ? $paramSettings[self::PARAM_REQUIRED]
- : false;
-
- // When type is not given, and no choices, the type is the same as $default
- if ( !isset( $type ) ) {
- if ( isset( $default ) ) {
- $type = gettype( $default );
- } else {
- $type = 'NULL'; // allow everything
- }
- }
- }
-
- if ( $type == 'boolean' ) {
- if ( isset( $default ) && $default !== false ) {
- // Having a default value of anything other than 'false' is not allowed
- ApiBase::dieDebug(
- __METHOD__,
- "Boolean param $encParamName's default is set to '$default'. " .
- "Boolean parameters must default to false."
- );
- }