From 065f3c1b6c9cbc2cd126a3c1b34c82b1b2f5d02a Mon Sep 17 00:00:00 2001 From: Daniel Cannon Date: Fri, 12 Oct 2007 00:15:21 +0000 Subject: [PATCH] API: Add a little docu so that we might be able to make some sense of how this works ;) --- includes/api/ApiQueryRecentChanges.php | 60 ++++++++++++++++++++++++-- 1 file changed, 56 insertions(+), 4 deletions(-) diff --git a/includes/api/ApiQueryRecentChanges.php b/includes/api/ApiQueryRecentChanges.php index 2268a8f72e..6809840d01 100644 --- a/includes/api/ApiQueryRecentChanges.php +++ b/includes/api/ApiQueryRecentChanges.php @@ -44,10 +44,21 @@ class ApiQueryRecentChanges extends ApiQueryBase { $fld_timestamp = false, $fld_title = false, $fld_ids = false, $fld_sizes = false; + /** + * Generates and outputs the result of this query based upon the provided parameters. + */ public function execute() { + /* Initialize vars */ $limit = $prop = $namespace = $show = $dir = $start = $end = null; + + /* Get the parameters of the request. */ extract($this->extractRequestParams()); + /* Build our basic query. Namely, something along the lines of: + * SELECT * from recentchanges WHERE rc_timestamp > $start + * AND rc_timestamp < $end AND rc_namespace = $namespace + * AND rc_deleted = '0' + */ $this->addTables('recentchanges'); $this->addWhereRange('rc_timestamp', $dir, $start, $end); $this->addWhereFld('rc_namespace', $namespace); @@ -55,9 +66,16 @@ class ApiQueryRecentChanges extends ApiQueryBase { if (!is_null($show)) { $show = array_flip($show); - if ((isset ($show['minor']) && isset ($show['!minor'])) || (isset ($show['bot']) && isset ($show['!bot'])) || (isset ($show['anon']) && isset ($show['!anon']))) + + /* Check for conflicting parameters. */ + if ((isset ($show['minor']) && isset ($show['!minor'])) + || (isset ($show['bot']) && isset ($show['!bot'])) + || (isset ($show['anon']) && isset ($show['!anon']))) { + $this->dieUsage("Incorrect parameter - mutually exclusive values may not be supplied", 'show'); + } + /* Add additional conditions to query depending upon parameters. */ $this->addWhereIf('rc_minor = 0', isset ($show['!minor'])); $this->addWhereIf('rc_minor != 0', isset ($show['minor'])); $this->addWhereIf('rc_bot = 0', isset ($show['!bot'])); @@ -66,6 +84,7 @@ class ApiQueryRecentChanges extends ApiQueryBase { $this->addWhereIf('rc_user != 0', isset ($show['!anon'])); } + /* Add the fields we're concerned with to out query. */ $this->addFields(array ( 'rc_timestamp', 'rc_namespace', @@ -75,9 +94,11 @@ class ApiQueryRecentChanges extends ApiQueryBase { 'rc_moved_to_title' )); + /* Determine what properties we need to display. */ if (!is_null($prop)) { $prop = array_flip($prop); + /* Set up internal members based upon params. */ $this->fld_comment = isset ($prop['comment']); $this->fld_user = isset ($prop['user']); $this->fld_flags = isset ($prop['flags']); @@ -85,7 +106,8 @@ class ApiQueryRecentChanges extends ApiQueryBase { $this->fld_title = isset ($prop['title']); $this->fld_ids = isset ($prop['ids']); $this->fld_sizes = isset ($prop['sizes']); - + + /* Add fields to our query if they are specified as a needed parameter. */ $this->addFieldsIf('rc_id', $this->fld_ids); $this->addFieldsIf('rc_cur_id', $this->fld_ids); $this->addFieldsIf('rc_this_oldid', $this->fld_ids); @@ -100,14 +122,21 @@ class ApiQueryRecentChanges extends ApiQueryBase { $this->addFieldsIf('rc_new_len', $this->fld_sizes); } + /* Specify the limit for our query. It's $limit+1 because we (possibly) need to + * generate a "continue" parameter, to allow paging. */ $this->addOption('LIMIT', $limit +1); + + /* Specify the index to use in the query as rc_timestamp, instead of rc_revid (default). */ $this->addOption('USE INDEX', 'rc_timestamp'); $data = array (); $count = 0; + + /* Perform the actual query. */ $db = $this->getDB(); $res = $this->select(__METHOD__); - + + /* Iterate through the rows, adding data extracted from them to our query result. */ 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... @@ -115,23 +144,39 @@ class ApiQueryRecentChanges extends ApiQueryBase { break; } + /* Extract the data from a single row. */ $vals = $this->extractRowInfo($row); + + /* Add that row's data to our final output. */ if($vals) $data[] = $vals; } + $db->freeResult($res); + /* Format the result */ $result = $this->getResult(); $result->setIndexedTagName($data, 'rc'); $result->addValue('query', $this->getModuleName(), $data); } + /** + * Extracts from a single sql row the data needed to describe one recent change. + * + * @param $row The row from which to extract the data. + * @return An array mapping strings (descriptors) to their respective string values. + * @access private + */ private function extractRowInfo($row) { + /* If page was moved somewhere, get the title of the move target. */ $movedToTitle = false; if (!empty($row->rc_moved_to_title)) $movedToTitle = Title :: makeTitle($row->rc_moved_to_ns, $row->rc_moved_to_title); + /* Determine the title of the page that has been changed. */ $title = Title :: makeTitle($row->rc_namespace, $row->rc_title); + + /* Our output data. */ $vals = array (); $type = intval ( $row->rc_type ); @@ -146,12 +191,14 @@ class ApiQueryRecentChanges extends ApiQueryBase { default: $vals['type'] = $type; } + /* Create a new entry in the result for the title. */ if ($this->fld_title) { ApiQueryBase :: addTitleInfo($vals, $title); if ($movedToTitle) ApiQueryBase :: addTitleInfo($vals, $movedToTitle, "new_"); } + /* Add ids, such as rcid, pageid, revid, and oldid to the change's info. */ if ($this->fld_ids) { $vals['rcid'] = intval($row->rc_id); $vals['pageid'] = intval($row->rc_cur_id); @@ -159,12 +206,14 @@ class ApiQueryRecentChanges extends ApiQueryBase { $vals['old_revid'] = intval( $row->rc_last_oldid ); } + /* Add user data and 'anon' flag, if use is anonymous. */ if ($this->fld_user) { $vals['user'] = $row->rc_user_text; if(!$row->rc_user) $vals['anon'] = ''; } + /* Add flags, such as new, minor, bot. */ if ($this->fld_flags) { if ($row->rc_bot) $vals['bot'] = ''; @@ -174,14 +223,17 @@ class ApiQueryRecentChanges extends ApiQueryBase { $vals['minor'] = ''; } + /* Add sizes of each revision. (Only available on 1.10+) */ if ($this->fld_sizes) { $vals['oldlen'] = intval($row->rc_old_len); $vals['newlen'] = intval($row->rc_new_len); } - + + /* Add the timestamp. */ if ($this->fld_timestamp) $vals['timestamp'] = wfTimestamp(TS_ISO_8601, $row->rc_timestamp); + /* Add edit summary / log summary. */ if ($this->fld_comment && !empty ($row->rc_comment)) { $vals['comment'] = $row->rc_comment; } -- 2.20.1