3 * Base code for "query" special pages.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
21 * @ingroup SpecialPage
25 * This is a class for doing query pages; since they're almost all the same,
26 * we factor out some of the functionality into a superclass, and let
27 * subclasses derive from it.
28 * @ingroup SpecialPage
30 abstract class QueryPage
extends SpecialPage
{
31 /** @var bool Whether or not we want plain listoutput rather than an ordered list */
32 protected $listoutput = false;
34 /** @var int The offset and limit in use, as passed to the query() function */
35 protected $offset = 0;
41 * The number of rows returned by the query. Reading this variable
42 * only makes sense in functions that are run after the query has been
43 * done, such as preprocessResults() and formatRow().
47 protected $cachedTimestamp = null;
50 * Whether to show prev/next links
52 protected $shownavigation = true;
55 * Get a list of query page classes and their associated special pages,
56 * for periodic updates.
58 * DO NOT CHANGE THIS LIST without testing that
59 * maintenance/updateSpecialPages.php still works.
62 public static function getPages() {
63 global $wgDisableCounters;
67 // QueryPage subclass, Special page name
69 array( 'AncientPagesPage', 'Ancientpages' ),
70 array( 'BrokenRedirectsPage', 'BrokenRedirects' ),
71 array( 'DeadendPagesPage', 'Deadendpages' ),
72 array( 'DoubleRedirectsPage', 'DoubleRedirects' ),
73 array( 'FileDuplicateSearchPage', 'FileDuplicateSearch' ),
74 array( 'ListDuplicatedFilesPage', 'ListDuplicatedFiles'),
75 array( 'LinkSearchPage', 'LinkSearch' ),
76 array( 'ListredirectsPage', 'Listredirects' ),
77 array( 'LonelyPagesPage', 'Lonelypages' ),
78 array( 'LongPagesPage', 'Longpages' ),
79 array( 'MIMEsearchPage', 'MIMEsearch' ),
80 array( 'MostcategoriesPage', 'Mostcategories' ),
81 array( 'MostimagesPage', 'Mostimages' ),
82 array( 'MostinterwikisPage', 'Mostinterwikis' ),
83 array( 'MostlinkedCategoriesPage', 'Mostlinkedcategories' ),
84 array( 'MostlinkedtemplatesPage', 'Mostlinkedtemplates' ),
85 array( 'MostlinkedPage', 'Mostlinked' ),
86 array( 'MostrevisionsPage', 'Mostrevisions' ),
87 array( 'FewestrevisionsPage', 'Fewestrevisions' ),
88 array( 'ShortPagesPage', 'Shortpages' ),
89 array( 'UncategorizedCategoriesPage', 'Uncategorizedcategories' ),
90 array( 'UncategorizedPagesPage', 'Uncategorizedpages' ),
91 array( 'UncategorizedImagesPage', 'Uncategorizedimages' ),
92 array( 'UncategorizedTemplatesPage', 'Uncategorizedtemplates' ),
93 array( 'UnusedCategoriesPage', 'Unusedcategories' ),
94 array( 'UnusedimagesPage', 'Unusedimages' ),
95 array( 'WantedCategoriesPage', 'Wantedcategories' ),
96 array( 'WantedFilesPage', 'Wantedfiles' ),
97 array( 'WantedPagesPage', 'Wantedpages' ),
98 array( 'WantedTemplatesPage', 'Wantedtemplates' ),
99 array( 'UnwatchedPagesPage', 'Unwatchedpages' ),
100 array( 'UnusedtemplatesPage', 'Unusedtemplates' ),
101 array( 'WithoutInterwikiPage', 'Withoutinterwiki' ),
103 wfRunHooks( 'wgQueryPages', array( &$qp ) );
105 if ( !$wgDisableCounters ) {
106 $qp[] = array( 'PopularPagesPage', 'Popularpages' );
114 * A mutator for $this->listoutput;
118 function setListoutput( $bool ) {
119 $this->listoutput
= $bool;
123 * Subclasses return an SQL query here, formatted as an array with the
125 * tables => Table(s) for passing to Database::select()
126 * fields => Field(s) for passing to Database::select(), may be *
127 * conds => WHERE conditions
129 * join_conds => JOIN conditions
131 * Note that the query itself should return the following three columns:
132 * 'namespace', 'title', and 'value'. 'value' is used for sorting.
134 * These may be stored in the querycache table for expensive queries,
135 * and that cached data will be returned sometimes, so the presence of
136 * extra fields can't be relied upon. The cached 'value' column will be
137 * an integer; non-numeric values are useful only for sorting the
138 * initial query (except if they're timestamps, see usesTimestamps()).
140 * Don't include an ORDER or LIMIT clause, they will be added.
142 * If this function is not overridden or returns something other than
143 * an array, getSQL() will be used instead. This is for backwards
144 * compatibility only and is strongly deprecated.
148 function getQueryInfo() {
153 * For back-compat, subclasses may return a raw SQL query here, as a string.
154 * This is strongly deprecated; getQueryInfo() should be overridden instead.
155 * @throws MWException
159 /* Implement getQueryInfo() instead */
160 throw new MWException( "Bug in a QueryPage: doesn't implement getQueryInfo() nor "
161 . "getQuery() properly" );
165 * Subclasses return an array of fields to order by here. Don't append
166 * DESC to the field names, that'll be done automatically if
167 * sortDescending() returns true.
171 function getOrderFields() {
172 return array( 'value' );
176 * Does this query return timestamps rather than integers in its
177 * 'value' field? If true, this class will convert 'value' to a
178 * UNIX timestamp for caching.
179 * NOTE: formatRow() may get timestamps in TS_MW (mysql), TS_DB (pgsql)
180 * or TS_UNIX (querycache) format, so be sure to always run them
181 * through wfTimestamp()
185 function usesTimestamps() {
190 * Override to sort by increasing values
194 function sortDescending() {
199 * Is this query expensive (for some definition of expensive)? Then we
200 * don't let it run in miser mode. $wgDisableQueryPages causes all query
201 * pages to be declared expensive. Some query pages are always expensive.
205 function isExpensive() {
206 global $wgDisableQueryPages;
207 return $wgDisableQueryPages;
211 * Is the output of this query cacheable? Non-cacheable expensive pages
212 * will be disabled in miser mode and will not have their results written
213 * to the querycache table.
217 public function isCacheable() {
222 * Whether or not the output of the page in question is retrieved from
223 * the database cache.
227 function isCached() {
230 return $this->isExpensive() && $wgMiserMode;
234 * Sometime we don't want to build rss / atom feeds.
238 function isSyndicated() {
243 * Formats the results of the query for display. The skin is the current
244 * skin; you can use it for making links. The result is a single row of
245 * result data. You should be able to grab SQL results off of it.
246 * If the function returns false, the line output will be skipped.
248 * @param object $result Result row
249 * @return string|bool String or false to skip
251 abstract function formatResult( $skin, $result );
254 * The content returned by this function will be output before any result
258 function getPageHeader() {
263 * If using extra form wheely-dealies, return a set of parameters here
264 * as an associative array. They will be encoded and added to the paging
265 * links (prev/next/lengths).
269 function linkParameters() {
274 * Some special pages (for example SpecialListusers) might not return the
275 * current object formatted, but return the previous one instead.
276 * Setting this to return true will ensure formatResult() is called
277 * one more time to make sure that the very last result is formatted
281 function tryLastResult() {
286 * Clear the cache and save new results
288 * @param int|bool $limit Limit for SQL statement
289 * @param bool $ignoreErrors Whether to ignore database errors
290 * @throws DBError|Exception
293 function recache( $limit, $ignoreErrors = true ) {
294 if ( !$this->isCacheable() ) {
298 $fname = get_class( $this ) . '::recache';
299 $dbw = wfGetDB( DB_MASTER
);
306 $res = $this->reallyDoQuery( $limit, false );
309 $num = $res->numRows();
312 foreach ( $res as $row ) {
313 if ( isset( $row->value
) ) {
314 if ( $this->usesTimestamps() ) {
315 $value = wfTimestamp( TS_UNIX
,
318 $value = intval( $row->value
); // @bug 14414
324 $vals[] = array( 'qc_type' => $this->getName(),
325 'qc_namespace' => $row->namespace,
326 'qc_title' => $row->title
,
327 'qc_value' => $value );
330 $dbw->begin( __METHOD__
);
331 # Clear out any old cached data
332 $dbw->delete( 'querycache', array( 'qc_type' => $this->getName() ), $fname );
333 # Save results into the querycache table on the master
334 if ( count( $vals ) ) {
335 $dbw->insert( 'querycache', $vals, __METHOD__
);
337 # Update the querycache_info record for the page
338 $dbw->delete( 'querycache_info', array( 'qci_type' => $this->getName() ), $fname );
339 $dbw->insert( 'querycache_info',
340 array( 'qci_type' => $this->getName(), 'qci_timestamp' => $dbw->timestamp() ),
342 $dbw->commit( __METHOD__
);
344 } catch ( DBError
$e ) {
345 if ( !$ignoreErrors ) {
346 throw $e; // report query error
348 $num = false; // set result to false to indicate error
355 * Get a DB connection to be used for slow recache queries
356 * @return DatabaseBase
358 function getRecacheDB() {
359 return wfGetDB( DB_SLAVE
, array( $this->getName(), 'QueryPage::recache', 'vslow' ) );
363 * Run the query and return the result
364 * @param int|bool $limit Numerical limit or false for no limit
365 * @param int|bool $offset Numerical offset or false for no offset
366 * @return ResultWrapper
369 function reallyDoQuery( $limit, $offset = false ) {
370 $fname = get_class( $this ) . "::reallyDoQuery";
371 $dbr = $this->getRecacheDB();
372 $query = $this->getQueryInfo();
373 $order = $this->getOrderFields();
375 if ( $this->sortDescending() ) {
376 foreach ( $order as &$field ) {
381 if ( is_array( $query ) ) {
382 $tables = isset( $query['tables'] ) ?
(array)$query['tables'] : array();
383 $fields = isset( $query['fields'] ) ?
(array)$query['fields'] : array();
384 $conds = isset( $query['conds'] ) ?
(array)$query['conds'] : array();
385 $options = isset( $query['options'] ) ?
(array)$query['options'] : array();
386 $join_conds = isset( $query['join_conds'] ) ?
(array)$query['join_conds'] : array();
388 if ( count( $order ) ) {
389 $options['ORDER BY'] = $order;
392 if ( $limit !== false ) {
393 $options['LIMIT'] = intval( $limit );
396 if ( $offset !== false ) {
397 $options['OFFSET'] = intval( $offset );
400 $res = $dbr->select( $tables, $fields, $conds, $fname,
401 $options, $join_conds
404 // Old-fashioned raw SQL style, deprecated
405 $sql = $this->getSQL();
406 $sql .= ' ORDER BY ' . implode( ', ', $order );
407 $sql = $dbr->limitResult( $sql, $limit, $offset );
408 $res = $dbr->query( $sql, $fname );
411 return $dbr->resultObject( $res );
415 * Somewhat deprecated, you probably want to be using execute()
416 * @param int|bool $offset
417 * @param int|bool $limit
418 * @return ResultWrapper
420 function doQuery( $offset = false, $limit = false ) {
421 if ( $this->isCached() && $this->isCacheable() ) {
422 return $this->fetchFromCache( $limit, $offset );
424 return $this->reallyDoQuery( $limit, $offset );
429 * Fetch the query results from the query cache
430 * @param int|bool $limit Numerical limit or false for no limit
431 * @param int|bool $offset Numerical offset or false for no offset
432 * @return ResultWrapper
435 function fetchFromCache( $limit, $offset = false ) {
436 $dbr = wfGetDB( DB_SLAVE
);
438 if ( $limit !== false ) {
439 $options['LIMIT'] = intval( $limit );
441 if ( $offset !== false ) {
442 $options['OFFSET'] = intval( $offset );
444 if ( $this->sortDescending() ) {
445 $options['ORDER BY'] = 'qc_value DESC';
447 $options['ORDER BY'] = 'qc_value ASC';
449 $res = $dbr->select( 'querycache', array( 'qc_type',
450 'namespace' => 'qc_namespace',
451 'title' => 'qc_title',
452 'value' => 'qc_value' ),
453 array( 'qc_type' => $this->getName() ),
456 return $dbr->resultObject( $res );
459 public function getCachedTimestamp() {
460 if ( is_null( $this->cachedTimestamp
) ) {
461 $dbr = wfGetDB( DB_SLAVE
);
462 $fname = get_class( $this ) . '::getCachedTimestamp';
463 $this->cachedTimestamp
= $dbr->selectField( 'querycache_info', 'qci_timestamp',
464 array( 'qci_type' => $this->getName() ), $fname );
466 return $this->cachedTimestamp
;
470 * This is the actual workhorse. It does everything needed to make a
471 * real, honest-to-gosh query page.
474 function execute( $par ) {
475 global $wgQueryCacheLimit, $wgDisableQueryPageUpdate;
477 $user = $this->getUser();
478 if ( !$this->userCanExecute( $user ) ) {
479 $this->displayRestrictionError();
484 $this->outputHeader();
486 $out = $this->getOutput();
488 if ( $this->isCached() && !$this->isCacheable() ) {
489 $out->addWikiMsg( 'querypage-disabled' );
493 $out->setSyndicated( $this->isSyndicated() );
495 if ( $this->limit
== 0 && $this->offset
== 0 ) {
496 list( $this->limit
, $this->offset
) = $this->getRequest()->getLimitOffset();
499 // @todo Use doQuery()
500 if ( !$this->isCached() ) {
501 # select one extra row for navigation
502 $res = $this->reallyDoQuery( $this->limit +
1, $this->offset
);
504 # Get the cached result, select one extra row for navigation
505 $res = $this->fetchFromCache( $this->limit +
1, $this->offset
);
506 if ( !$this->listoutput
) {
508 # Fetch the timestamp of this update
509 $ts = $this->getCachedTimestamp();
510 $lang = $this->getLanguage();
511 $maxResults = $lang->formatNum( $wgQueryCacheLimit );
514 $updated = $lang->userTimeAndDate( $ts, $user );
515 $updateddate = $lang->userDate( $ts, $user );
516 $updatedtime = $lang->userTime( $ts, $user );
517 $out->addMeta( 'Data-Cache-Time', $ts );
518 $out->addJsConfigVars( 'dataCacheTime', $ts );
519 $out->addWikiMsg( 'perfcachedts', $updated, $updateddate, $updatedtime, $maxResults );
521 $out->addWikiMsg( 'perfcached', $maxResults );
524 # If updates on this page have been disabled, let the user know
525 # that the data set won't be refreshed for now
526 if ( is_array( $wgDisableQueryPageUpdate )
527 && in_array( $this->getName(), $wgDisableQueryPageUpdate )
530 "<div class=\"mw-querypage-no-updates\">\n$1\n</div>",
531 'querypage-no-updates'
537 $this->numRows
= $res->numRows();
539 $dbr = wfGetDB( DB_SLAVE
);
540 $this->preprocessResults( $dbr, $res );
542 $out->addHTML( Xml
::openElement( 'div', array( 'class' => 'mw-spcontent' ) ) );
544 # Top header and navigation
545 if ( $this->shownavigation
) {
546 $out->addHTML( $this->getPageHeader() );
547 if ( $this->numRows
> 0 ) {
548 $out->addHTML( $this->msg( 'showingresultsinrange' )->numParams(
549 min( $this->numRows
, $this->limit
), # do not show the one extra row, if exist
550 $this->offset +
1, ( min( $this->numRows
, $this->limit
) +
$this->offset
) )->parseAsBlock() );
551 # Disable the "next" link when we reach the end
552 $paging = $this->getLanguage()->viewPrevNext( $this->getPageTitle( $par ), $this->offset
,
553 $this->limit
, $this->linkParameters(), ( $this->numRows
<= $this->limit
) );
554 $out->addHTML( '<p>' . $paging . '</p>' );
556 # No results to show, so don't bother with "showing X of Y" etc.
557 # -- just let the user know and give up now
558 $out->addWikiMsg( 'specialpage-empty' );
559 $out->addHTML( Xml
::closeElement( 'div' ) );
564 # The actual results; specialist subclasses will want to handle this
565 # with more than a straight list, so we hand them the info, plus
566 # an OutputPage, and let them get on with it
567 $this->outputResults( $out,
569 $dbr, # Should use a ResultWrapper for this
571 min( $this->numRows
, $this->limit
), # do not format the one extra row, if exist
574 # Repeat the paging links at the bottom
575 if ( $this->shownavigation
) {
576 $out->addHTML( '<p>' . $paging . '</p>' );
579 $out->addHTML( Xml
::closeElement( 'div' ) );
583 * Format and output report results using the given information plus
586 * @param OutputPage $out OutputPage to print to
587 * @param Skin $skin User skin to use
588 * @param DatabaseBase $dbr Database (read) connection to use
589 * @param ResultWrapper $res Result pointer
590 * @param int $num Number of available result rows
591 * @param int $offset Paging offset
593 protected function outputResults( $out, $skin, $dbr, $res, $num, $offset ) {
598 if ( !$this->listoutput
) {
599 $html[] = $this->openList( $offset );
602 # $res might contain the whole 1,000 rows, so we read up to
603 # $num [should update this to use a Pager]
604 // @codingStandardsIgnoreStart Generic.CodeAnalysis.ForLoopWithTestFunctionCall.NotAllowed
605 for ( $i = 0; $i < $num && $row = $res->fetchObject(); $i++
) {
606 // @codingStandardsIgnoreEnd
607 $line = $this->formatResult( $skin, $row );
609 $attr = ( isset( $row->usepatrol
) && $row->usepatrol
&& $row->patrolled
== 0 )
610 ?
' class="not-patrolled"'
612 $html[] = $this->listoutput
614 : "<li{$attr}>{$line}</li>\n";
618 # Flush the final result
619 if ( $this->tryLastResult() ) {
621 $line = $this->formatResult( $skin, $row );
623 $attr = ( isset( $row->usepatrol
) && $row->usepatrol
&& $row->patrolled
== 0 )
624 ?
' class="not-patrolled"'
626 $html[] = $this->listoutput
628 : "<li{$attr}>{$line}</li>\n";
632 if ( !$this->listoutput
) {
633 $html[] = $this->closeList();
636 $html = $this->listoutput
637 ?
$wgContLang->listToText( $html )
638 : implode( '', $html );
640 $out->addHTML( $html );
648 function openList( $offset ) {
649 return "\n<ol start='" . ( $offset +
1 ) . "' class='special'>\n";
655 function closeList() {
660 * Do any necessary preprocessing of the result object.
661 * @param DatabaseBase $db
662 * @param ResultWrapper $res
664 function preprocessResults( $db, $res ) {
668 * Similar to above, but packaging in a syndicated feed instead of a web page
669 * @param string $class
673 function doFeed( $class = '', $limit = 50 ) {
674 global $wgFeed, $wgFeedClasses, $wgFeedLimit;
677 $this->getOutput()->addWikiMsg( 'feed-unavailable' );
681 $limit = min( $limit, $wgFeedLimit );
683 if ( isset( $wgFeedClasses[$class] ) ) {
684 /** @var RSSFeed|AtomFeed $feed */
685 $feed = new $wgFeedClasses[$class](
691 $res = $this->reallyDoQuery( $limit, 0 );
692 foreach ( $res as $obj ) {
693 $item = $this->feedResult( $obj );
695 $feed->outItem( $item );
707 * Override for custom handling. If the titles/links are ok, just do
710 * @return FeedItem|null
712 function feedResult( $row ) {
713 if ( !isset( $row->title
) ) {
716 $title = Title
::makeTitle( intval( $row->namespace ), $row->title
);
718 $date = isset( $row->timestamp
) ?
$row->timestamp
: '';
721 $talkpage = $title->getTalkPage();
722 $comments = $talkpage->getFullURL();
726 $title->getPrefixedText(),
727 $this->feedItemDesc( $row ),
728 $title->getFullURL(),
730 $this->feedItemAuthor( $row ),
737 function feedItemDesc( $row ) {
738 return isset( $row->comment
) ?
htmlspecialchars( $row->comment
) : '';
741 function feedItemAuthor( $row ) {
742 return isset( $row->user_text
) ?
$row->user_text
: '';
745 function feedTitle() {
746 global $wgLanguageCode, $wgSitename;
747 $desc = $this->getDescription();
748 return "$wgSitename - $desc [$wgLanguageCode]";
751 function feedDesc() {
752 return $this->msg( 'tagline' )->text();
756 return $this->getPageTitle()->getFullURL();