Documentation and type hinting.
[lhc/web/wiklou.git] / includes / LogEventsList.php
index 37502f4..2d918ed 100644 (file)
@@ -1,30 +1,53 @@
 <?php
-# Copyright (C) 2004 Brion Vibber <brion@pobox.com>, 2008 Aaron Schulz
-# http://www.mediawiki.org/
-#
-# This program is free software; you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 2 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License along
-# with this program; if not, write to the Free Software Foundation, Inc.,
-# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
-# http://www.gnu.org/copyleft/gpl.html
+/**
+ * Contain classes to list log entries
+ *
+ * Copyright © 2004 Brion Vibber <brion@pobox.com>, 2008 Aaron Schulz
+ * http://www.mediawiki.org/
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ * http://www.gnu.org/copyleft/gpl.html
+ *
+ * @file
+ */
 
 class LogEventsList {
        const NO_ACTION_LINK = 1;
        const NO_EXTRA_USER_LINKS = 2;
 
+       /**
+        * @var Skin
+        */
        private $skin;
+
+       /**
+        * @var OutputPage
+        */
        private $out;
        public $flags;
 
+       /**
+        * @var Array
+        */
+       protected $message;
+
+       /**
+        * @var Array
+        */
+       protected $mDefaultQuery;
+
        public function __construct( $skin, $out, $flags = 0 ) {
                $this->skin = $skin;
                $this->out = $out;
@@ -41,7 +64,7 @@ class LogEventsList {
                if( !isset( $this->message ) ) {
                        $messages = array( 'revertmerge', 'protect_change', 'unblocklink', 'change-blocklink',
                                'revertmove', 'undeletelink', 'undeleteviewlink', 'revdel-restore', 'hist', 'diff',
-                               'pipe-separator' );
+                               'pipe-separator', 'revdel-restore-deleted', 'revdel-restore-visible' );
                        foreach( $messages as $msg ) {
                                $this->message[$msg] = wfMsgExt( $msg, array( 'escapenoentities' ) );
                        }
@@ -65,6 +88,7 @@ class LogEventsList {
 
        /**
         * Show options for the log list
+        *
         * @param $types string or Array
         * @param $user String
         * @param $page String
@@ -75,8 +99,7 @@ class LogEventsList {
         * @param $tagFilter: array?
         */
        public function showOptions( $types=array(), $user='', $page='', $pattern='', $year='', 
-               $month = '', $filter = null, $tagFilter='' )
-       {
+               $month = '', $filter = null, $tagFilter='' ) {
                global $wgScript, $wgMiserMode;
 
                $action = $wgScript;
@@ -88,8 +111,7 @@ class LogEventsList {
 
                $tagSelector = ChangeTags::buildTagFilterSelector( $tagFilter );
 
-               $html = '';
-               $html .= Xml::hidden( 'title', $special );
+               $html = Html::hidden( 'title', $special );
 
                // Basic selectors
                $html .= $this->getTypeMenu( $types ) . "\n";
@@ -107,7 +129,7 @@ class LogEventsList {
 
                // Tag filter
                if ($tagSelector) {
-                       $html .= Xml::tags( 'p', null, implode( '&nbsp;', $tagSelector ) );
+                       $html .= Xml::tags( 'p', null, implode( '&#160;', $tagSelector ) );
                }
 
                // Filter links
@@ -132,7 +154,7 @@ class LogEventsList {
         * @return String: Formatted HTML
         */
        private function getFilterLinks( $filter ) {
-               global $wgTitle, $wgLang;
+               global $wgLang;
                // show/hide links
                $messages = array( wfMsgHtml( 'show' ), wfMsgHtml( 'hide' ) );
                // Option value -> message mapping
@@ -148,7 +170,7 @@ class LogEventsList {
                        $query[$queryKey] = $hideVal;
 
                        $link = $this->skin->link(
-                               $wgTitle,
+                               $this->out->getTitle(),
                                $messages[$hideVal],
                                array(),
                                $query,
@@ -156,7 +178,7 @@ class LogEventsList {
                        );
 
                        $links[$type] = wfMsgHtml( "log-show-hide-{$type}", $link );
-                       $hiddens .= Xml::hidden( "hide_{$type}_log", $val ) . "\n";
+                       $hiddens .= Html::hidden( "hide_{$type}_log", $val ) . "\n";
                }
                // Build links
                return '<small>'.$wgLang->pipeList( $links ) . '</small>' . $hiddens;
@@ -199,6 +221,14 @@ class LogEventsList {
 
                // Note the query type
                $queryType = count($queryTypes) == 1 ? $queryTypes[0] : '';
+
+               // Always put "All public logs" on top
+               if ( isset( $typesByName[''] ) ) {
+                       $all = $typesByName[''];
+                       unset( $typesByName[''] );
+                       $typesByName = array( '' => $all ) + $typesByName;
+               }
+
                // Third pass generates sorted XHTML content
                foreach( $typesByName as $type => $text ) {
                        $selected = ($type == $queryType);
@@ -306,7 +336,6 @@ class LogEventsList {
        }
 
        private function logUserLinks( $row ) {
-               $userLinks = '';
                if( self::isDeleted( $row, LogPage::DELETED_USER ) ) {
                        $userLinks = '<span class="history-deleted">' .
                                wfMsgHtml( 'rev-deleted-user' ) . '</span>';
@@ -322,7 +351,6 @@ class LogEventsList {
        }
 
        private function logAction( $row, $title, $paramArray ) {
-               $action = '';
                if( self::isDeleted( $row, LogPage::DELETED_ACTION ) ) {
                        $action = '<span class="history-deleted">' .
                                wfMsgHtml( 'rev-deleted-event' ) . '</span>';
@@ -335,7 +363,6 @@ class LogEventsList {
        
        private function logComment( $row ) {
                global $wgContLang;
-               $comment = '';
                if( self::isDeleted( $row, LogPage::DELETED_COMMENT ) ) {
                        $comment = '<span class="history-deleted">' .
                                wfMsgHtml( 'rev-deleted-comment' ) . '</span>';
@@ -346,9 +373,17 @@ class LogEventsList {
                return $comment;
        }
 
-       // @TODO: split up!
+       /**
+        * @TODO: split up!
+        *
+        * @param  $row
+        * @param Title $title
+        * @param Array $paramArray
+        * @param  $comment
+        * @return String
+        */
        private function logActionLinks( $row, $title, $paramArray, &$comment ) {
-               global $wgUser, $wgLang;
+               global $wgUser;
                if( ( $this->flags & self::NO_ACTION_LINK ) // we don't want to see the action
                        || self::isDeleted( $row, LogPage::DELETED_ACTION ) ) // action is hidden
                {
@@ -389,18 +424,15 @@ class LogEventsList {
                } else if( self::typeAction( $row, array( 'block', 'suppress' ), array( 'block', 'reblock' ), 'block' ) ) {
                        $revert = '(' .
                                $this->skin->link(
-                                       SpecialPage::getTitleFor( 'Ipblocklist' ),
+                                       SpecialPage::getTitleFor( 'Unblock', $row->log_title ),
                                        $this->message['unblocklink'],
                                        array(),
-                                       array(
-                                               'action' => 'unblock',
-                                               'ip' => $row->log_title
-                                       ),
+                                       array(),
                                        'known'
                                ) .
                                $this->message['pipe-separator'] .
                                $this->skin->link(
-                                       SpecialPage::getTitleFor( 'Blockip', $row->log_title ),
+                                       SpecialPage::getTitleFor( 'Block', $row->log_title ),
                                        $this->message['change-blocklink'],
                                        array(),
                                        array(),
@@ -430,7 +462,7 @@ class LogEventsList {
                // Show unmerge link
                } else if( self::typeAction( $row, 'merge', 'merge', 'mergehistory' ) ) {
                        $revert = '(' . $this->skin->link(
-                               SpecialPage::getTitleFor( 'Mergehistory' ),
+                               SpecialPage::getTitleFor( 'MergeHistory' ),
                                $this->message['revertmerge'],
                                array(),
                                array(
@@ -442,63 +474,13 @@ class LogEventsList {
                        ) . ')';
                // If an edit was hidden from a page give a review link to the history
                } else if( self::typeAction( $row, array( 'delete', 'suppress' ), 'revision', 'deletedhistory' ) ) {
-                       if( count($paramArray) >= 2 ) {
-                               // Different revision types use different URL params...
-                               $key = $paramArray[0];
-                               // $paramArray[1] is a CSV of the IDs
-                               $Ids = explode( ',', $paramArray[1] );
-                               $query = $paramArray[1];
-                               $revert = array();
-                               // Diff link for single rev deletions
-                               if( count($Ids) == 1 ) {
-                                       // Live revision diffs...
-                                       if( in_array( $key, array( 'oldid', 'revision' ) ) ) {
-                                               $revert[] = $this->skin->link(
-                                                       $title,
-                                                       $this->message['diff'],
-                                                       array(),
-                                                       array(
-                                                               'diff' => intval( $Ids[0] ),
-                                                               'unhide' => 1
-                                                       ),
-                                                       array( 'known', 'noclasses' )
-                                               );
-                                       // Deleted revision diffs...
-                                       } else if( in_array( $key, array( 'artimestamp','archive' ) ) ) {
-                                               $revert[] = $this->skin->link(
-                                                       SpecialPage::getTitleFor( 'Undelete' ),
-                                                       $this->message['diff'], 
-                                                       array(),
-                                                       array(
-                                                               'target'    => $title->getPrefixedDBKey(),
-                                                               'diff'      => 'prev',
-                                                               'timestamp' => $Ids[0]
-                                                       ),
-                                                       array( 'known', 'noclasses' )
-                                               );
-                                       }
-                               }
-                               // View/modify link...
-                               $revert[] = $this->skin->link(
-                                       SpecialPage::getTitleFor( 'Revisiondelete' ),
-                                       $this->message['revdel-restore'],
-                                       array(),
-                                       array(
-                                               'target' => $title->getPrefixedText(),
-                                               'type' => $key,
-                                               'ids' => $query
-                                       ),
-                                       array( 'known', 'noclasses' )
-                               );
-                               // Pipe links
-                               $revert = wfMsg( 'parentheses', $wgLang->pipeList( $revert ) );
-                       }
+                       $revert = RevisionDeleter::getLogLinks( $title, $paramArray,
+                                                               $this->skin, $this->message );
                // Hidden log items, give review link
                } else if( self::typeAction( $row, array( 'delete', 'suppress' ), 'event', 'deletedhistory' ) ) {
                        if( count($paramArray) >= 1 ) {
                                $revdel = SpecialPage::getTitleFor( 'Revisiondelete' );
                                // $paramArray[1] is a CSV of the IDs
-                               $Ids = explode( ',', $paramArray[0] );
                                $query = $paramArray[0];
                                // Link to each hidden object ID, $paramArray[1] is the url param
                                $revert = '(' . $this->skin->link(
@@ -545,8 +527,7 @@ class LogEventsList {
        private function getShowHideLinks( $row ) {
                global $wgUser;
                if( ( $this->flags & self::NO_ACTION_LINK ) // we don't want to see the links
-                       || $row->log_type == 'suppress' ) // no one can hide items from the suppress log
-               {
+                       || $row->log_type == 'suppress' ) { // no one can hide items from the suppress log
                        return '';
                }
                $del = '';
@@ -577,7 +558,7 @@ class LogEventsList {
         * @param $type Mixed: string/array
         * @param $action Mixed: string/array
         * @param $right string
-        * @return bool
+        * @return Boolean
         */
        public static function typeAction( $row, $type, $action, $right='' ) {
                $match = is_array($type) ?
@@ -596,6 +577,7 @@ class LogEventsList {
        /**
         * Determine if the current user is allowed to view a particular
         * field of this log row, if it's marked as deleted.
+        *
         * @param $row Row
         * @param $field Integer
         * @return Boolean
@@ -603,10 +585,11 @@ class LogEventsList {
        public static function userCan( $row, $field ) {
                return self::userCanBitfield( $row->log_deleted, $field );
        }
-       
+
        /**
         * Determine if the current user is allowed to view a particular
         * field of this log row, if it's marked as deleted.
+        *
         * @param $bitfield Integer (current field)
         * @param $field Integer
         * @return Boolean
@@ -614,7 +597,7 @@ class LogEventsList {
        public static function userCanBitfield( $bitfield, $field ) {
                if( $bitfield & $field ) {
                        global $wgUser;
-                       $permission = '';
+
                        if ( $bitfield & LogPage::DELETED_RESTRICTED ) {
                                $permission = 'suppressrevision';
                        } else {
@@ -638,7 +621,8 @@ class LogEventsList {
 
        /**
         * Show log extract. Either with text and a box (set $msgKey) or without (don't set $msgKey)
-        * @param $out OutputPage or String-by-reference
+        *
+        * @param $out OutputPage|String-by-reference
         * @param $types String or Array
         * @param $page String The page title to show log entries for
         * @param $user String The user who made the log entries
@@ -747,9 +731,10 @@ class LogEventsList {
 
        /**
         * SQL clause to skip forbidden log types for this user
+        *
         * @param $db Database
         * @param $audience string, public/user
-        * @return mixed (string or false)
+        * @return Mixed: string or false
         */
        public static function getExcludeClause( $db, $audience = 'public' ) {
                global $wgLogRestrictions, $wgUser;
@@ -780,19 +765,20 @@ class LogPager extends ReverseChronologicalPager {
        public $mLogEventsList;
 
        /**
-        * constructor
+        * Constructor
+        *
         * @param $list LogEventsList
-        * @param $types String or Array log types to show
-        * @param $user String The user who made the log entries
-        * @param $title String The page title the log entries are for
-        * @param $pattern String Do a prefix search rather than an exact title match
-        * @param $conds Array Extra conditions for the query
-        * @param $year Integer The year to start from
-        * @param $month Integer The month to start from
+        * @param $types String or Array: log types to show
+        * @param $user String: the user who made the log entries
+        * @param $title String: the page title the log entries are for
+        * @param $pattern String: do a prefix search rather than an exact title match
+        * @param $conds Array: extra conditions for the query
+        * @param $year Integer: the year to start from
+        * @param $month Integer: the month to start from
+        * @param $tagFilter String: tag
         */
        public function __construct( $list, $types = array(), $user = '', $title = '', $pattern = '',
-               $conds = array(), $year = false, $month = false, $tagFilter = '' ) 
-       {
+               $conds = array(), $year = false, $month = false, $tagFilter = '' ) {
                parent::__construct();
                $this->mConds = $conds;
 
@@ -836,6 +822,7 @@ class LogPager extends ReverseChronologicalPager {
        /**
         * Set the log reader to return only entries of the given type.
         * Type restrictions enforced here
+        *
         * @param $types String or array: Log types ('upload', 'delete', etc);
         *   empty string means no restriction
         */
@@ -868,6 +855,7 @@ class LogPager extends ReverseChronologicalPager {
 
        /**
         * Set the log reader to return only entries by the given user.
+        *
         * @param $name String: (In)valid user name
         */
        private function limitUser( $name ) {
@@ -901,6 +889,7 @@ class LogPager extends ReverseChronologicalPager {
        /**
         * Set the log reader to return only entries affecting the given page.
         * (For the block and rights logs, this is a user page.)
+        *
         * @param $page String: Title name as text
         * @param $pattern String
         */
@@ -908,8 +897,9 @@ class LogPager extends ReverseChronologicalPager {
                global $wgMiserMode, $wgUser;
 
                $title = Title::newFromText( $page );
-               if( strlen( $page ) == 0 || !$title instanceof Title )
+               if( strlen( $page ) == 0 || !$title instanceof Title ) {
                        return false;
+               }
 
                $this->title = $title->getPrefixedText();
                $ns = $title->getNamespace();
@@ -944,17 +934,25 @@ class LogPager extends ReverseChronologicalPager {
        }
 
        public function getQueryInfo() {
-               global $wgOut;
                $tables = array( 'logging', 'user' );
                $this->mConds[] = 'user_id = log_user';
                $index = array();
                $options = array();
-               # Add log_search table if there are conditions on it
-               if( array_key_exists('ls_field',$this->mConds) ) {
+               # Add log_search table if there are conditions on it.
+               # This filters the results to only include log rows that have
+               # log_search records with the specified ls_field and ls_value values.
+               if( array_key_exists( 'ls_field', $this->mConds ) ) {
                        $tables[] = 'log_search';
                        $index['log_search'] = 'ls_field_val';
                        $index['logging'] = 'PRIMARY';
-                       $options[] = 'DISTINCT';
+                       if ( !$this->hasEqualsClause( 'ls_field' )
+                               || !$this->hasEqualsClause( 'ls_value' ) )
+                       {
+                               # Since (ls_field,ls_value,ls_logid) is unique, if the condition is
+                               # to match a specific (ls_field,ls_value) tuple, then there will be
+                               # no duplicate log rows. Otherwise, we need to remove the duplicates.
+                               $options[] = 'DISTINCT';
+                       }
                # Avoid usage of the wrong index by limiting
                # the choices of available indexes. This mainly
                # avoids site-breaking filesorts.
@@ -978,7 +976,7 @@ class LogPager extends ReverseChronologicalPager {
                        'conds'      => $this->mConds,
                        'options'    => $options,
                        'join_conds' => array(
-                               'user' => array( 'INNER JOIN', 'user_id=log_user' ),
+                               'user'           => array( 'INNER JOIN', 'user_id=log_user' ),
                                'log_search' => array( 'INNER JOIN', 'ls_log_id=log_id' )
                        )
                );
@@ -988,6 +986,14 @@ class LogPager extends ReverseChronologicalPager {
                return $info;
        }
 
+       // Checks if $this->mConds has $field matched to a *single* value
+       protected function hasEqualsClause( $field ) {
+               return (
+                       array_key_exists( $field, $this->mConds ) &&
+                       ( !is_array( $this->mConds[$field] ) || count( $this->mConds[$field] ) == 1 )
+               );
+       }
+
        function getIndexField() {
                return 'log_timestamp';
        }
@@ -997,7 +1003,7 @@ class LogPager extends ReverseChronologicalPager {
                # Do a link batch query
                if( $this->getNumRows() > 0 ) {
                        $lb = new LinkBatch;
-                       while( $row = $this->mResult->fetchObject() ) {
+                       foreach ( $this->mResult as $row ) {
                                $lb->add( $row->log_namespace, $row->log_title );
                                $lb->addObj( Title::makeTitleSafe( NS_USER, $row->user_name ) );
                                $lb->addObj( Title::makeTitleSafe( NS_USER_TALK, $row->user_name ) );
@@ -1055,6 +1061,7 @@ class LogPager extends ReverseChronologicalPager {
  */
 class LogReader {
        var $pager;
+
        /**
         * @param $request WebRequest: for internal use use a FauxRequest object to pass arbitrary parameters.
         */
@@ -1119,8 +1126,9 @@ class LogViewer {
         * Take over the whole output page in $wgOut with the log display.
         */
        public function show() {
+               global $wgOut;
                # Set title and add header
-               $this->list->showHeader( $pager->getType() );
+               $this->list->showHeader( $this->pager->getType() );
                # Show form options
                $this->list->showOptions( $this->pager->getType(), $this->pager->getUser(), $this->pager->getPage(),
                        $this->pager->getPattern(), $this->pager->getYear(), $this->pager->getMonth() );
@@ -1143,6 +1151,7 @@ class LogViewer {
         * Output just the list of entries given by the linked LogReader,
         * with extraneous UI elements. Use for displaying log fragments in
         * another page (eg at Special:Undelete)
+        *
         * @param $out OutputPage: where to send output
         */
        public function showList( &$out ) {