* - limit: An integer or the string 'max'. Default lower limit is 0 (but
* see PARAM_MIN), and requires that PARAM_MAX and PARAM_MAX2 be
* specified. Cannot be used with PARAM_ISMULTI.
- * - namespace: An integer representing a MediaWiki namespace.
+ * - namespace: An integer representing a MediaWiki namespace. Forces PARAM_ALL = true to
+ * support easily specifying all namespaces.
* - NULL: Any string.
* - password: Any non-empty string. Input value is private or sensitive.
* <input type="password"> would be an appropriate HTML form field.
*/
const PARAM_SUBMODULE_PARAM_PREFIX = 16;
+ /**
+ * (boolean|string) When PARAM_TYPE has a defined set of values and PARAM_ISMULTI is true,
+ * this allows for an asterisk ('*') to be passed in place of a pipe-separated list of
+ * every possible value. If a string is set, it will be used in place of the asterisk.
+ * @since 1.29
+ */
+ const PARAM_ALL = 17;
+
/**@}*/
+ const ALL_DEFAULT_STRING = '*';
+
/** Fast query, standard limit. */
const LIMIT_BIG1 = 500;
/** Fast query, apihighlimits limit. */
/**
* Gets a default replica DB connection object
- * @return DatabaseBase
+ * @return Database
*/
protected function getDB() {
if ( !isset( $this->mSlaveDB ) ) {
$dupes = false;
$deprecated = false;
$required = false;
+ $allowAll = false;
} else {
$default = isset( $paramSettings[self::PARAM_DFLT] )
? $paramSettings[self::PARAM_DFLT]
$required = isset( $paramSettings[self::PARAM_REQUIRED] )
? $paramSettings[self::PARAM_REQUIRED]
: false;
+ $allowAll = isset( $paramSettings[self::PARAM_ALL] )
+ ? $paramSettings[self::PARAM_ALL]
+ : false;
// When type is not given, and no choices, the type is the same as $default
if ( !isset( $type ) ) {
if ( isset( $value ) && $type == 'namespace' ) {
$type = MWNamespace::getValidNamespaces();
+ // By default, namespace parameters allow ALL_DEFAULT_STRING to be used to specify
+ // all namespaces.
+ $allowAll = true;
}
if ( isset( $value ) && $type == 'submodule' ) {
if ( isset( $paramSettings[self::PARAM_SUBMODULE_MAP] ) ) {
}
}
+ $allSpecifier = ( is_string( $allowAll ) ? $allowAll : self::ALL_DEFAULT_STRING );
+ if ( $allowAll && $multi && is_array( $type ) && in_array( $allSpecifier, $type, true ) ) {
+ ApiBase::dieDebug(
+ __METHOD__,
+ "For param $encParamName, PARAM_ALL collides with a possible value" );
+ }
if ( isset( $value ) && ( $multi || is_array( $type ) ) ) {
$value = $this->parseMultiValue(
$encParamName,
$value,
$multi,
- is_array( $type ) ? $type : null
+ is_array( $type ) ? $type : null,
+ $allowAll ? $allSpecifier : null
);
}
* separated by '|'?
* @param string[]|null $allowedValues An array of values to check against. If
* null, all values are accepted.
+ * @param string|null $allSpecifier String to use to specify all allowed values, or null
+ * if this behavior should not be allowed
* @return string|string[] (allowMultiple ? an_array_of_values : a_single_value)
*/
- protected function parseMultiValue( $valueName, $value, $allowMultiple, $allowedValues ) {
+ protected function parseMultiValue( $valueName, $value, $allowMultiple, $allowedValues,
+ $allSpecifier = null
+ ) {
if ( ( trim( $value ) === '' || trim( $value ) === "\x1f" ) && $allowMultiple ) {
return [];
}
? self::LIMIT_SML2
: self::LIMIT_SML1;
+ if ( $allowMultiple && is_array( $allowedValues ) && $allSpecifier &&
+ count( $valuesList ) === 1 && $valuesList[0] === $allSpecifier
+ ) {
+ return $allowedValues;
+ }
+
if ( self::truncateArray( $valuesList, $sizeLimit ) ) {
$this->logFeatureUsage( "too-many-$valueName-for-{$this->getModulePath()}" );
$this->setWarning( "Too many values supplied for parameter '$valueName': " .
return false;
}
- /**
- * Generates help message for this module, or false if there is no description
- * @deprecated since 1.25
- * @return string|bool
- */
- public function makeHelpMsg() {
- wfDeprecated( __METHOD__, '1.25' );
- static $lnPrfx = "\n ";
-
- $msg = $this->getFinalDescription();
-
- if ( $msg !== false ) {
-
- if ( !is_array( $msg ) ) {
- $msg = [
- $msg
- ];
- }
- $msg = $lnPrfx . implode( $lnPrfx, $msg ) . "\n";
-
- $msg .= $this->makeHelpArrayToString( $lnPrfx, false, $this->getHelpUrls() );
-
- if ( $this->isReadMode() ) {
- $msg .= "\nThis module requires read rights";
- }
- if ( $this->isWriteMode() ) {
- $msg .= "\nThis module requires write rights";
- }
- if ( $this->mustBePosted() ) {
- $msg .= "\nThis module only accepts POST requests";
- }
- if ( $this->isReadMode() || $this->isWriteMode() ||
- $this->mustBePosted()
- ) {
- $msg .= "\n";
- }
-
- // Parameters
- $paramsMsg = $this->makeHelpMsgParameters();
- if ( $paramsMsg !== false ) {
- $msg .= "Parameters:\n$paramsMsg";
- }
-
- $examples = $this->getExamples();
- if ( $examples ) {
- if ( !is_array( $examples ) ) {
- $examples = [
- $examples
- ];
- }
- $msg .= 'Example' . ( count( $examples ) > 1 ? 's' : '' ) . ":\n";
- foreach ( $examples as $k => $v ) {
- if ( is_numeric( $k ) ) {
- $msg .= " $v\n";
- } else {
- if ( is_array( $v ) ) {
- $msgExample = implode( "\n", array_map( [ $this, 'indentExampleText' ], $v ) );
- } else {
- $msgExample = " $v";
- }
- $msgExample .= ':';
- $msg .= wordwrap( $msgExample, 100, "\n" ) . "\n $k\n";
- }
- }
- }
- }
-
- return $msg;
- }
-
- /**
- * @deprecated since 1.25
- * @param string $item
- * @return string
- */
- private function indentExampleText( $item ) {
- return ' ' . $item;
- }
-
- /**
- * @deprecated since 1.25
- * @param string $prefix Text to split output items
- * @param string $title What is being output
- * @param string|array $input
- * @return string
- */
- protected function makeHelpArrayToString( $prefix, $title, $input ) {
- wfDeprecated( __METHOD__, '1.25' );
- if ( $input === false ) {
- return '';
- }
- if ( !is_array( $input ) ) {
- $input = [ $input ];
- }
-
- if ( count( $input ) > 0 ) {
- if ( $title ) {
- $msg = $title . ( count( $input ) > 1 ? 's' : '' ) . ":\n ";
- } else {
- $msg = ' ';
- }
- $msg .= implode( $prefix, $input ) . "\n";
-
- return $msg;
- }
-
- return '';
- }
-
- /**
- * Generates the parameter descriptions for this module, to be displayed in the
- * module's help.
- * @deprecated since 1.25
- * @return string|bool
- */
- public function makeHelpMsgParameters() {
- wfDeprecated( __METHOD__, '1.25' );
- $params = $this->getFinalParams( ApiBase::GET_VALUES_FOR_HELP );
- if ( $params ) {
- $paramsDescription = $this->getFinalParamDescription();
- $msg = '';
- $paramPrefix = "\n" . str_repeat( ' ', 24 );
- $descWordwrap = "\n" . str_repeat( ' ', 28 );
- foreach ( $params as $paramName => $paramSettings ) {
- $desc = isset( $paramsDescription[$paramName] ) ? $paramsDescription[$paramName] : '';
- if ( is_array( $desc ) ) {
- $desc = implode( $paramPrefix, $desc );
- }
-
- // handle shorthand
- if ( !is_array( $paramSettings ) ) {
- $paramSettings = [
- self::PARAM_DFLT => $paramSettings,
- ];
- }
-
- // handle missing type
- if ( !isset( $paramSettings[ApiBase::PARAM_TYPE] ) ) {
- $dflt = isset( $paramSettings[ApiBase::PARAM_DFLT] )
- ? $paramSettings[ApiBase::PARAM_DFLT]
- : null;
- if ( is_bool( $dflt ) ) {
- $paramSettings[ApiBase::PARAM_TYPE] = 'boolean';
- } elseif ( is_string( $dflt ) || is_null( $dflt ) ) {
- $paramSettings[ApiBase::PARAM_TYPE] = 'string';
- } elseif ( is_int( $dflt ) ) {
- $paramSettings[ApiBase::PARAM_TYPE] = 'integer';
- }
- }
-
- if ( isset( $paramSettings[self::PARAM_DEPRECATED] )
- && $paramSettings[self::PARAM_DEPRECATED]
- ) {
- $desc = "DEPRECATED! $desc";
- }
-
- if ( isset( $paramSettings[self::PARAM_REQUIRED] )
- && $paramSettings[self::PARAM_REQUIRED]
- ) {
- $desc .= $paramPrefix . 'This parameter is required';
- }
-
- $type = isset( $paramSettings[self::PARAM_TYPE] )
- ? $paramSettings[self::PARAM_TYPE]
- : null;
- if ( isset( $type ) ) {
- $hintPipeSeparated = true;
- $multi = isset( $paramSettings[self::PARAM_ISMULTI] )
- ? $paramSettings[self::PARAM_ISMULTI]
- : false;
- if ( $multi ) {
- $prompt = 'Values (separate with \'|\'): ';
- } else {
- $prompt = 'One value: ';
- }
-
- if ( $type === 'submodule' ) {
- if ( isset( $paramSettings[self::PARAM_SUBMODULE_MAP] ) ) {
- $type = array_keys( $paramSettings[self::PARAM_SUBMODULE_MAP] );
- } else {
- $type = $this->getModuleManager()->getNames( $paramName );
- }
- sort( $type );
- }
- if ( is_array( $type ) ) {
- $choices = [];
- $nothingPrompt = '';
- foreach ( $type as $t ) {
- if ( $t === '' ) {
- $nothingPrompt = 'Can be empty, or ';
- } else {
- $choices[] = $t;
- }
- }
- $desc .= $paramPrefix . $nothingPrompt . $prompt;
- $choicesstring = implode( ', ', $choices );
- $desc .= wordwrap( $choicesstring, 100, $descWordwrap );
- $hintPipeSeparated = false;
- } else {
- switch ( $type ) {
- case 'namespace':
- // Special handling because namespaces are
- // type-limited, yet they are not given
- $desc .= $paramPrefix . $prompt;
- $desc .= wordwrap( implode( ', ', MWNamespace::getValidNamespaces() ),
- 100, $descWordwrap );
- $hintPipeSeparated = false;
- break;
- case 'limit':
- $desc .= $paramPrefix . "No more than {$paramSettings[self::PARAM_MAX]}";
- if ( isset( $paramSettings[self::PARAM_MAX2] ) ) {
- $desc .= " ({$paramSettings[self::PARAM_MAX2]} for bots)";
- }
- $desc .= ' allowed';
- break;
- case 'integer':
- $s = $multi ? 's' : '';
- $hasMin = isset( $paramSettings[self::PARAM_MIN] );
- $hasMax = isset( $paramSettings[self::PARAM_MAX] );
- if ( $hasMin || $hasMax ) {
- if ( !$hasMax ) {
- $intRangeStr = "The value$s must be no less than " .
- "{$paramSettings[self::PARAM_MIN]}";
- } elseif ( !$hasMin ) {
- $intRangeStr = "The value$s must be no more than " .
- "{$paramSettings[self::PARAM_MAX]}";
- } else {
- $intRangeStr = "The value$s must be between " .
- "{$paramSettings[self::PARAM_MIN]} and {$paramSettings[self::PARAM_MAX]}";
- }
-
- $desc .= $paramPrefix . $intRangeStr;
- }
- break;
- case 'upload':
- $desc .= $paramPrefix . 'Must be posted as a file upload using multipart/form-data';
- break;
- }
- }
-
- if ( $multi ) {
- if ( $hintPipeSeparated ) {
- $desc .= $paramPrefix . "Separate values with '|'";
- }
-
- $isArray = is_array( $type );
- if ( !$isArray
- || $isArray && count( $type ) > self::LIMIT_SML1
- ) {
- $desc .= $paramPrefix . 'Maximum number of values ' .
- self::LIMIT_SML1 . ' (' . self::LIMIT_SML2 . ' for bots)';
- }
- }
- }
-
- $default = isset( $paramSettings[self::PARAM_DFLT] ) ? $paramSettings[self::PARAM_DFLT] : null;
- if ( !is_null( $default ) && $default !== false ) {
- $desc .= $paramPrefix . "Default: $default";
- }
-
- $msg .= sprintf( " %-19s - %s\n", $this->encodeParamName( $paramName ), $desc );
- }
-
- return $msg;
- }
-
- return false;
- }
-
/**
* @deprecated since 1.25, always returns empty string
* @param IDatabase|bool $db
return 0;
}
- /**
- * Get the result data array (read-only)
- * @deprecated since 1.25, use $this->getResult() methods instead
- * @return array
- */
- public function getResultData() {
- wfDeprecated( __METHOD__, '1.25' );
- return $this->getResult()->getData();
- }
-
/**
* Call wfTransactionalTimeLimit() if this request was POSTed
* @since 1.26