From 751f69aa948a26dda48dd022e1efc8126d7ddb24 Mon Sep 17 00:00:00 2001 From: Yuri Astrakhan Date: Mon, 30 Oct 2006 00:18:05 +0000 Subject: [PATCH] API * Implemented backlinks / imagelinks / embeddedin modules * Revised help screen --- includes/api/ApiBase.php | 14 +- includes/api/ApiMain.php | 15 ++ includes/api/ApiPageSet.php | 27 +++- includes/api/ApiQuery.php | 4 +- includes/api/ApiQueryBacklinks.php | 243 +++++++++++++++++++++-------- includes/api/ApiQueryBase.php | 5 +- includes/api/ApiQueryRevisions.php | 2 +- 7 files changed, 230 insertions(+), 80 deletions(-) diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php index d524f54621..cee0018d67 100644 --- a/includes/api/ApiBase.php +++ b/includes/api/ApiBase.php @@ -170,14 +170,17 @@ abstract class ApiBase { $desc = isset ($paramsDescription[$paramName]) ? $paramsDescription[$paramName] : ''; if (is_array($desc)) $desc = implode($paramPrefix, $desc); + if (isset ($paramSettings[self :: PARAM_TYPE])) { + if (isset ($paramSettings[self :: PARAM_ISMULTI])) + $prompt = 'Multiple "|"-separated values: '; + else + $prompt = 'Any one of these values: '; $type = $paramSettings[self :: PARAM_TYPE]; if (is_array($type)) - $desc .= $paramPrefix . 'Allowed values: ' . implode(', ', $type); + $desc .= $paramPrefix . $prompt . implode(', ', $type); } - if (isset ($paramSettings[self :: PARAM_ISMULTI])) - $desc .= $paramPrefix . 'Allows multiple values separated with "|"'; - + $default = is_array($paramSettings) ? (isset ($paramSettings[self :: PARAM_DFLT]) ? $paramSettings[self :: PARAM_DFLT] : null) : $paramSettings; if (!is_null($default) && $default !== false) $desc .= $paramPrefix . "Default: $default"; @@ -327,7 +330,6 @@ abstract class ApiBase { break; default : ApiBase :: dieDebug(__METHOD__, "Param $paramName's type is unknown - $type"); - } } @@ -437,7 +439,7 @@ abstract class ApiBase { $this->profileOut(); } } - + /** * Total time the module was executed */ diff --git a/includes/api/ApiMain.php b/includes/api/ApiMain.php index 77e230ba7c..9fe2ccdec9 100644 --- a/includes/api/ApiMain.php +++ b/includes/api/ApiMain.php @@ -271,9 +271,21 @@ class ApiMain extends ApiBase { '', 'This API allows programs to access various functions of MediaWiki software.', 'For more details see API Home Page @ http://meta.wikimedia.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.', + ' Make sure you monitor changes to this page, wikitech-l mailing list,', + ' or the source code in the includes/api directory for any changes.', '' ); } + + 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' + ); + } /** * Override the parent to generate help messages for all available modules. @@ -303,6 +315,9 @@ class ApiMain extends ApiBase { $msg .= $msg2; $msg .= "\n"; } + + $msg .= "\n*** Credits: ***\n " . implode("\n ", $this->getCredits()) . "\n"; + return $msg; } diff --git a/includes/api/ApiPageSet.php b/includes/api/ApiPageSet.php index 33ebbf9173..ef05465e90 100644 --- a/includes/api/ApiPageSet.php +++ b/includes/api/ApiPageSet.php @@ -32,7 +32,7 @@ if (!defined('MEDIAWIKI')) { class ApiPageSet extends ApiQueryBase { private $mAllPages; // [ns][dbkey] => page_id or 0 when missing - private $mGoodTitles, $mMissingTitles, $mMissingPageIDs, $mRedirectTitles, $mNormalizedTitles; + private $mTitles, $mGoodTitles, $mMissingTitles, $mMissingPageIDs, $mRedirectTitles, $mNormalizedTitles; private $mResolveRedirects, $mPendingRedirectIDs; private $mGoodRevIDs, $mMissingRevIDs; @@ -42,6 +42,7 @@ class ApiPageSet extends ApiQueryBase { parent :: __construct($query, __CLASS__); $this->mAllPages = array (); + $this->mTitles = array(); $this->mGoodTitles = array (); $this->mMissingTitles = array (); $this->mMissingPageIDs = array (); @@ -88,6 +89,21 @@ class ApiPageSet extends ApiQueryBase { return array_keys(array_merge($pageFlds, $this->mRequestedPageFields)); } + /** + * All Title objects provided. + * @return array of Title objects + */ + public function getTitles() { + return $this->mTitles; + } + + /** + * Returns the number of unique pages (not revisions) in the set. + */ + public function getTitleCount() { + return count($this->mTitles); + } + /** * Title objects that were found in the database. * @return array page_id (int) => Title (obj) @@ -97,10 +113,10 @@ class ApiPageSet extends ApiQueryBase { } /** - * Returns the number of unique pages (not revisions) in the set. + * Returns the number of found unique pages (not revisions) in the set. */ public function getGoodTitleCount() { - return count($this->getGoodTitles()); + return count($this->mGoodTitles); } /** @@ -252,6 +268,7 @@ class ApiPageSet extends ApiQueryBase { $pageId = intval($row->page_id); $this->mAllPages[$row->page_namespace][$row->page_title] = $pageId; + $this->mTitles[] = $title; if ($this->mResolveRedirects && $row->page_is_redirect == '1') { $this->mPendingRedirectIDs[$pageId] = $title; @@ -366,8 +383,10 @@ class ApiPageSet extends ApiQueryBase { // The remaining titles in $remaining are non-existant pages foreach ($remaining as $ns => $dbkeys) { foreach ($dbkeys as $dbkey => $nothing) { - $this->mMissingTitles[] = Title :: makeTitle($ns, $dbkey); + $title = Title :: makeTitle($ns, $dbkey); + $this->mMissingTitles[] = $title; $this->mAllPages[$ns][$dbkey] = 0; + $this->mTitles[] = $title; } } } diff --git a/includes/api/ApiQuery.php b/includes/api/ApiQuery.php index 6ddac0adc3..b56fa4663e 100644 --- a/includes/api/ApiQuery.php +++ b/includes/api/ApiQuery.php @@ -50,7 +50,9 @@ class ApiQuery extends ApiBase { 'logevents' => 'ApiQueryLogEvents', 'watchlist' => 'ApiQueryWatchlist', 'recentchanges' => 'ApiQueryRecentChanges', - 'backlinks' => 'ApiQueryBacklinks' + 'backlinks' => 'ApiQueryBacklinks', + 'embeddedin' => 'ApiQueryBacklinks', + 'imagelinks' => 'ApiQueryBacklinks' ); // 'categorymembers' => 'ApiQueryCategorymembers', // 'embeddedin' => 'ApiQueryEmbeddedin', diff --git a/includes/api/ApiQueryBacklinks.php b/includes/api/ApiQueryBacklinks.php index 6c9063ed2d..a5076b5bea 100644 --- a/includes/api/ApiQueryBacklinks.php +++ b/includes/api/ApiQueryBacklinks.php @@ -33,8 +33,53 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { private $rootTitle, $contRedirs, $contLevel, $contTitle, $contID; + // output element name, database column field prefix, database table + private $backlinksSettings = array ( + 'backlinks' => array ( + 'code' => 'bl', + 'prefix' => 'pl', + 'linktbl' => 'pagelinks' + ), + 'embeddedin' => array ( + 'code' => 'ei', + 'prefix' => 'tl', + 'linktbl' => 'templatelinks' + ), + 'imagelinks' => array ( + 'code' => 'il', + 'prefix' => 'il', + 'linktbl' => 'imagelinks' + ) + ); + public function __construct($query, $moduleName) { - parent :: __construct($query, $moduleName, 'bl'); + $code = $prefix = $linktbl = null; + extract($this->backlinksSettings[$moduleName]); + + parent :: __construct($query, $moduleName, $code); + $this->bl_ns = $prefix . '_namespace'; + $this->bl_from = $prefix . '_from'; + $this->bl_tables = array ( + $linktbl, + 'page' + ); + $this->bl_code = $code; + + $this->hasNS = $moduleName !== 'imagelinks'; + if ($this->hasNS) { + $this->bl_title = $prefix . '_title'; + $this->bl_sort = "{$this->bl_ns}, {$this->bl_title}, {$this->bl_from}"; + $this->bl_fields = array ( + $this->bl_ns, + $this->bl_title + ); + } else { + $this->bl_title = $prefix . '_to'; + $this->bl_sort = "{$this->bl_title}, {$this->bl_from}"; + $this->bl_fields = array ( + $this->bl_title + ); + } } public function execute() { @@ -54,34 +99,25 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { $this->processContinue($continue, $redirect); - if (is_null($resultPageSet)) { + $this->addFields($this->bl_fields); + if (is_null($resultPageSet)) $this->addFields(array ( - 'pl_from as page_id', // is this more efficient than getting page_id? - 'pl_namespace', - 'pl_title', + 'page_id', 'page_namespace', 'page_title' )); - } else { - $this->addFields($resultPageSet->getPageTableFields()); - $this->addFields(array ( - 'pl_namespace', - 'pl_title', - - )); - } + else + $this->addFields($resultPageSet->getPageTableFields()); // will include page_id - $this->addTables(array ( - 'pagelinks', - 'page' - )); - $this->addWhere('pl_from=page_id'); + $this->addTables($this->bl_tables); + $this->addWhere($this->bl_from . '=page_id'); - $this->addWhereFld('pl_namespace', $this->rootTitle->getNamespace()); - $this->addWhereFld('pl_title', $this->rootTitle->getDBkey()); + if ($this->hasNS) + $this->addWhereFld($this->bl_ns, $this->rootTitle->getNamespace()); + $this->addWhereFld($this->bl_title, $this->rootTitle->getDBkey()); $this->addWhereFld('page_namespace', $namespace); $this->addOption('LIMIT', $limit +1); - $this->addOption('ORDER BY', 'pl_namespace, pl_title, pl_from'); + $this->addOption('ORDER BY', $this->bl_sort); if ($redirect) $this->addWhereFld('page_is_redirect', 0); @@ -91,11 +127,16 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { $plfrm = intval($this->contID); if ($this->contLevel == 0) { // For the first level, there is only one target title, so no need for complex filtering - $this->addWhere("pl_from>=$plfrm"); + $this->addWhere($this->bl_from . '>=' . $plfrm); } else { $ns = $this->contTitle->getNamespace(); $t = $db->addQuotes($this->contTitle->getDBkey()); - $this->addWhere("(pl_namespace>$ns OR (pl_namespace=$ns AND (pl_title>$t OR (pl_title=$t AND pl_from>=$plfrm))))"); + $whereWithoutNS = "{$this->bl_title}>$t OR ({$this->bl_title}=$t AND {$this->bl_from}>=$plfrm))"; + + if ($this->hasNS) + $this->addWhere("{$this->bl_ns}>$ns OR ({$this->bl_ns}=$ns AND ($whereWithoutNS)"); + else + $this->addWhere($whereWithoutNS); } } @@ -106,7 +147,14 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { while ($row = $db->fetchObject($res)) { if (++ $count > $limit) { // We've reached the one extra which shows that there are additional pages to be had. Stop here... - $continue = $this->rootTitle->getNamespace() . '|' . $this->rootTitle->getDBkey() . '|1|0|' . $row->pl_namespace . '|' . $row->pl_title . '|' . $row->page_id; + if ($redirect) { + $ns = $row-> { + $this->bl_ns }; + $t = $row-> { + $this->bl_title }; + $continue = $this->getContinueRedirStr(false, 0, $ns, $t, $row->page_id); + } else + $continue = $this->getContinueStr($row->page_id); $this->setContinueEnumParameter('continue', $continue); break; } @@ -123,17 +171,17 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { if (is_null($resultPageSet)) { $result = $this->getResult(); - $result->setIndexedTagName($data, 'bl'); + $result->setIndexedTagName($data, $this->bl_code); $result->addValue('query', $this->getModuleName(), $data); } } protected function processContinue($continue, $redirect) { $pageSet = $this->getPageSet(); - $count = $pageSet->getGoodTitleCount(); + $count = $pageSet->getTitleCount(); if (!is_null($continue)) { if ($count !== 0) - $this->dieUsage('When continuing the backlink query, no other titles may be provided', 'titles_on_continue'); + $this->dieUsage("When continuing the {$this->getModuleName()} query, no other titles may be provided", 'titles_on_continue'); $this->parseContinueParam($continue, $redirect); // Skip all completed links @@ -141,46 +189,61 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { } else { if ($count !== 1) - $this->dieUsage('Backlinks requires one title to start the query', 'bad_title_count'); - $this->rootTitle = array_pop($pageSet->getGoodTitles()); // only one title there + $this->dieUsage("The {$this->getModuleName()} query requires one title to start", 'bad_title_count'); + $this->rootTitle = current($pageSet->getTitles()); // only one title there } + + // only image titles are allowed for the root + if (!$this->hasNS && $this->rootTitle->getNamespace() !== NS_IMAGE) + $this->dieUsage("The title for {$this->getModuleName()} query must be an image", 'bad_image_title'); } protected function parseContinueParam($continue, $redirect) { - // - // the parameter will be in the format: - // ns|db_key|step|level|ns|db_key - // ns+db_key -- the root title - // step = 1 or 2 - which step to continue from - 1-titles, 2-redirects - // level -- how many levels to follow before starting enumerating. - // ns+title to continue from - // $continueList = explode('|', $continue); - if (count($continueList) === 7) { - $rootNs = intval($continueList[0]); - if (($rootNs !== 0 || $continueList[0] === '0') && !empty ($continueList[1])) { - $this->rootTitle = Title :: makeTitleSafe($rootNs, $continueList[1]); - if ($this->rootTitle && $this->rootTitle->userCanRead()) { - - $step = intval($continueList[2]); - if ($step === 1 || $step === 2) { - $this->contRedirs = ($step === 2); - - $level = intval($continueList[3]); - if ($level !== 0 || $continueList[3] === '0') { - $this->contLevel = $level; - - $contNs = intval($continueList[4]); - if (($contNs !== 0 || $continueList[4] === '0') && !empty ($continueList[5])) { - $this->contTitle = Title :: makeTitleSafe($contNs, $continueList[5]); - - $contID = intval($continueList[6]); - if ($contID !== 0 || $continueList[6] === '0') { - $this->contID = $contID; - - // When not processing redirects, only page through the non-redirects - if ($redirect || ($step === 1 && $level === 0 && $this->contTitle && $this->contTitle->userCanRead() && $this->contID > 0)) { - return; // done + if ($redirect) { + // + // expected redirect-mode parameter: + // ns|db_key|step|level|ns|db_key|id + // ns+db_key -- the root title + // step = 1 or 2 - which step to continue from - 1-titles, 2-redirects + // level -- how many levels to follow before starting enumerating. + // if level > 0 -- ns+title to continue from, otherwise skip these + // id = last page_id to continue from + // + if (count($continueList) > 4) { + $rootNs = intval($continueList[0]); + if (($rootNs !== 0 || $continueList[0] === '0') && !empty ($continueList[1])) { + $this->rootTitle = Title :: makeTitleSafe($rootNs, $continueList[1]); + if ($this->rootTitle && $this->rootTitle->userCanRead()) { + + $step = intval($continueList[2]); + if ($step === 1 || $step === 2) { + $this->contRedirs = ($step === 2); + + $level = intval($continueList[3]); + if ($level !== 0 || $continueList[3] === '0') { + $this->contLevel = $level; + + if ($level === 0) { + if (count($continueList) === 5) { + $contID = intval($continueList[4]); + if ($contID !== 0 || $continueList[4] === '0') { + $this->contID = $contID; + return; // done + } + } + } else { + if (count($continueList) === 7) { + $contNs = intval($continueList[4]); + if (($contNs !== 0 || $continueList[4] === '0') && !empty ($continueList[5])) { + $this->contTitle = Title :: makeTitleSafe($contNs, $continueList[5]); + + $contID = intval($continueList[6]); + if ($contID !== 0 || $continueList[6] === '0') { + $this->contID = $contID; + return; // done + } + } } } } @@ -188,11 +251,47 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { } } } + } else { + // + // expected non-redirect-mode parameter: + // ns|db_key|id + // ns+db_key -- the root title + // id = last page_id to continue from + // + if (count($continueList) === 3) { + $rootNs = intval($continueList[0]); + if (($rootNs !== 0 || $continueList[0] === '0') && !empty ($continueList[1])) { + $this->rootTitle = Title :: makeTitleSafe($rootNs, $continueList[1]); + if ($this->rootTitle && $this->rootTitle->userCanRead()) { + + $contID = intval($continueList[2]); + if ($contID !== 0) { + $this->contID = $contID; + return; // done + } + } + } + } } $this->dieUsage("Invalid continue param. You should pass the original value returned by the previous query", "_badcontinue"); } + protected function getContinueStr($lastPageID) { + return $this->rootTitle->getNamespace() . + '|' . $this->rootTitle->getDBkey() . + '|' . $lastPageID; + } + + protected function getContinueRedirStr($isRedirPhase, $level, $ns, $title, $lastPageID) { + return $this->rootTitle->getNamespace() . + '|' . $this->rootTitle->getDBkey() . + '|' . ($isRedirPhase ? 1 : 2) . + '|' . $level . + ($level > 0 ? ('|' . $ns . '|' . $title) : '') . + '|' . $lastPageID; + } + protected function getAllowedParams() { $namespaces = $this->getQuery()->getValidNamespaces(); @@ -227,12 +326,22 @@ class ApiQueryBacklinks extends ApiQueryGeneratorBase { } protected function getExamples() { - return array ( - 'api.php?action=query&list=backlinks&titles=Main%20Page', - 'api.php?action=query&generator=backlinks&titles=Main%20Page&prop=info', - - + static $examples = array ( + 'backlinks' => array ( + "api.php?action=query&list=backlinks&titles=Main%20Page", + "api.php?action=query&generator=backlinks&titles=Main%20Page&prop=info" + ), + 'embeddedin' => array ( + "api.php?action=query&list=embeddedin&titles=Template:Stub", + "api.php?action=query&generator=embeddedin&titles=Template:Stub&prop=info" + ), + 'imagelinks' => array ( + "api.php?action=query&list=imagelinks&titles=Image:Albert%20Einstein%20Head.jpg", + "api.php?action=query&generator=imagelinks&titles=Image:Albert%20Einstein%20Head.jpg&prop=info" + ) ); + + return $examples[$this->getModuleName()]; } public function getVersion() { diff --git a/includes/api/ApiQueryBase.php b/includes/api/ApiQueryBase.php index e4db51c7c9..16b265cb22 100644 --- a/includes/api/ApiQueryBase.php +++ b/includes/api/ApiQueryBase.php @@ -36,7 +36,10 @@ abstract class ApiQueryBase extends ApiBase { public function __construct($query, $moduleName, $paramPrefix = '') { parent :: __construct($query->getMain(), $moduleName, $paramPrefix); $this->mQueryModule = $query; - + $this->resetQueryParams(); + } + + protected function resetQueryParams() { $this->tables = array (); $this->where = array (); $this->fields = array(); diff --git a/includes/api/ApiQueryRevisions.php b/includes/api/ApiQueryRevisions.php index 57e0de483b..6efb638388 100644 --- a/includes/api/ApiQueryRevisions.php +++ b/includes/api/ApiQueryRevisions.php @@ -118,7 +118,7 @@ class ApiQueryRevisions extends ApiQueryBase { $this->validateLimit($this->encodeParamName('limit'), $limit, 1, $userMax, $botMax); // There is only one ID, use it - $this->addWhereFld('rev_page', array_pop(array_keys($pageSet->getGoodTitles()))); + $this->addWhereFld('rev_page', current(array_keys($pageSet->getGoodTitles()))); } elseif ($pageCount > 0) { // When working in multi-page non-enumeration mode, -- 2.20.1