<?php
-
/*
* Created on Sep 4, 2006
*
}
/**
- * This is the main API class, used for both external and internal processing.
+ * This is the main API class, used for both external and internal processing.
+ * When executed, it will create the requested formatter object,
+ * instantiate and execute an object associated with the needed action,
+ * and use formatter to print results.
+ * In case of an exception, an error message will be printed using the same formatter.
+ *
+ * To use API from another application, run it using FauxRequest object, in which
+ * case any internal exceptions will not be handled but passed up to the caller.
+ * After successful execution, use getResult() for the resulting data.
+ *
+ * @addtogroup API
*/
class ApiMain extends ApiBase {
* List of available modules: action name => module class
*/
private static $Modules = array (
- 'help' => 'ApiHelp',
- 'login' => 'ApiLogin',
+// 'login' => 'ApiLogin', // LOGIN is temporarily disabled until it becomes more secure
+ 'query' => 'ApiQuery',
'opensearch' => 'ApiOpenSearch',
'feedwatchlist' => 'ApiFeedWatchlist',
- 'query' => 'ApiQuery'
+ 'help' => 'ApiHelp',
);
/**
$this->mSquidMaxage = 0;
}
- public function & getRequest() {
+ /**
+ * Return the request object that contains client's request
+ */
+ public function getRequest() {
return $this->mRequest;
}
- public function & getResult() {
+ /**
+ * Get the ApiResult object asscosiated with current request
+ */
+ public function getResult() {
return $this->mResult;
}
+ /**
+ * This method will simply cause an error if the write mode was disabled for this api.
+ */
public function requestWriteMode() {
if (!$this->mEnableWrite)
$this->dieUsage('Editing of this site is disabled. Make sure the $wgEnableWriteAPI=true; ' .
'statement is included in the site\'s LocalSettings.php file', 'readonly');
}
+ /**
+ * Set how long the response should be cached.
+ */
public function setCacheMaxAge($maxage) {
$this->mSquidMaxage = $maxage;
}
+ /**
+ * Create an instance of an output formatter by its name
+ */
public function createPrinterByName($format) {
return new $this->mFormats[$format] ($this, $format);
}
+ /**
+ * Execute api request. Any errors will be handled if the API was called by the remote client.
+ */
public function execute() {
$this->profileIn();
if ($this->mInternalMode)
$this->profileOut();
}
+ /**
+ * Execute an action, and in case of an error, erase whatever partial results
+ * have been accumulated, and replace it with an error message and a help screen.
+ */
protected function executeActionWithErrorHandling() {
// In case an error occurs during data output,
- // this clear the output buffer and print just the error information
+ // clear the output buffer and print just the error information
ob_start();
try {
header('Expires: ' . wfTimestamp(TS_RFC2822, $expires));
header('Cache-Control: s-maxage=' . $this->mSquidMaxage . ', must-revalidate, max-age=0');
+ if($this->mPrinter->getIsHtml())
+ echo wfReportTime();
+
ob_end_flush();
}
}
/**
- * Internal printer
+ * Print results using the current printer
*/
protected function printResult($isError) {
$printer = $this->mPrinter;
$printer->profileOut();
}
+ /**
+ * See ApiBase for description.
+ */
protected function getAllowedParams() {
return array (
'format' => array (
);
}
+ /**
+ * See ApiBase for description.
+ */
protected function getParamDescription() {
return array (
'format' => 'The format of the output',
);
}
+ /**
+ * See ApiBase for description.
+ */
protected function getDescription() {
return array (
'',
'This API allows programs to access various functions of MediaWiki software.',
- 'For more details see API Home Page @ http://meta.wikimedia.org/wiki/API',
+ 'For more details see API Home Page @ http://www.mediawiki.org/wiki/API',
'',
'Status: ALPHA -- all features shown on this page should be working,',
' but the API is still in active development, and may change at any time.',
);
}
+ /**
+ * Returns an array of strings with credits for the API
+ */
protected function getCredits() {
return array(
- 'This API is being implemented by Yuri Astrakhan [[User:Yurik]] / FirstnameLastname@gmail.com',
- 'Please leave your comments and suggestions at http://meta.wikimedia.org/wiki/API'
+ 'This API is being implemented by Yuri Astrakhan [[User:Yurik]] / <FirstnameLastname>@gmail.com',
+ 'Please leave your comments and suggestions at http://www.mediawiki.org/wiki/API'
);
}
}
private $mIsBot = null;
+
+ /**
+ * Returns true if the currently logged in user is a bot, false otherwise
+ */
public function isBot() {
if (!isset ($this->mIsBot)) {
global $wgUser;
return $this->mShowVersions;
}
+ /**
+ * Returns the version information of this file, plus it includes
+ * the versions for all files that are not callable proper API modules
+ */
public function getVersion() {
$vers = array ();
$vers[] = __CLASS__ . ': $Id$';
}
/**
-* @desc This exception will be thrown when dieUsage is called to stop module execution.
-*/
+ * This exception will be thrown when dieUsage is called to stop module execution.
+ * The exception handling code will print a help screen explaining how this API may be used.
+ *
+ * @addtogroup API
+ */
class UsageException extends Exception {
private $mCodestr;