Update formatting on API classes

Change-Id: Ifd18a8de1d2580b723a5b91e8d202818fd97795a
This commit is contained in:
Siebrand Mazeland 2013-11-14 13:40:22 +01:00 committed by Chad
parent 995e6679ee
commit fe05f85a62
10 changed files with 74 additions and 35 deletions

View file

@ -30,10 +30,10 @@
* The class functions are divided into several areas of functionality:
*
* Module parameters: Derived classes can define getAllowedParams() to specify
* which parameters to expect, how to parse and validate them.
* which parameters to expect, how to parse and validate them.
*
* Profiling: various methods to allow keeping tabs on various tasks and their
* time costs
* time costs
*
* Self-documentation: code to allow the API to document its own state
*
@ -124,6 +124,7 @@ abstract class ApiBase extends ContextSource {
*/
public function getVersion() {
wfDeprecated( __METHOD__, '1.21' );
return '';
}
@ -194,6 +195,7 @@ abstract class ApiBase extends ContextSource {
if ( $this->isMain() ) {
ApiBase::dieDebug( __METHOD__, 'base method was called on main module. ' );
}
return $this->getMain()->getResult();
}
@ -216,6 +218,7 @@ abstract class ApiBase extends ContextSource {
*/
public function createContext() {
wfDeprecated( __METHOD__, '1.19' );
return new DerivativeContext( $this->getContext() );
}
@ -293,7 +296,8 @@ abstract class ApiBase extends ContextSource {
$msg .= "\nThis module only accepts POST requests";
}
if ( $this->isReadMode() || $this->isWriteMode() ||
$this->mustBePosted() ) {
$this->mustBePosted()
) {
$msg .= "\n";
}
@ -359,8 +363,10 @@ abstract class ApiBase extends ContextSource {
$msg = ' ';
}
$msg .= implode( $prefix, $input ) . "\n";
return $msg;
}
return '';
}
@ -479,9 +485,10 @@ abstract class ApiBase extends ContextSource {
$isArray = is_array( $type );
if ( !$isArray
|| $isArray && count( $type ) > self::LIMIT_SML1 ) {
|| $isArray && count( $type ) > self::LIMIT_SML1
) {
$desc .= $paramPrefix . "Maximum number of values " .
self::LIMIT_SML1 . " (" . self::LIMIT_SML2 . " for bots)";
self::LIMIT_SML1 . " (" . self::LIMIT_SML2 . " for bots)";
}
}
}
@ -493,8 +500,8 @@ abstract class ApiBase extends ContextSource {
$msg .= sprintf( " %-19s - %s\n", $this->encodeParamName( $paramName ), $desc );
}
return $msg;
return $msg;
} else {
return false;
}
@ -555,6 +562,7 @@ abstract class ApiBase extends ContextSource {
public function getFinalParams( $flags = 0 ) {
$params = $this->getAllowedParams( $flags );
wfRunHooks( 'APIGetAllowedParams', array( &$this, &$params, $flags ) );
return $params;
}
@ -567,6 +575,7 @@ abstract class ApiBase extends ContextSource {
public function getFinalParamDescription() {
$desc = $this->getParamDescription();
wfRunHooks( 'APIGetParamDescription', array( &$this, &$desc ) );
return $desc;
}
@ -599,6 +608,7 @@ abstract class ApiBase extends ContextSource {
public function getFinalResultProperties() {
$properties = $this->getResultProperties();
wfRunHooks( 'APIGetResultProperties', array( $this, &$properties ) );
return $properties;
}
@ -624,6 +634,7 @@ abstract class ApiBase extends ContextSource {
public function getFinalDescription() {
$desc = $this->getDescription();
wfRunHooks( 'APIGetDescription', array( &$this, &$desc ) );
return $desc;
}
@ -660,6 +671,7 @@ abstract class ApiBase extends ContextSource {
}
$this->mParamCache[$parseLimit] = $results;
}
return $this->mParamCache[$parseLimit];
}
@ -672,6 +684,7 @@ abstract class ApiBase extends ContextSource {
protected function getParameter( $paramName, $parseLimit = true ) {
$params = $this->getFinalParams();
$paramSettings = $params[$paramName];
return $this->getParameterFromSettings( $paramName, $paramSettings, $parseLimit );
}
@ -810,6 +823,7 @@ abstract class ApiBase extends ContextSource {
*/
public static function getValidNamespaces() {
wfDeprecated( __METHOD__, '1.17' );
return MWNamespace::getValidNamespaces();
}
@ -818,7 +832,7 @@ abstract class ApiBase extends ContextSource {
* @param string $watchlist Valid values: 'watch', 'unwatch', 'preferences', 'nochange'
* @param $titleObj Title 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.
* If not set will use watchdefault always and watchcreations if $titleObj doesn't exist.
* @return bool
*/
protected function getWatchlistValue( $watchlist, $titleObj, $userOption = null ) {
@ -842,6 +856,7 @@ abstract class ApiBase extends ContextSource {
return $this->getUser()->getBoolOption( 'watchdefault' ) ||
$this->getUser()->getBoolOption( 'watchcreations' ) && !$titleObj->exists();
}
# Watch the article based on the user preference
return $this->getUser()->getBoolOption( $userOption );
@ -964,7 +979,7 @@ abstract class ApiBase extends ContextSource {
$min = isset( $paramSettings[self::PARAM_MIN] ) ? $paramSettings[self::PARAM_MIN] : null;
$max = isset( $paramSettings[self::PARAM_MAX] ) ? $paramSettings[self::PARAM_MAX] : null;
$enforceLimits = isset( $paramSettings[self::PARAM_RANGE_ENFORCE] )
? $paramSettings[self::PARAM_RANGE_ENFORCE] : false;
? $paramSettings[self::PARAM_RANGE_ENFORCE] : false;
if ( is_array( $value ) ) {
$value = array_map( 'intval', $value );
@ -1067,7 +1082,7 @@ abstract class ApiBase extends ContextSource {
// This is a bit awkward, but we want to avoid calling canApiHighLimits() because it unstubs $wgUser
$valuesList = explode( '|', $value, self::LIMIT_SML2 + 1 );
$sizeLimit = count( $valuesList ) > self::LIMIT_SML1 && $this->mMainModule->canApiHighLimits() ?
self::LIMIT_SML2 : self::LIMIT_SML1;
self::LIMIT_SML2 : self::LIMIT_SML1;
if ( self::truncateArray( $valuesList, $sizeLimit ) ) {
$this->setWarning( "Too many values supplied for parameter '$valueName': the limit is $sizeLimit" );
@ -1153,6 +1168,7 @@ abstract class ApiBase extends ContextSource {
if ( $unixTimestamp === false ) {
$this->dieUsage( "Invalid value '$value' for timestamp parameter $encParamName", "badtimestamp_{$encParamName}" );
}
return wfTimestamp( TS_MW, $unixTimestamp );
}
@ -1167,6 +1183,7 @@ abstract class ApiBase extends ContextSource {
if ( $title === null ) {
$this->dieUsage( "Invalid value '$value' for user parameter $encParamName", "baduser_{$encParamName}" );
}
return $title->getText();
}
@ -1196,6 +1213,7 @@ abstract class ApiBase extends ContextSource {
array_pop( $arr );
$modified = true;
}
return $modified;
}
@ -1521,6 +1539,7 @@ abstract class ApiBase extends ContextSource {
public function isReadMode() {
return true;
}
/**
* Indicates whether this module requires write mode
* @return bool
@ -1584,6 +1603,7 @@ abstract class ApiBase extends ContextSource {
}
$user = $this->getUser();
}
return $user;
}
@ -1656,6 +1676,7 @@ abstract class ApiBase extends ContextSource {
public function getFinalPossibleErrors() {
$possibleErrors = $this->getPossibleErrors();
wfRunHooks( 'APIGetPossibleErrors', array( $this, &$possibleErrors ) );
return $possibleErrors;
}
@ -1674,6 +1695,7 @@ abstract class ApiBase extends ContextSource {
$ret[] = $this->parseMsg( $row );
}
}
return $ret;
}
@ -1730,6 +1752,7 @@ abstract class ApiBase extends ContextSource {
if ( $this->mTimeIn !== 0 ) {
ApiBase::dieDebug( __METHOD__, 'called without calling profileOut() first' );
}
return $this->mModuleTime;
}
@ -1779,6 +1802,7 @@ abstract class ApiBase extends ContextSource {
if ( $this->mDBTimeIn !== 0 ) {
ApiBase::dieDebug( __METHOD__, 'called without calling profileDBOut() first' );
}
return $this->mDBTime;
}
@ -1792,6 +1816,7 @@ abstract class ApiBase extends ContextSource {
$this->mSlaveDB = wfGetDB( DB_SLAVE, 'api' );
$this->profileDBOut();
}
return $this->mSlaveDB;
}

View file

@ -88,12 +88,14 @@ class ApiComparePages extends ApiBase {
if ( !$title || $title->isExternal() ) {
$this->dieUsageMsg( array( 'invalidtitle', $titleText ) );
}
return $title->getLatestRevID();
} elseif ( $titleId ) {
$title = Title::newFromID( $titleId );
if ( !$title ) {
$this->dieUsageMsg( array( 'nosuchpageid', $titleId ) );
}
return $title->getLatestRevID();
}
$this->dieUsage( 'inputneeded', 'A title, a page ID, or a revision number is needed for both the from and the to parameters' );

View file

@ -172,6 +172,7 @@ class ApiCreateAccount extends ApiBase {
public function getAllowedParams() {
global $wgEmailConfirmToEdit;
return array(
'name' => array(
ApiBase::PARAM_TYPE => 'user',
@ -196,6 +197,7 @@ class ApiCreateAccount extends ApiBase {
public function getParamDescription() {
$p = $this->getModulePrefix();
return array(
'name' => 'Username',
'password' => "Password (ignored if {$p}mailpassword is set)",
@ -280,6 +282,7 @@ class ApiCreateAccount extends ApiBase {
'code' => 'passwordtooshort',
'info' => wfMessage( 'passwordtooshort', $wgMinimalPasswordLength )->inLanguage( 'en' )->useDatabase( false )->parse()
);
return $errors;
}

View file

@ -121,6 +121,7 @@ class ApiDelete extends ApiBase {
}
$error = '';
// Luckily, Article.php provides a reusable delete function that does the hard work for us
return $page->doDeleteArticleReal( $reason, false, 0, true, $error );
}
@ -159,6 +160,7 @@ class ApiDelete extends ApiBase {
if ( is_null( $reason ) ) { // Log and RC don't like null reasons
$reason = '';
}
return FileDeleteForm::doDelete( $title, $file, $oldimage, $reason, $suppress, $user );
}
@ -204,6 +206,7 @@ class ApiDelete extends ApiBase {
public function getParamDescription() {
$p = $this->getModulePrefix();
return array(
'title' => "Title of the page you want to delete. Cannot be used together with {$p}pageid",
'pageid' => "Page ID of the page you want to delete. Cannot be used together with {$p}title",

View file

@ -38,9 +38,9 @@ class ApiEditPage extends ApiBase {
$params = $this->extractRequestParams();
if ( is_null( $params['text'] ) && is_null( $params['appendtext'] ) &&
is_null( $params['prependtext'] ) &&
$params['undo'] == 0 )
{
is_null( $params['prependtext'] ) &&
$params['undo'] == 0
) {
$this->dieUsageMsg( 'missingtext' );
}
@ -53,8 +53,8 @@ class ApiEditPage extends ApiBase {
$oldTitle = $titleObj;
$titles = Revision::newFromTitle( $oldTitle, false, Revision::READ_LATEST )
->getContent( Revision::FOR_THIS_USER, $user )
->getRedirectChain();
->getContent( Revision::FOR_THIS_USER, $user )
->getRedirectChain();
// array_shift( $titles );
$redirValues = array();
@ -101,7 +101,7 @@ class ApiEditPage extends ApiBase {
$model = $contentHandler->getModelID();
$this->dieUsage( "The requested format $contentFormat is not supported for content model " .
" $model used by $name", 'badformat' );
" $model used by $name", 'badformat' );
}
if ( $params['createonly'] && $titleObj->exists() ) {
@ -121,8 +121,7 @@ class ApiEditPage extends ApiBase {
}
$toMD5 = $params['text'];
if ( !is_null( $params['appendtext'] ) || !is_null( $params['prependtext'] ) )
{
if ( !is_null( $params['appendtext'] ) || !is_null( $params['prependtext'] ) ) {
$content = $pageObj->getContent();
if ( !$content ) {
@ -138,6 +137,7 @@ class ApiEditPage extends ApiBase {
$content = ContentHandler::makeContent( $text, $this->getTitle() );
} catch ( MWContentSerializationException $ex ) {
$this->dieUsage( $ex->getMessage(), 'parseerror' );
return;
}
} else {
@ -187,7 +187,7 @@ class ApiEditPage extends ApiBase {
if ( $params['undoafter'] > 0 ) {
if ( $params['undo'] < $params['undoafter'] ) {
list( $params['undo'], $params['undoafter'] ) =
array( $params['undoafter'], $params['undo'] );
array( $params['undoafter'], $params['undo'] );
}
$undoafterRev = Revision::newFromID( $params['undoafter'] );
}
@ -363,6 +363,7 @@ class ApiEditPage extends ApiBase {
if ( count( $r ) ) {
$r['result'] = 'Failure';
$apiResult->addValue( null, $this->getModuleName(), $r );
return;
} else {
$this->dieUsageMsg( 'hookaborted' );
@ -513,11 +514,11 @@ class ApiEditPage extends ApiBase {
array( 'code' => 'invalidsection', 'info' => 'The section parameter must be set to an integer or \'new\'' ),
array( 'code' => 'sectionsnotsupported', 'info' => 'Sections are not supported for this type of page.' ),
array( 'code' => 'editnotsupported', 'info' => 'Editing of this type of page is not supported using '
. 'the text based edit API.' ),
. 'the text based edit API.' ),
array( 'code' => 'appendnotsupported', 'info' => 'This type of page can not be edited by appending '
. 'or prepending text.' ),
. 'or prepending text.' ),
array( 'code' => 'badformat', 'info' => 'The requested serialization format can not be applied to '
. 'the page\'s content model' ),
. 'the page\'s content model' ),
array( 'customcssprotected' ),
array( 'customjsprotected' ),
)
@ -591,6 +592,7 @@ class ApiEditPage extends ApiBase {
public function getParamDescription() {
$p = $this->getModulePrefix();
return array(
'title' => "Title of the page you want to edit. Cannot be used together with {$p}pageid",
'pageid' => "Page ID of the page you want to edit. Cannot be used together with {$p}title",
@ -598,17 +600,17 @@ class ApiEditPage extends ApiBase {
'sectiontitle' => 'The title for a new section',
'text' => 'Page content',
'token' => array( 'Edit token. You can get one of these through prop=info.',
"The token should always be sent as the last parameter, or at least, after the {$p}text parameter"
"The token should always be sent as the last parameter, or at least, after the {$p}text parameter"
),
'summary' => "Edit summary. Also section title when {$p}section=new and {$p}sectiontitle is not set",
'minor' => 'Minor edit',
'notminor' => 'Non-minor edit',
'bot' => 'Mark this edit as bot',
'basetimestamp' => array( 'Timestamp of the base revision (obtained through prop=revisions&rvprop=timestamp).',
'Used to detect edit conflicts; leave unset to ignore conflicts'
'Used to detect edit conflicts; leave unset to ignore conflicts'
),
'starttimestamp' => array( 'Timestamp when you obtained the edit token.',
'Used to detect edit conflicts; leave unset to ignore conflicts'
'Used to detect edit conflicts; leave unset to ignore conflicts'
),
'recreate' => 'Override any errors about the article having been deleted in the meantime',
'createonly' => 'Don\'t edit the page if it exists already',
@ -617,10 +619,10 @@ class ApiEditPage extends ApiBase {
'unwatch' => 'Remove the page from your watchlist',
'watchlist' => 'Unconditionally add or remove the page from your watchlist, use preferences or do not change watch',
'md5' => array( "The MD5 hash of the {$p}text parameter, or the {$p}prependtext and {$p}appendtext parameters concatenated.",
'If set, the edit won\'t be done unless the hash is correct' ),
'If set, the edit won\'t be done unless the hash is correct' ),
'prependtext' => "Add this text to the beginning of the page. Overrides {$p}text",
'appendtext' => array( "Add this text to the end of the page. Overrides {$p}text.",
"Use {$p}section=new to append a new section" ),
"Use {$p}section=new to append a new section" ),
'undo' => "Undo this revision. Overrides {$p}text, {$p}prependtext and {$p}appendtext",
'undoafter' => 'Undo all revisions from undo to this one. If not set, just undo one revision',
'redirect' => 'Automatically resolve redirects',

View file

@ -61,8 +61,8 @@ class ApiFeedContributions extends ApiBase {
$feedUrl = SpecialPage::getTitleFor( 'Contributions', $params['user'] )->getFullURL();
$target = $params['user'] == 'newbies'
? 'newbies'
: Title::makeTitleSafe( NS_USER, $params['user'] )->getText();
? 'newbies'
: Title::makeTitleSafe( NS_USER, $params['user'] )->getText();
$feed = new $wgFeedClasses[$params['feedformat']] (
$feedTitle,
@ -107,6 +107,7 @@ class ApiFeedContributions extends ApiBase {
$comments
);
}
return null;
}
@ -142,12 +143,14 @@ class ApiFeedContributions extends ApiBase {
htmlspecialchars( FeedItem::stripComment( $revision->getComment() ) ) .
"</p>\n<hr />\n<div>" . $html . "</div>";
}
return '';
}
public function getAllowedParams() {
global $wgFeedClasses;
$feedFormatNames = array_keys( $wgFeedClasses );
return array(
'feedformat' => array(
ApiBase::PARAM_DFLT => 'rss',

View file

@ -135,7 +135,6 @@ class ApiFeedWatchlist extends ApiBase {
$feed = new $wgFeedClasses[$params['feedformat']] ( $feedTitle, htmlspecialchars( $msg ), $feedUrl );
ApiFormatFeedWrapper::setResult( $this->getResult(), $feed, $feedItems );
} catch ( Exception $e ) {
// Error results should not be cached
@ -199,6 +198,7 @@ class ApiFeedWatchlist extends ApiBase {
$this->watchlistModule = $this->getMain()->getModuleManager()->getModule( 'query' )
->getModuleManager()->getModule( 'watchlist' );
}
return $this->watchlistModule;
}
@ -235,11 +235,13 @@ class ApiFeedWatchlist extends ApiBase {
$ret['wltype'] = null;
$ret['wlexcludeuser'] = null;
}
return $ret;
}
public function getParamDescription() {
$wldescr = $this->getWatchlistModule()->getParamDescription();
return array(
'feedformat' => 'The format of the feed',
'hours' => 'List pages modified within this many hours from now',

View file

@ -58,7 +58,6 @@ class ApiFileRevert extends ApiBase {
}
$this->getResult()->addValue( null, $this->getModuleName(), $result );
}
/**
@ -130,7 +129,6 @@ class ApiFileRevert extends ApiBase {
ApiBase::PARAM_REQUIRED => true
),
);
}
public function getParamDescription() {

View file

@ -43,9 +43,9 @@ abstract class ApiFormatBase extends ApiBase {
public function __construct( $main, $format ) {
parent::__construct( $main, $format );
$this->mIsHtml = ( substr( $format, - 2, 2 ) === 'fm' ); // ends with 'fm'
$this->mIsHtml = ( substr( $format, -2, 2 ) === 'fm' ); // ends with 'fm'
if ( $this->mIsHtml ) {
$this->mFormat = substr( $format, 0, - 2 ); // remove ending 'fm'
$this->mFormat = substr( $format, 0, -2 ); // remove ending 'fm'
} else {
$this->mFormat = $format;
}
@ -360,8 +360,8 @@ class ApiFormatFeedWrapper extends ApiFormatBase {
/**
* This class expects the result data to be in a custom format set by self::setResult()
* $result['_feed'] - an instance of one of the $wgFeedClasses classes
* $result['_feeditems'] - an array of FeedItem instances
* $result['_feed'] - an instance of one of the $wgFeedClasses classes
* $result['_feeditems'] - an array of FeedItem instances
*/
public function execute() {
$data = $this->getResultData();

View file

@ -43,6 +43,7 @@ class ApiFormatJson extends ApiFormatBase {
if ( $params['callback'] ) {
return 'text/javascript';
}
return 'application/json';
}