| Index: trunk/phase3/includes/api/ApiChangeRights.php |
| — | — | @@ -27,7 +27,10 @@ |
| 28 | 28 | require_once ("ApiBase.php"); |
| 29 | 29 | } |
| 30 | 30 | |
| 31 | | -/** |
| | 31 | +/** |
| | 32 | + * API module that facilitates the changing of user rights. The API eqivalent of |
| | 33 | + * Special:Userrights. Requires API write mode to be enabled. |
| | 34 | + * |
| 32 | 35 | * @addtogroup API |
| 33 | 36 | */ |
| 34 | 37 | class ApiChangeRights extends ApiBase { |
| Index: trunk/phase3/includes/api/ApiLogout.php |
| — | — | @@ -28,6 +28,12 @@ |
| 29 | 29 | require_once ('ApiBase.php'); |
| 30 | 30 | } |
| 31 | 31 | |
| | 32 | +/** |
| | 33 | + * API module to allow users to log out of the wiki. API equivalent of |
| | 34 | + * Special:Userlogout. |
| | 35 | + * |
| | 36 | + * @addtogroup API |
| | 37 | + */ |
| 32 | 38 | class ApiLogout extends ApiBase { |
| 33 | 39 | |
| 34 | 40 | public function __construct($main, $action) { |
| — | — | @@ -62,4 +68,4 @@ |
| 63 | 69 | public function getVersion() { |
| 64 | 70 | return __CLASS__ . ': $Id$'; |
| 65 | 71 | } |
| 66 | | -} |
| \ No newline at end of file |
| | 72 | +} |
| Index: trunk/phase3/includes/api/ApiBlock.php |
| — | — | @@ -28,14 +28,26 @@ |
| 29 | 29 | } |
| 30 | 30 | |
| 31 | 31 | /** |
| | 32 | +* API module that facilitates the blocking of users. Requires API write mode |
| | 33 | +* to be enabled. |
| | 34 | +* |
| 32 | 35 | * @addtogroup API |
| 33 | 36 | */ |
| 34 | 37 | class ApiBlock extends ApiBase { |
| 35 | 38 | |
| | 39 | + /** |
| | 40 | + * Std ctor. |
| | 41 | + */ |
| 36 | 42 | public function __construct($main, $action) { |
| 37 | 43 | parent :: __construct($main, $action); |
| 38 | 44 | } |
| 39 | 45 | |
| | 46 | + /** |
| | 47 | + * Blocks the user specified in the parameters for the given expiry, with the |
| | 48 | + * given reason, and with all other settings provided in the params. If the block |
| | 49 | + * succeeds, produces a result containing the details of the block and notice |
| | 50 | + * of success. If it fails, the result will specify the nature of the error. |
| | 51 | + */ |
| 40 | 52 | public function execute() { |
| 41 | 53 | global $wgUser; |
| 42 | 54 | $this->getMain()->requestWriteMode(); |
| — | — | @@ -141,7 +153,7 @@ |
| 142 | 154 | 'nocreate' => 'Prevent account creation', |
| 143 | 155 | 'autoblock' => 'Automatically block the last used IP address, and any subsequent IP addresses they try to login from', |
| 144 | 156 | 'noemail' => 'Prevent user from sending e-mail through the wiki', |
| 145 | | - 'hidename' => 'Hide the username from the block log.' |
| | 157 | + 'hidename' => 'Hide the username from the block log. (Requires the "hideuser" right.)' |
| 146 | 158 | ); |
| 147 | 159 | } |
| 148 | 160 | |
| Index: trunk/phase3/includes/api/ApiExpandTemplates.php |
| — | — | @@ -29,6 +29,10 @@ |
| 30 | 30 | } |
| 31 | 31 | |
| 32 | 32 | /** |
| | 33 | + * API module that functions as a shortcut to the wikitext preprocessor. Expands |
| | 34 | + * any templates in a provided string, and returns the result of this expansion |
| | 35 | + * to the caller. |
| | 36 | + * |
| 33 | 37 | * @addtogroup API |
| 34 | 38 | */ |
| 35 | 39 | class ApiExpandTemplates extends ApiBase { |
| Index: trunk/phase3/includes/api/ApiDelete.php |
| — | — | @@ -29,6 +29,9 @@ |
| 30 | 30 | |
| 31 | 31 | |
| 32 | 32 | /** |
| | 33 | + * API module that facilitates deleting pages. The API eqivalent of action=delete. |
| | 34 | + * Requires API write mode to be enabled. |
| | 35 | + * |
| 33 | 36 | * @addtogroup API |
| 34 | 37 | */ |
| 35 | 38 | class ApiDelete extends ApiBase { |
| — | — | @@ -37,51 +40,21 @@ |
| 38 | 41 | parent :: __construct($main, $action); |
| 39 | 42 | } |
| 40 | 43 | |
| | 44 | + /* Return values for the delete function. */ |
| | 45 | + const DELETE_SUCCESS = 0; |
| | 46 | + const DELETE_PERM = 1; |
| | 47 | + const DELETE_BLOCKED = 2; |
| | 48 | + const DELETE_READONLY = 3; |
| | 49 | + const DELETE_BADTOKEN = 4; |
| | 50 | + const DELETE_BADARTICLE = 5; |
| | 51 | + |
| 41 | 52 | /** |
| 42 | | - * We have our own delete() function, since Article.php's implementation is split in two phases |
| 43 | | - * @param Article $article - Article object to work on |
| 44 | | - * @param string $token - Delete token (same as edit token) |
| 45 | | - * @param string $reason - Reason for the deletion. Autogenerated if NULL |
| 46 | | - * @return DELETE_SUCCESS on success, DELETE_* on failure |
| | 53 | + * Extracts the title, token, and reason from the request parameters and invokes |
| | 54 | + * the local delete() function with these as arguments. It does not make use of |
| | 55 | + * the delete function specified by Article.php. If the deletion succeeds, the |
| | 56 | + * details of the article deleted and the reason for deletion are added to the |
| | 57 | + * result object. |
| 47 | 58 | */ |
| 48 | | - |
| 49 | | - const DELETE_SUCCESS = 0; |
| 50 | | - const DELETE_PERM = 1; |
| 51 | | - const DELETE_BLOCKED = 2; |
| 52 | | - const DELETE_READONLY = 3; |
| 53 | | - const DELETE_BADTOKEN = 4; |
| 54 | | - const DELETE_BADARTICLE = 5; |
| 55 | | - |
| 56 | | - public static function delete(&$article, $token, &$reason = NULL) |
| 57 | | - { |
| 58 | | - global $wgUser; |
| 59 | | - |
| 60 | | - // Check permissions first |
| 61 | | - if(!$article->mTitle->userCan('delete')) |
| 62 | | - return self::DELETE_PERM; |
| 63 | | - if($wgUser->isBlocked()) |
| 64 | | - return self::DELETE_BLOCKED; |
| 65 | | - if(wfReadOnly()) |
| 66 | | - return self::DELETE_READONLY; |
| 67 | | - |
| 68 | | - // Check token |
| 69 | | - if(!$wgUser->matchEditToken($token)) |
| 70 | | - return self::DELETE_BADTOKEN; |
| 71 | | - |
| 72 | | - // Auto-generate a summary, if necessary |
| 73 | | - if(is_null($reason)) |
| 74 | | - { |
| 75 | | - $reason = $article->generateReason($hasHistory); |
| 76 | | - if($reason === false) |
| 77 | | - return self::DELETE_BADARTICLE; |
| 78 | | - } |
| 79 | | - |
| 80 | | - // Luckily, Article.php provides a reusable delete function that does the hard work for us |
| 81 | | - if($article->doDeleteArticle($reason)) |
| 82 | | - return self::DELETE_SUCCESS; |
| 83 | | - return self::DELETE_BADARTICLE; |
| 84 | | - } |
| 85 | | - |
| 86 | 59 | public function execute() { |
| 87 | 60 | global $wgUser; |
| 88 | 61 | $this->getMain()->requestWriteMode(); |
| — | — | @@ -136,6 +109,44 @@ |
| 137 | 110 | $r = array('title' => $titleObj->getPrefixedText(), 'reason' => $reason); |
| 138 | 111 | $this->getResult()->addValue(null, $this->getModuleName(), $r); |
| 139 | 112 | } |
| | 113 | + |
| | 114 | + /** |
| | 115 | + * We have our own delete() function, since Article.php's implementation is split in two phases |
| | 116 | + * |
| | 117 | + * @param Article $article - Article object to work on |
| | 118 | + * @param string $token - Delete token (same as edit token) |
| | 119 | + * @param string $reason - Reason for the deletion. Autogenerated if NULL |
| | 120 | + * @return DELETE_SUCCESS on success, DELETE_* on failure |
| | 121 | + */ |
| | 122 | + public static function delete(&$article, $token, &$reason = NULL) |
| | 123 | + { |
| | 124 | + global $wgUser; |
| | 125 | + |
| | 126 | + // Check permissions first |
| | 127 | + if(!$article->mTitle->userCan('delete')) |
| | 128 | + return self::DELETE_PERM; |
| | 129 | + if($wgUser->isBlocked()) |
| | 130 | + return self::DELETE_BLOCKED; |
| | 131 | + if(wfReadOnly()) |
| | 132 | + return self::DELETE_READONLY; |
| | 133 | + |
| | 134 | + // Check token |
| | 135 | + if(!$wgUser->matchEditToken($token)) |
| | 136 | + return self::DELETE_BADTOKEN; |
| | 137 | + |
| | 138 | + // Auto-generate a summary, if necessary |
| | 139 | + if(is_null($reason)) |
| | 140 | + { |
| | 141 | + $reason = $article->generateReason($hasHistory); |
| | 142 | + if($reason === false) |
| | 143 | + return self::DELETE_BADARTICLE; |
| | 144 | + } |
| | 145 | + |
| | 146 | + // Luckily, Article.php provides a reusable delete function that does the hard work for us |
| | 147 | + if($article->doDeleteArticle($reason)) |
| | 148 | + return self::DELETE_SUCCESS; |
| | 149 | + return self::DELETE_BADARTICLE; |
| | 150 | + } |
| 140 | 151 | |
| 141 | 152 | protected function getAllowedParams() { |
| 142 | 153 | return array ( |
| Index: trunk/phase3/includes/api/ApiBase.php |
| — | — | @@ -63,12 +63,36 @@ |
| 64 | 64 | $this->mModulePrefix = $modulePrefix; |
| 65 | 65 | } |
| 66 | 66 | |
| | 67 | + /***************************************************************************** |
| | 68 | + * ABSTRACT METHODS * |
| | 69 | + *****************************************************************************/ |
| | 70 | + |
| 67 | 71 | /** |
| 68 | | - * Executes this module |
| | 72 | + * Evaluates the parameters, performs the requested query, and sets up the |
| | 73 | + * result. Concrete implementations of ApiBase must override this method to |
| | 74 | + * provide whatever functionality their module offers. Implementations must |
| | 75 | + * not produce any output on their own and are not expected to handle any |
| | 76 | + * errors. |
| | 77 | + * |
| | 78 | + * The execute method will be invoked directly by ApiMain immediately before |
| | 79 | + * the result of the module is output. Aside from the constructor, implementations |
| | 80 | + * should assume that no other methods will be called externally on the module |
| | 81 | + * before the result is processed. |
| | 82 | + * |
| | 83 | + * The result data should be stored in the result object referred to by |
| | 84 | + * "getResult()". Refer to ApiResult.php for details on populating a result |
| | 85 | + * object. |
| 69 | 86 | */ |
| 70 | 87 | public abstract function execute(); |
| 71 | 88 | |
| 72 | 89 | /** |
| | 90 | + * Returns a String that identifies the version of the extending class. Typically |
| | 91 | + * includes the class name, the svn revision, timestamp, and last author. May |
| | 92 | + * be severely incorrect in many implementations! |
| | 93 | + */ |
| | 94 | + public abstract function getVersion(); |
| | 95 | + |
| | 96 | + /** |
| 73 | 97 | * Get the name of the module being executed by this instance |
| 74 | 98 | */ |
| 75 | 99 | public function getModuleName() { |
| — | — | @@ -100,14 +124,16 @@ |
| 101 | 125 | } |
| 102 | 126 | |
| 103 | 127 | /** |
| 104 | | - * If this module's $this is the same as $this->mMainModule, its the root, otherwise no |
| | 128 | + * Returns true if this module is the main module ($this === $this->mMainModule), |
| | 129 | + * false otherwise. |
| 105 | 130 | */ |
| 106 | 131 | public function isMain() { |
| 107 | 132 | return $this === $this->mMainModule; |
| 108 | 133 | } |
| 109 | 134 | |
| 110 | 135 | /** |
| 111 | | - * Get result object |
| | 136 | + * Get the result object. Please refer to the documentation in ApiResult.php |
| | 137 | + * for details on populating and accessing data in a result object. |
| 112 | 138 | */ |
| 113 | 139 | public function getResult() { |
| 114 | 140 | // Main module has getResult() method overriden |
| — | — | @@ -125,7 +151,8 @@ |
| 126 | 152 | } |
| 127 | 153 | |
| 128 | 154 | /** |
| 129 | | - * Set warning section for this module. Users should monitor this section to notice any changes in API. |
| | 155 | + * Set warning section for this module. Users should monitor this section to |
| | 156 | + * notice any changes in API. |
| 130 | 157 | */ |
| 131 | 158 | public function setWarning($warning) { |
| 132 | 159 | $msg = array(); |
| — | — | @@ -196,6 +223,10 @@ |
| 197 | 224 | return $msg; |
| 198 | 225 | } |
| 199 | 226 | |
| | 227 | + /** |
| | 228 | + * Generates the parameter descriptions for this module, to be displayed in the |
| | 229 | + * module's help. |
| | 230 | + */ |
| 200 | 231 | public function makeHelpMsgParameters() { |
| 201 | 232 | $params = $this->getAllowedParams(); |
| 202 | 233 | if ($params !== false) { |
| — | — | @@ -208,7 +239,7 @@ |
| 209 | 240 | if (is_array($desc)) |
| 210 | 241 | $desc = implode($paramPrefix, $desc); |
| 211 | 242 | |
| 212 | | - @ $type = $paramSettings[self :: PARAM_TYPE]; |
| | 243 | + $type = $paramSettings[self :: PARAM_TYPE]; |
| 213 | 244 | if (isset ($type)) { |
| 214 | 245 | if (isset ($paramSettings[self :: PARAM_ISMULTI])) |
| 215 | 246 | $prompt = 'Values (separate with \'|\'): '; |
| — | — | @@ -325,6 +356,10 @@ |
| 326 | 357 | return $this->getParameterFromSettings($paramName, $paramSettings); |
| 327 | 358 | } |
| 328 | 359 | |
| | 360 | + /** |
| | 361 | + * Returns an array of the namespaces (by integer id) that exist on the |
| | 362 | + * wiki. Used primarily in help documentation. |
| | 363 | + */ |
| 329 | 364 | public static function getValidNamespaces() { |
| 330 | 365 | static $mValidNamespaces = null; |
| 331 | 366 | if (is_null($mValidNamespaces)) { |
| — | — | @@ -341,6 +376,7 @@ |
| 342 | 377 | |
| 343 | 378 | /** |
| 344 | 379 | * Using the settings determine the value for the given parameter |
| | 380 | + * |
| 345 | 381 | * @param $paramName String: parameter name |
| 346 | 382 | * @param $paramSettings Mixed: default value or an array of settings using PARAM_* constants. |
| 347 | 383 | * @param $parseMaxLimit Boolean: parse limit when max is given? |
| — | — | @@ -637,8 +673,10 @@ |
| 638 | 674 | print "\n</pre>\n"; |
| 639 | 675 | } |
| 640 | 676 | |
| 641 | | - public abstract function getVersion(); |
| 642 | 677 | |
| | 678 | + /** |
| | 679 | + * Returns a String that identifies the version of this class. |
| | 680 | + */ |
| 643 | 681 | public static function getBaseVersion() { |
| 644 | 682 | return __CLASS__ . ': $Id$'; |
| 645 | 683 | } |
| Index: trunk/phase3/includes/api/ApiUnblock.php |
| — | — | @@ -28,6 +28,9 @@ |
| 29 | 29 | } |
| 30 | 30 | |
| 31 | 31 | /** |
| | 32 | + * API module that facilitates the unblocking of users. Requires API write mode |
| | 33 | + * to be enabled. |
| | 34 | + * |
| 32 | 35 | * @addtogroup API |
| 33 | 36 | */ |
| 34 | 37 | class ApiUnblock extends ApiBase { |
| — | — | @@ -36,6 +39,9 @@ |
| 37 | 40 | parent :: __construct($main, $action); |
| 38 | 41 | } |
| 39 | 42 | |
| | 43 | + /** |
| | 44 | + * Unblocks the specified user or provides the reason the unblock failed. |
| | 45 | + */ |
| 40 | 46 | public function execute() { |
| 41 | 47 | global $wgUser; |
| 42 | 48 | $this->getMain()->requestWriteMode(); |