| blob | 7ebd0c38d1a5c37e47fe0ff8adca6d6fae6d1c50 |
1 <?php
2 /**
3 *
4 *
5 * Created on Sep 5, 2006
6 *
7 * Copyright © 2006, 2010 Yuri Astrakhan "<Firstname><Lastname>@gmail.com"
8 *
9 * This program is free software; you can redistribute it and/or modify
10 * it under the terms of the GNU General Public License as published by
11 * the Free Software Foundation; either version 2 of the License, or
12 * (at your option) any later version.
13 *
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU General Public License for more details.
18 *
19 * You should have received a copy of the GNU General Public License along
20 * with this program; if not, write to the Free Software Foundation, Inc.,
21 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
22 * http://www.gnu.org/copyleft/gpl.html
23 *
24 * @file
25 */
27 /**
28 * This abstract class implements many basic API functions, and is the base of
29 * all API classes.
30 * The class functions are divided into several areas of functionality:
31 *
32 * Module parameters: Derived classes can define getAllowedParams() to specify
33 * which parameters to expect, how to parse and validate them.
34 *
35 * Profiling: various methods to allow keeping tabs on various tasks and their
36 * time costs
37 *
38 * Self-documentation: code to allow the API to document its own state
39 *
40 * @ingroup API
41 */
43 // These constants allow modules to specify exactly how to treat incoming parameters.
45 // Default value of the parameter
47 // Boolean, do we accept more than one item for this parameter (e.g.: titles)?
49 // Can be either a string type (e.g.: 'integer') or an array of allowed values
51 // Max value allowed for a parameter. Only applies if TYPE='integer'
53 // Max value allowed for a parameter for bots and sysops. Only applies if TYPE='integer'
55 // Lowest value allowed for a parameter. Only applies if TYPE='integer'
57 // Boolean, do we allow the same value to be set more than once when ISMULTI=true
59 // Boolean, is the parameter deprecated (will show a warning)
61 /// @since 1.17
63 /// @since 1.17
64 // Boolean, if MIN/MAX are set, enforce (die) these?
65 // Only applies if TYPE='integer' Use with extreme caution
68 // Name of property group that is on the root element of the result,
69 // i.e. not part of a list
71 // Boolean, is the result multiple items? Defaults to true for query modules,
72 // to false for other modules
75 // Boolean, can the property be not included in the result? Defaults to false
83 /**
84 * getAllowedParams() flag: When set, the result could take longer to generate,
85 * but should be more thorough. E.g. get the list of generators for ApiSandBox extension
86 * @since 1.21
87 */
90 /** @var ApiMain */
92 /** @var string */
97 /**
98 * @param ApiMain $mainModule
99 * @param string $moduleName Name of this module
100 * @param string $modulePrefix Prefix to use for parameter names
101 */
109 }
110 }
112 /*****************************************************************************
113 * ABSTRACT METHODS *
114 *****************************************************************************/
116 /**
117 * Evaluates the parameters, performs the requested query, and sets up
118 * the result. Concrete implementations of ApiBase must override this
119 * method to provide whatever functionality their module offers.
120 * Implementations must not produce any output on their own and are not
121 * expected to handle any errors.
122 *
123 * The execute() method will be invoked directly by ApiMain immediately
124 * before the result of the module is output. Aside from the
125 * constructor, implementations should assume that no other methods
126 * will be called externally on the module before the result is
127 * processed.
128 *
129 * The result data should be stored in the ApiResult object available
130 * through getResult().
131 */
134 /**
135 * Returns a string that identifies the version of the extending class.
136 * Typically includes the class name, the svn revision, timestamp, and
137 * last author. Usually done with SVN's Id keyword
138 * @return string
139 * @deprecated since 1.21, version string is no longer supported
140 */
145 }
147 /**
148 * Get the name of the module being executed by this instance
149 * @return string
150 */
153 }
155 /**
156 * Get the module manager, or null if this module has no sub-modules
157 * @since 1.21
158 * @return ApiModuleManager
159 */
162 }
164 /**
165 * Get parameter prefix (usually two letters or an empty string).
166 * @return string
167 */
170 }
172 /**
173 * Get the name of the module as shown in the profiler log
174 *
175 * @param DatabaseBase|bool $db
176 *
177 * @return string
178 */
182 }
185 }
187 /**
188 * Get the main module
189 * @return ApiMain
190 */
193 }
195 /**
196 * Returns true if this module is the main module ($this === $this->mMainModule),
197 * false otherwise.
198 * @return bool
199 */
202 }
204 /**
205 * Get the result object
206 * @return ApiResult
207 */
209 // Main module has getResult() method overridden
210 // Safety - avoid infinite loop:
213 }
216 }
218 /**
219 * Get the result data array (read-only)
220 * @return array
221 */
224 }
226 /**
227 * Set warning section for this module. Users should monitor this
228 * section to notice any changes in API. Multiple calls to this
229 * function will result in the warning messages being separated by
230 * newlines
231 * @param string $warning Warning message
232 */
238 // Don't add duplicate warnings
241 // If $warning was found in $oldWarning, check if it starts at 0 or after "\n"
243 // Check if $warning is followed by "\n" or the end of the $oldWarning
247 }
248 }
249 // If there is a warning already, append it to the existing one
251 }
256 }
258 /**
259 * If the module may only be used with a certain format module,
260 * it should override this method to return an instance of that formatter.
261 * A value of null means the default format will be used.
262 * @return mixed Instance of a derived class of ApiFormatBase, or null
263 */
266 }
268 /**
269 * Generates help message for this module, or false if there is no description
270 * @return string|bool
271 */
281 $msg
282 );
283 }
290 }
293 }
296 }
299 ) {
301 }
303 // Parameters
307 }
313 $examples
314 );
315 }
325 }
328 }
329 }
330 }
331 }
334 }
336 /**
337 * @param string $item
338 * @return string
339 */
342 }
344 /**
345 * @param string $prefix Text to split output items
346 * @param string $title What is being output
347 * @param string|array $input
348 * @return string
349 */
353 }
356 }
363 }
367 }
370 }
372 /**
373 * Generates the parameter descriptions for this module, to be displayed in the
374 * module's help.
375 * @return string|bool
376 */
389 }
391 //handle shorthand
395 );
396 }
398 //handle missing type
409 }
410 }
414 ) {
416 }
420 ) {
422 }
436 }
446 }
447 }
455 // Special handling because namespaces are
456 // type-limited, yet they are not given
466 }
483 }
486 }
491 }
492 }
497 }
502 ) {
505 }
506 }
507 }
512 }
515 }
518 }
521 }
523 /**
524 * Returns the description string for this module
525 * @return string|array
526 */
529 }
531 /**
532 * Returns usage examples for this module. Return false if no examples are available.
533 * @return bool|string|array
534 */
537 }
539 /**
540 * Returns an array of allowed parameters (parameter name) => (default
541 * value) or (parameter name) => (array with PARAM_* constants as keys)
542 * Don't call this function directly: use getFinalParams() to allow
543 * hooks to modify parameters as needed.
544 *
545 * Some derived classes may choose to handle an integer $flags parameter
546 * in the overriding methods. Callers of this method can pass zero or
547 * more OR-ed flags like GET_VALUES_FOR_HELP.
548 *
549 * @return array|bool
550 */
552 // int $flags is not declared because it causes "Strict standards"
553 // warning. Most derived classes do not implement it.
555 }
557 /**
558 * Returns an array of parameter descriptions.
559 * Don't call this function directly: use getFinalParamDescription() to
560 * allow hooks to modify descriptions as needed.
561 * @return array|bool False on no parameter descriptions
562 */
565 }
567 /**
568 * Get final list of parameters, after hooks have had a chance to
569 * tweak it as needed.
570 *
571 * @param int $flags Zero or more flags like GET_VALUES_FOR_HELP
572 * @return array|bool False on no parameters
573 * @since 1.21 $flags param added
574 */
580 }
582 /**
583 * Get final parameter descriptions, after hooks have had a chance to tweak it as
584 * needed.
585 *
586 * @return array|bool False on no parameter descriptions
587 */
593 }
595 /**
596 * Returns possible properties in the result, grouped by the value of the prop parameter
597 * that shows them.
598 *
599 * Properties that are shown always are in a group with empty string as a key.
600 * Properties that can be shown by several values of prop are included multiple times.
601 * If some properties are part of a list and some are on the root object (see ApiQueryQueryPage),
602 * those on the root object are under the key PROP_ROOT.
603 * The array can also contain a boolean under the key PROP_LIST,
604 * indicating whether the result is a list.
605 *
606 * Don't call this function directly: use getFinalResultProperties() to
607 * allow hooks to modify descriptions as needed.
608 *
609 * @return array|bool False on no properties
610 */
613 }
615 /**
616 * Get final possible result properties, after hooks have had a chance to tweak it as
617 * needed.
618 *
619 * @return array
620 */
626 }
628 /**
629 * Add token properties to the array used by getResultProperties,
630 * based on a token functions mapping.
631 * @param array $props
632 * @param array $tokenFunctions
633 */
639 );
640 }
641 }
643 /**
644 * Get final module description, after hooks have had a chance to tweak it as
645 * needed.
646 *
647 * @return array|bool False on no parameters
648 */
654 }
656 /**
657 * This method mangles parameter name based on the prefix supplied to the constructor.
658 * Override this method to change parameter name during runtime
659 * @param string $paramName Parameter name
660 * @return string Prefixed parameter name
661 */
664 }
666 /**
667 * Using getAllowedParams(), this function makes an array of the values
668 * provided by the user, with key being the name of the variable, and
669 * value - validated value from user or default. limits will not be
670 * parsed if $parseLimit is set to false; use this when the max
671 * limit is not definitive yet, e.g. when getting revisions.
672 * @param bool $parseLimit True by default
673 * @return array
674 */
676 // Cache parameters, for performance and to avoid bug 24564.
685 }
686 }
688 }
691 }
693 /**
694 * Get a value for the given parameter
695 * @param string $paramName Parameter name
696 * @param bool $parseLimit See extractRequestParams()
697 * @return mixed Parameter value
698 */
704 }
706 /**
707 * Die if none or more than one of a certain set of parameters is set and not false.
708 *
709 * Call getRequireOnlyOneParameterErrorMessages() to get a list of possible errors.
710 *
711 * @param array $params User provided set of parameters, as from $this->extractRequestParams()
712 * @param string $required,... Names of parameters of which exactly one must be set
713 */
729 'missingparam'
730 );
731 }
732 }
734 /**
735 * Generates the possible errors requireOnlyOneParameter() can die with
736 *
737 * @param array $params
738 * @return array
739 */
748 ),
752 )
753 );
754 }
756 /**
757 * Die if more than one of a certain set of parameters is set and not false.
758 *
759 * Call getRequireMaxOneParameterErrorMessages() to get a list of possible errors.
760 *
761 * @param array $params User provided set of parameters, as from $this->extractRequestParams()
762 * @param string $required,... Names of parameters of which at most one must be set
763 */
775 'invalidparammix'
776 );
777 }
778 }
780 /**
781 * Generates the possible error requireMaxOneParameter() can die with
782 *
783 * @param array $params
784 * @return array
785 */
794 )
795 );
796 }
798 /**
799 * Die if none of a certain set of parameters is set and not false.
800 *
801 * Call getRequireAtLeastOneParameterErrorMessages() to get a list of possible errors.
802 *
803 * @since 1.23
804 * @param array $params User provided set of parameters, as from $this->extractRequestParams()
805 * @param string $required,... Names of parameters of which at least one must be set
806 */
814 $required
815 );
820 }
821 }
823 /**
824 * Generates the possible errors requireAtLeastOneParameter() can die with
825 *
826 * @since 1.23
827 * @param array $params Array of parameter key names
828 * @return array
829 */
838 ),
839 );
840 }
842 /**
843 * Get a WikiPage object from a title or pageid param, if possible.
844 * Can die, if no param is set or if the title or page id is not valid.
845 *
846 * Call getTitleOrPageIdErrorMessage() to get a list of possible errors.
847 *
848 * @param array $params
849 * @param bool|string $load Whether load the object's state from the database:
850 * - false: don't load (if the pageid is given, it will still be loaded)
851 * - 'fromdb': load from a slave database
852 * - 'fromdbmaster': load from the master database
853 * @return WikiPage
854 */
863 }
866 }
870 }
874 }
878 }
879 }
882 }
884 /**
885 * Generates the possible error getTitleOrPageId() can die with
886 *
887 * @return array
888 */
896 )
897 );
898 }
900 /**
901 * Callback function used in requireOnlyOneParameter to check whether required parameters are set
902 *
903 * @param object $x Parameter to check is not null/false
904 * @return bool
905 */
908 }
910 /**
911 * Return true if we're to watch the page, false if not, null if no change.
912 * @param string $watchlist Valid values: 'watch', 'unwatch', 'preferences', 'nochange'
913 * @param Title $titleObj The page under consideration
914 * @param string $userOption The user option to consider when $watchlist=preferences.
915 * If not set will use watchdefault always and watchcreations if $titleObj doesn't exist.
916 * @return bool
917 */
930 # If the user is already watching, don't bother checking
933 }
934 # If no user option was passed, use watchdefault and watchcreations
938 }
940 # Watch the article based on the user preference
948 }
949 }
951 /**
952 * Set a watch (or unwatch) based the based on a watchlist parameter.
953 * @param string $watch Valid values: 'watch', 'unwatch', 'preferences', 'nochange'
954 * @param Title $titleObj The article's title to change
955 * @param string $userOption The user option to consider when $watch=preferences
956 */
961 }
964 }
966 /**
967 * Using the settings determine the value for the given parameter
968 *
969 * @param string $paramName Parameter name
970 * @param array|mixed $paramSettings Default value or an array of settings
971 * using PARAM_* constants.
972 * @param bool $parseLimit Parse limit?
973 * @return mixed Parameter value
974 */
976 // Some classes may decide to change parameter names
1006 // When type is not given, and no choices, the type is the same as $default
1012 }
1013 }
1014 }
1018 // Having a default value of anything other than 'false' is not allowed
1020 __METHOD__,
1022 "Boolean parameters must default to false."
1023 );
1024 }
1029 // Having a default value is not allowed
1031 __METHOD__,
1034 }
1037 }
1040 // This will get the value without trying to normalize it
1041 // (because trying to normalize a large binary file
1042 // accidentally uploaded as a field fails spectacularly)
1050 );
1051 }
1052 }
1058 }
1059 }
1067 );
1068 }
1070 // More validation only when choices were not given
1071 // choices were validated in parseMultiValue()
1080 }
1093 }
1094 }
1099 }
1100 }
1104 // Don't do any validation whatsoever
1106 }
1109 ) {
1111 __METHOD__,
1113 );
1114 }
1117 }
1132 );
1133 }
1138 }
1144 }
1147 }
1153 }
1156 }
1162 }
1163 }
1165 // Throw out duplicates if requested
1168 }
1170 // Set a warning if a deprecated parameter has been passed
1173 }
1176 }
1179 }
1181 /**
1182 * Return an array of values that were given in a 'a|b|c' notation,
1183 * after it optionally validates them against the list allowed values.
1184 *
1185 * @param string $valueName The name of the parameter (for error
1186 * reporting)
1187 * @param mixed $value The value being parsed
1188 * @param bool $allowMultiple Can $value contain more than one value
1189 * separated by '|'?
1190 * @param string[]|null $allowedValues An array of values to check against. If
1191 * null, all values are accepted.
1192 * @return string|string[] (allowMultiple ? an_array_of_values : a_single_value)
1193 */
1197 }
1199 // This is a bit awkward, but we want to avoid calling canApiHighLimits()
1200 // because it unstubs $wgUser
1203 ? self::LIMIT_SML2
1209 }
1212 // Bug 33482 - Allow entries with | in them for non-multiple values
1215 }
1223 );
1224 }
1227 // Check for unknown values
1238 );
1239 }
1240 }
1241 // Now throw them out
1243 }
1246 }
1248 /**
1249 * Validate the value against the minimum and user/bot maximum limits.
1250 * Prints usage info on failure.
1251 * @param string $paramName Parameter name
1252 * @param int $value Parameter value
1253 * @param int|null $min Minimum value
1254 * @param int|null $max Maximum value for users
1255 * @param int $botMax Maximum value for sysops/bots
1256 * @param bool $enforceLimits Whether to enforce (die) if value is outside limits
1257 */
1258 function validateLimit( $paramName, &$value, $min, $max, $botMax = null, $enforceLimits = false ) {
1264 }
1266 // Minimum is always validated, whereas maximum is checked only if not
1267 // running in internal call mode
1270 }
1272 // Optimization: do not check user's bot status unless really needed -- skips db query
1273 // assumes $botMax >= $max
1281 }
1283 $msg = $this->encodeParamName( $paramName ) . " may not be over $max (set to $value) for users";
1286 }
1287 }
1288 }
1290 /**
1291 * Validate and normalize of parameters of type 'timestamp'
1292 * @param string $value Parameter value
1293 * @param string $encParamName Parameter name
1294 * @return string Validated and normalized parameter
1295 */
1302 );
1303 }
1306 }
1308 /**
1309 * Validate and normalize of parameters of type 'user'
1310 * @param string $value Parameter value
1311 * @param string $encParamName Parameter name
1312 * @return string Validated and normalized parameter
1313 */
1320 );
1321 }
1324 }
1326 /**
1327 * Adds a warning to the output, else dies
1328 *
1329 * @param string $msg Message to show as a warning, or error message if dying
1330 * @param bool $enforceLimits Whether this is an enforce (die)
1331 */
1335 }
1338 }
1340 /**
1341 * Truncate an array to a certain length.
1342 * @param array $arr Array to truncate
1343 * @param int $limit Maximum length
1344 * @return bool True if the array was truncated, false otherwise
1345 */
1351 }
1354 }
1356 /**
1357 * Throw a UsageException, which will (if uncaught) call the main module's
1358 * error handler and die with an error message.
1359 *
1360 * @param string $description One-line human-readable description of the
1361 * error condition, e.g., "The API requires a valid action parameter"
1362 * @param string $errorCode Brief, arbitrary, stable string to allow easy
1363 * automated identification of the error, e.g., 'unknown_action'
1364 * @param int $httpRespCode HTTP response code
1365 * @param array $extradata Data to add to the "<error>" element; array in ApiResult format
1366 * @throws UsageException
1367 */
1374 $extradata
1375 );
1376 }
1378 /**
1379 * Get error (as code, string) from a Status object.
1380 *
1381 * @since 1.23
1382 * @param Status $status
1383 * @return array Array of code and error string
1384 */
1388 }
1392 // No errors? Assume the warnings should be treated as errors
1394 }
1396 // Still no errors? Punt
1398 }
1400 // Cannot use dieUsageMsg() because extensions might return custom
1401 // error messages.
1408 }
1410 // Translate message to code, for backwards compatability
1412 }
1415 }
1417 /**
1418 * Throw a UsageException based on the errors in the Status object.
1419 *
1420 * @since 1.22
1421 * @param Status $status
1422 * @throws MWException
1423 */
1428 }
1430 // @codingStandardsIgnoreStart Allow long lines. Cannot split these.
1431 /**
1432 * Array that maps message keys to error messages. $1 and friends are replaced.
1433 */
1435 // This one MUST be present, or dieUsageMsg() will recurse infinitely
1439 // Messages from Title::getUserPermissionsErrors()
1443 ),
1447 ),
1451 ),
1455 ),
1459 ),
1462 'info' => "The page you're trying to edit is protected because it's included in a cascade-protected page"
1463 ),
1467 ),
1471 ),
1479 ),
1483 ),
1487 ),
1491 ),
1495 ),
1499 ),
1503 ),
1507 ),
1510 'info' => "Your IP address has been blocked automatically, because it was used by a blocked user"
1511 ),
1513 // Miscellaneous interface messages
1517 ),
1521 ),
1525 ),
1529 ),
1536 ),
1540 ),
1542 ),
1546 ),
1550 ),
1554 ),
1558 ),
1562 ),
1566 ),
1570 ),
1571 // 'badarticleerror' => shouldn't happen
1572 // 'badtitletext' => shouldn't happen
1577 ),
1581 ),
1587 ),
1590 'info' => "IP address \"\$1\" was blocked as part of range \"\$2\". You can't unblock the IP individually, but you can unblock the range as a whole."
1591 ),
1595 ),
1598 'info' => "You are not logged in, you do not have a confirmed email address, or you are not allowed to send email to other users, so you cannot send email"
1599 ),
1603 ),
1607 ),
1611 ),
1615 ),
1619 ),
1622 'info' => "The user has not specified a valid email address, or has chosen not to receive email from other users"
1623 ),
1627 ),
1631 ),
1635 ),
1639 ),
1643 ),
1647 ),
1654 ),
1658 ),
1660 // API-specific messages
1664 ),
1667 'info' => "Editing of this wiki through the API is disabled. Make sure the \$wgEnableWriteAPI=true; statement is included in the wiki's LocalSettings.php file"
1668 ),
1672 ),
1676 'nosuchrevid' => array( 'code' => 'nosuchrevid', 'info' => "There is no revision with ID \$1" ),
1679 'invalidexpiry' => array( 'code' => 'invalidexpiry', 'info' => "Invalid expiry time \"\$1\"" ),
1680 'pastexpiry' => array( 'code' => 'pastexpiry', 'info' => "Expiry time \"\$1\" is in the past" ),
1684 ),
1688 ),
1691 ),
1695 ),
1699 ),
1703 ),
1707 ),
1711 ),
1714 'info' => "Couldn't undelete: the requested revisions may not exist, or may have been undeleted already"
1715 ),
1719 ),
1723 ),
1727 ),
1731 ),
1735 ),
1739 ),
1743 ),
1747 ),
1751 ),
1756 ),
1760 ),
1764 ),
1768 ),
1772 ),
1776 ),
1780 ),
1783 'info' => 'The target file exists on a shared repository and you do not have permission to override it'
1784 ),
1787 'info' => 'The target file exists on a shared repository. Use the ignorewarnings parameter to override it.'
1788 ),
1792 ),
1796 ),
1800 ),
1804 ),
1808 ),
1812 ),
1815 'info' => 'A file with name "$1" already exists in the shared file repository, and cannot be overwritten.'
1816 ),
1820 ),
1822 // ApiEditPage messages
1826 ),
1830 ),
1834 ),
1838 ),
1839 'noedit-anon' => array( 'code' => 'noedit-anon', 'info' => "Anonymous users can't edit pages" ),
1844 ),
1848 ),
1850 'hashcheckfailed' => array( 'code' => 'badmd5', 'info' => "The supplied MD5 hash was incorrect" ),
1854 ),
1858 ),
1862 ),
1866 ),
1868 // Messages from WikiPage::doEit()
1872 ),
1876 ),
1881 ),
1883 // uploadMsgs
1888 'info' => 'Uploads are not enabled. Make sure $wgEnableUploads is set to true in LocalSettings.php and the PHP ini setting file_uploads is true'
1889 ),
1892 'info' => 'Uploads by URL is not enabled. Make sure $wgAllowCopyUploads is set to true in LocalSettings.php.'
1893 ),
1897 ),
1901 ),
1906 ),
1907 'filename-toolong' => array( 'code' => 'filename-toolong', 'info' => 'The filename is too long' ),
1911 ),
1915 ),
1917 'mustbeloggedin' => array( 'code' => 'mustbeloggedin', 'info' => 'You must be logged in to $1.' )
1918 );
1919 // @codingStandardsIgnoreEnd
1921 /**
1922 * Helper function for readonly errors
1923 */
1928 }
1930 /**
1931 * Output the error message related to a certain array
1932 * @param array|string $error Element of a getUserPermissionsErrors()-style array
1933 */
1935 # most of the time we send a 1 element, so we might as well send it as
1936 # a string and make this an array here.
1939 }
1942 }
1944 /**
1945 * Will only set a warning instead of failing if the global $wgDebugAPI
1946 * is set to true. Otherwise behaves exactly as dieUsageMsg().
1947 * @param array|string $error Element of a getUserPermissionsErrors()-style array
1948 * @since 1.21
1949 */
1953 }
1957 }
1960 }
1962 /**
1963 * Die with the $prefix.'badcontinue' error. This call is common enough to
1964 * make it into the base method.
1965 * @param bool $condition Will only die if this value is true
1966 * @since 1.21
1967 */
1973 }
1974 }
1976 /**
1977 * Return the error message related to a certain array
1978 * @param array $error Element of a getUserPermissionsErrors()-style array
1979 * @return array('code' => code, 'info' => info)
1980 */
1985 // Check whether the error array was nested
1986 // array( array( <code>, <params> ), array( <another_code>, <params> ) )
1990 }
1996 );
1997 }
1999 // If the key isn't present, throw an "unknown error"
2001 }
2003 /**
2004 * Internal code errors should be reported with this method
2005 * @param string $method Method or function name
2006 * @param string $message Error message
2007 * @throws MWException
2008 */
2011 }
2013 /**
2014 * Indicates if this module needs maxlag to be checked
2015 * @return bool
2016 */
2019 }
2021 /**
2022 * Indicates whether this module requires read rights
2023 * @return bool
2024 */
2027 }
2029 /**
2030 * Indicates whether this module requires write mode
2031 * @return bool
2032 */
2035 }
2037 /**
2038 * Indicates whether this module must be called with a POST request
2039 * @return bool
2040 */
2043 }
2045 /**
2046 * Returns whether this module requires a token to execute
2047 * It is used to show possible errors in action=paraminfo
2048 * see bug 25248
2049 * @return bool
2050 */
2053 }
2055 /**
2056 * Returns the token salt if there is one,
2057 * '' if the module doesn't require a salt,
2058 * else false if the module doesn't need a token
2059 * You have also to override needsToken()
2060 * Value is passed to User::getEditToken
2061 * @return bool|string|array
2062 */
2065 }
2067 /**
2068 * Gets the user for whom to get the watchlist
2069 *
2070 * @param array $params
2071 * @return User
2072 */
2078 }
2083 'bad_wltoken'
2084 );
2085 }
2089 }
2092 }
2094 }
2097 }
2099 /**
2100 * @return bool|string|array Returns a false if the module has no help URL,
2101 * else returns a (array of) string
2102 */
2105 }
2107 /**
2108 * Returns a list of all possible errors returned by the module
2109 *
2110 * Don't call this function directly: use getFinalPossibleErrors() to allow
2111 * hooks to modify parameters as needed.
2112 *
2113 * @return array Array in the format of array( key, param1, param2, ... )
2114 * or array( 'code' => ..., 'info' => ... )
2115 */
2124 ) {
2126 }
2127 }
2132 'original value returned by the previous query'
2133 );
2134 }
2135 }
2139 }
2143 }
2148 }
2153 ) {
2154 // Add token as possible missing parameter, if not already done
2156 }
2158 }
2161 }
2163 /**
2164 * Get final list of possible errors, after hooks have had a chance to
2165 * tweak it as needed.
2166 *
2167 * @return array
2168 * @since 1.22
2169 */
2175 }
2177 /**
2178 * Parses a list of errors into a standardised format
2179 * @param array $errors List of errors. Items can be in the for
2180 * array( key, param1, param2, ... ) or array( 'code' => ..., 'info' => ... )
2181 * @return array Parsed list of errors with items in the form array( 'code' => ..., 'info' => ... )
2182 */
2191 }
2192 }
2195 }
2197 /**
2198 * Profiling: total module execution time
2199 */
2202 /**
2203 * Start module profiling
2204 */
2208 }
2211 }
2213 /**
2214 * End module profiling
2215 */
2219 }
2222 __METHOD__,
2223 'Must be called after database profiling is done with profileDBOut()'
2224 );
2225 }
2230 }
2232 /**
2233 * When modules crash, sometimes it is needed to do a profileOut() regardless
2234 * of the profiling state the module was in. This method does such cleanup.
2235 */
2240 }
2242 }
2243 }
2245 /**
2246 * Total time the module was executed
2247 * @return float
2248 */
2252 }
2255 }
2257 /**
2258 * Profiling: database execution time
2259 */
2262 /**
2263 * Start module profiling
2264 */
2268 __METHOD__,
2269 'Must be called while profiling the entire module with profileIn()'
2270 );
2271 }
2274 }
2277 }
2279 /**
2280 * End database profiling
2281 */
2286 }
2289 }
2297 }
2299 /**
2300 * Total time the module used the database
2301 * @return float
2302 */
2306 }
2309 }
2311 /**
2312 * Gets a default slave database connection object
2313 * @return DatabaseBase
2314 */
2320 }
2323 }
2325 /**
2326 * Debugging function that prints a value and an optional backtrace
2327 * @param mixed $value Value to print
2328 * @param string $name Description of the printed value
2329 * @param bool $backtrace If true, print a backtrace
2330 */
2336 }
2338 }
2339 }