Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Mark API base classes as extensible

Browse source 
This marks API base classes as stable for extending per the
Stable Interface Policy.

Bug: T247862
Change-Id: I164192ba3d013d8bc98a8b9c6db10e3dd1e58b23
This commit is contained in:
daniel 2020-06-30 14:43:54 +02:00 committed by Daniel Kinzler
parent dfbbaecf0f
commit 948123e589
4 changed files with 47 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

25
includes/api/ApiBase.php
View file

@ -45,6 +45,8 @@ use Wikimedia\Rdbms\IDatabase;
* *
* Self-documentation: code to allow the API to document its own state * Self-documentation: code to allow the API to document its own state
* *
* @stable for subclassing
*
* @ingroup API * @ingroup API
*/ */
abstract class ApiBase extends ContextSource { abstract class ApiBase extends ContextSource {
@ -202,6 +204,7 @@ abstract class ApiBase extends ContextSource {
private $mModuleSource = false; private $mModuleSource = false;
/** /**
* @stable for calling
* @param ApiMain $mainModule * @param ApiMain $mainModule
* @param string $moduleName Name of this module * @param string $moduleName Name of this module
* @param string $modulePrefix Prefix to use for parameter names * @param string $modulePrefix Prefix to use for parameter names
@ -242,6 +245,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Get the module manager, or null if this module has no sub-modules * Get the module manager, or null if this module has no sub-modules
* @since 1.21 * @since 1.21
* @stable for overriding
* @return ApiModuleManager * @return ApiModuleManager
*/ */
public function getModuleManager() { public function getModuleManager() {
@ -255,6 +259,7 @@ abstract class ApiBase extends ContextSource {
* @note Do not use this just because you don't want to support non-json * @note Do not use this just because you don't want to support non-json
* formats. This should be used only when there is a fundamental * formats. This should be used only when there is a fundamental
* requirement for a specific format. * requirement for a specific format.
* @stable for overriding
* @return mixed Instance of a derived class of ApiFormatBase, or null * @return mixed Instance of a derived class of ApiFormatBase, or null
*/ */
public function getCustomPrinter() { public function getCustomPrinter() {
@ -270,6 +275,7 @@ abstract class ApiBase extends ContextSource {
* Do not call this base class implementation when overriding this method. * Do not call this base class implementation when overriding this method.
* *
* @since 1.25 * @since 1.25
* @stable for overriding
* @return array * @return array
*/ */
protected function getExamplesMessages() { protected function getExamplesMessages() {
@ -279,6 +285,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Return links to more detailed help pages about the module. * Return links to more detailed help pages about the module.
* @since 1.25, returning boolean false is deprecated * @since 1.25, returning boolean false is deprecated
* @stable for overriding
* @return string|array * @return string|array
*/ */
public function getHelpUrls() { public function getHelpUrls() {
@ -295,6 +302,7 @@ abstract class ApiBase extends ContextSource {
* in the overriding methods. Callers of this method can pass zero or * in the overriding methods. Callers of this method can pass zero or
* more OR-ed flags like GET_VALUES_FOR_HELP. * more OR-ed flags like GET_VALUES_FOR_HELP.
* *
* @stable for overriding
* @return array * @return array
*/ */
protected function getAllowedParams( /* $flags = 0 */ ) { protected function getAllowedParams( /* $flags = 0 */ ) {
@ -305,6 +313,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Indicates if this module needs maxlag to be checked * Indicates if this module needs maxlag to be checked
* @stable for overriding
* @return bool * @return bool
*/ */
public function shouldCheckMaxlag() { public function shouldCheckMaxlag() {
@ -313,6 +322,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Indicates whether this module requires read rights * Indicates whether this module requires read rights
* @stable for overriding
* @return bool * @return bool
*/ */
public function isReadMode() { public function isReadMode() {
@ -328,6 +338,7 @@ abstract class ApiBase extends ContextSource {
* Additionally, requests that only need replica DBs can be efficiently routed to any * Additionally, requests that only need replica DBs can be efficiently routed to any
* datacenter via the Promise-Non-Write-API-Action header. * datacenter via the Promise-Non-Write-API-Action header.
* *
* @stable for overriding
* @return bool * @return bool
*/ */
public function isWriteMode() { public function isWriteMode() {
@ -336,6 +347,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Indicates whether this module must be called with a POST request * Indicates whether this module must be called with a POST request
* @stable for overriding
* @return bool * @return bool
*/ */
public function mustBePosted() { public function mustBePosted() {
@ -345,6 +357,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Indicates whether this module is deprecated * Indicates whether this module is deprecated
* @since 1.25 * @since 1.25
* @stable for overriding
* @return bool * @return bool
*/ */
public function isDeprecated() { public function isDeprecated() {
@ -355,6 +368,7 @@ abstract class ApiBase extends ContextSource {
* Indicates whether this module is "internal" * Indicates whether this module is "internal"
* Internal API modules are not (yet) intended for 3rd party use and may be unstable. * Internal API modules are not (yet) intended for 3rd party use and may be unstable.
* @since 1.25 * @since 1.25
* @stable for overriding
* @return bool * @return bool
*/ */
public function isInternal() { public function isInternal() {
@ -377,6 +391,7 @@ abstract class ApiBase extends ContextSource {
* Returning true will generate errors indicating that the API module needs * Returning true will generate errors indicating that the API module needs
* updating. * updating.
* *
* @stable for overriding
* @return string|false * @return string|false
*/ */
public function needsToken() { public function needsToken() {
@ -390,6 +405,7 @@ abstract class ApiBase extends ContextSource {
* *
* @since 1.24 * @since 1.24
* @param array $params All supplied parameters for the module * @param array $params All supplied parameters for the module
* @stable for overriding
* @return string|array|null * @return string|array|null
*/ */
protected function getWebUITokenSalt( array $params ) { protected function getWebUITokenSalt( array $params ) {
@ -400,6 +416,7 @@ abstract class ApiBase extends ContextSource {
* Returns data for HTTP conditional request mechanisms. * Returns data for HTTP conditional request mechanisms.
* *
* @since 1.26 * @since 1.26
* @stable for overriding
* @param string $condition Condition being queried: * @param string $condition Condition being queried:
* - last-modified: Return a timestamp representing the maximum of the * - last-modified: Return a timestamp representing the maximum of the
* last-modified dates for all resources involved in the request. See * last-modified dates for all resources involved in the request. See
@ -454,6 +471,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Get the parent of this module * Get the parent of this module
* @stable for overriding
* @since 1.25 * @since 1.25
* @return ApiBase|null * @return ApiBase|null
*/ */
@ -555,6 +573,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Get the error formatter * Get the error formatter
* @stable for overriding
* @return ApiErrorFormatter * @return ApiErrorFormatter
*/ */
public function getErrorFormatter() { public function getErrorFormatter() {
@ -569,6 +588,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Gets a default replica DB connection object * Gets a default replica DB connection object
* @stable for overriding
* @return IDatabase * @return IDatabase
*/ */
protected function getDB() { protected function getDB() {
@ -655,6 +675,7 @@ abstract class ApiBase extends ContextSource {
/** /**
* Indicate if the module supports dynamically-determined parameters that * Indicate if the module supports dynamically-determined parameters that
* cannot be included in self::getAllowedParams(). * cannot be included in self::getAllowedParams().
* @stable for overriding
* @return string|array|Message|null Return null if the module does not * @return string|array|Message|null Return null if the module does not
* support additional dynamic parameters, otherwise return a message * support additional dynamic parameters, otherwise return a message
* describing them. * describing them.
@ -1658,6 +1679,7 @@ abstract class ApiBase extends ContextSource {
* list of modules. * list of modules.
* *
* @since 1.30 * @since 1.30
* @stable for overriding
* @return string|array|Message * @return string|array|Message
*/ */
protected function getSummaryMessage() { protected function getSummaryMessage() {
@ -1671,6 +1693,7 @@ abstract class ApiBase extends ContextSource {
* the summary. * the summary.
* *
* @since 1.30 * @since 1.30
* @stable for overriding
* @return string|array|Message * @return string|array|Message
*/ */
protected function getExtendedDescription() { protected function getExtendedDescription() {
@ -1684,6 +1707,7 @@ abstract class ApiBase extends ContextSource {
* Get final module summary * Get final module summary
* *
* @since 1.30 * @since 1.30
* @stable for overriding
* @return Message * @return Message
*/ */
public function getFinalSummary() { public function getFinalSummary() {
@ -2018,6 +2042,7 @@ abstract class ApiBase extends ContextSource {
* This exists mainly for ApiMain to add the Permissions and Credits * This exists mainly for ApiMain to add the Permissions and Credits
* sections. Other modules probably don't need it. * sections. Other modules probably don't need it.
* *
* @stable for overriding
* @param string[] &$help Array of help data * @param string[] &$help Array of help data
* @param array $options Options passed to ApiHelp::getHelp * @param array $options Options passed to ApiHelp::getHelp
* @param array &$tocData If a TOC is being generated, this array has keys * @param array &$tocData If a TOC is being generated, this array has keys

7
includes/api/ApiQueryBase.php
View file

@ -30,6 +30,8 @@ use Wikimedia\Rdbms\SelectQueryBuilder;
* It provides some common functionality such as constructing various SQL * It provides some common functionality such as constructing various SQL
* queries. * queries.
* *
* @stable for subclassing
*
* @ingroup API * @ingroup API
*/ */
abstract class ApiQueryBase extends ApiBase { abstract class ApiQueryBase extends ApiBase {
@ -43,6 +45,7 @@ abstract class ApiQueryBase extends ApiBase {
private $queryBuilder; private $queryBuilder;
/** /**
* @stable for calling
* @param ApiQuery $queryModule * @param ApiQuery $queryModule
* @param string $moduleName * @param string $moduleName
* @param string $paramPrefix * @param string $paramPrefix
@ -67,6 +70,7 @@ abstract class ApiQueryBase extends ApiBase {
* Public caching will only be allowed if *all* the modules that supply * Public caching will only be allowed if *all* the modules that supply
* data for a given request return a cache mode of public. * data for a given request return a cache mode of public.
* *
* @stable for overriding
* @param array $params * @param array $params
* @return string * @return string
*/ */
@ -81,6 +85,7 @@ abstract class ApiQueryBase extends ApiBase {
* Note this only makes sense for 'prop' modules, as 'list' and 'meta' * Note this only makes sense for 'prop' modules, as 'list' and 'meta'
* modules should not be using the pageset. * modules should not be using the pageset.
* *
* @stable for overriding
* @param ApiPageSet $pageSet * @param ApiPageSet $pageSet
*/ */
public function requestExtraData( $pageSet ) { public function requestExtraData( $pageSet ) {
@ -108,6 +113,7 @@ abstract class ApiQueryBase extends ApiBase {
/** /**
* Get the Query database connection (read-only) * Get the Query database connection (read-only)
* @stable for overriding
* @return IDatabase * @return IDatabase
*/ */
protected function getDB() { protected function getDB() {
@ -133,6 +139,7 @@ abstract class ApiQueryBase extends ApiBase {
/** /**
* Get the PageSet object to work on * Get the PageSet object to work on
* @stable for overriding
* @return ApiPageSet * @return ApiPageSet
*/ */
protected function getPageSet() { protected function getPageSet() {

2
includes/api/ApiQueryGeneratorBase.php
View file

@ -21,6 +21,8 @@
*/ */
/** /**
* @stable for subclassing
*
* @ingroup API * @ingroup API
*/ */
abstract class ApiQueryGeneratorBase extends ApiQueryBase { abstract class ApiQueryGeneratorBase extends ApiQueryBase {

13
includes/api/ApiQueryRevisionsBase.php
View file

@ -32,6 +32,8 @@ use Wikimedia\ParamValidator\TypeDef\IntegerDef;
/** /**
* A base class for functions common to producing a list of revisions. * A base class for functions common to producing a list of revisions.
* *
* @stable for subclassing
*
* @ingroup API * @ingroup API
*/ */
abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase { abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
@ -655,6 +657,12 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
return $vals; return $vals;
} }
/**
* @stable for overriding
* @param array $params
*
* @return string
*/
public function getCacheMode( $params ) { public function getCacheMode( $params ) {
if ( $this->userCanSeeRevDel() ) { if ( $this->userCanSeeRevDel() ) {
return 'private'; return 'private';
@ -663,6 +671,11 @@ abstract class ApiQueryRevisionsBase extends ApiQueryGeneratorBase {
return 'public'; return 'public';
} }
/**
* @stable for overriding
* @return array
* @throws MWException
*/
public function getAllowedParams() { public function getAllowedParams() {
$slotRoles = MediaWikiServices::getInstance()->getSlotRoleRegistry()->getKnownRoles(); $slotRoles = MediaWikiServices::getInstance()->getSlotRoleRegistry()->getKnownRoles();
sort( $slotRoles, SORT_STRING ); sort( $slotRoles, SORT_STRING );