includes/changes/CategoryMembershipChange.php

   1 <?php
   2 /**
   3  * Helper class for category membership changes
   4  *
   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.
   9  *
  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.
  14  *
  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
  19  *
  20  * @file
  21  * @author Kai Nissen
  22  * @author Adam Shorland
  23  * @since 1.26
  24  */
  25
  26 use Wikimedia\Assert\Assert;
  27
  28 class CategoryMembershipChange {
  29
  30         const CATEGORY_ADDITION = 1;
  31         const CATEGORY_REMOVAL = -1;
  32
  33         /**
  34          * @var string Current timestamp, set during CategoryMembershipChange::__construct()
  35          */
  36         private $timestamp;
  37
  38         /**
  39          * @var Title Title instance of the categorized page
  40          */
  41         private $pageTitle;
  42
  43         /**
  44          * @var Revision|null Latest Revision instance of the categorized page
  45          */
  46         private $revision;
  47
  48         /**
  49          * @var int
  50          * Number of pages this WikiPage is embedded by; set by CategoryMembershipChange::setRecursive()
  51          */
  52         private $numTemplateLinks = 0;
  53
  54         /**
  55          * @var callable|null
  56          */
  57         private $newForCategorizationCallback = null;
  58
  59         /**
  60          * @param Title $pageTitle Title instance of the categorized page
  61          * @param Revision $revision Latest Revision instance of the categorized page
  62          *
  63          * @throws MWException
  64          */
  65         public function __construct( Title $pageTitle, Revision $revision = null ) {
  66                 $this->pageTitle = $pageTitle;
  67                 $this->timestamp = wfTimestampNow();
  68                 $this->revision = $revision;
  69                 $this->newForCategorizationCallback = array( 'RecentChange', 'newForCategorization' );
  70         }
  71
  72         /**
  73          * Overrides the default new for categorization callback
  74          * This is intended for use while testing and will fail if MW_PHPUNIT_TEST is not defined.
  75          *
  76          * @param callable $callback
  77          * @see RecentChange::newForCategorization for callback signiture
  78          *
  79          * @throws MWException
  80          */
  81         public function overrideNewForCategorizationCallback( $callback ) {
  82                 if ( !defined( 'MW_PHPUNIT_TEST' ) ) {
  83                         throw new MWException( 'Cannot override newForCategorization callback in operation.' );
  84                 }
  85                 Assert::parameterType( 'callable', $callback, '$callback' );
  86                 $this->newForCategorizationCallback = $callback;
  87         }
  88
  89         /**
  90          * Determines the number of template links for recursive link updates
  91          */
  92         public function checkTemplateLinks() {
  93                 $this->numTemplateLinks = $this->pageTitle->getBacklinkCache()->getNumLinks( 'templatelinks' );
  94         }
  95
  96         /**
  97          * Create a recentchanges entry for category additions
  98          *
  99          * @param Title $categoryTitle
 100          */
 101         public function triggerCategoryAddedNotification( Title $categoryTitle ) {
 102                 $this->createRecentChangesEntry( $categoryTitle, self::CATEGORY_ADDITION );
 103         }
 104
 105         /**
 106          * Create a recentchanges entry for category removals
 107          *
 108          * @param Title $categoryTitle
 109          */
 110         public function triggerCategoryRemovedNotification( Title $categoryTitle ) {
 111                 $this->createRecentChangesEntry( $categoryTitle, self::CATEGORY_REMOVAL );
 112         }
 113
 114         /**
 115          * Create a recentchanges entry using RecentChange::notifyCategorization()
 116          *
 117          * @param Title $categoryTitle
 118          * @param int $type
 119          */
 120         private function createRecentChangesEntry( Title $categoryTitle, $type ) {
 121                 $this->notifyCategorization(
 122                         $this->timestamp,
 123                         $categoryTitle,
 124                         $this->getUser(),
 125                         $this->getChangeMessageText( $type, array(
 126                                 'prefixedText' => $this->pageTitle->getPrefixedText(),
 127                                 'numTemplateLinks' => $this->numTemplateLinks
 128                         ) ),
 129                         $this->pageTitle,
 130                         $this->getPreviousRevisionTimestamp(),
 131                         $this->revision
 132                 );
 133         }
 134
 135         /**
 136          * @param string $timestamp Timestamp of the recent change to occur in TS_MW format
 137          * @param Title $categoryTitle Title of the category a page is being added to or removed from
 138          * @param User $user User object of the user that made the change
 139          * @param string $comment Change summary
 140          * @param Title $pageTitle Title of the page that is being added or removed
 141          * @param string $lastTimestamp Parent revision timestamp of this change in TS_MW format
 142          * @param Revision|null $revision
 143          *
 144          * @throws MWException
 145          */
 146         private function notifyCategorization(
 147                 $timestamp,
 148                 Title $categoryTitle,
 149                 User $user = null,
 150                 $comment,
 151                 Title $pageTitle,
 152                 $lastTimestamp,
 153                 $revision
 154         ) {
 155                 $deleted = $revision ? $revision->getVisibility() & Revision::SUPPRESSED_USER : 0;
 156                 $newRevId = $revision ? $revision->getId() : 0;
 157
 158                 /**
 159                  * T109700 - Default bot flag to true when there is no corresponding RC entry
 160                  * This means all changes caused by parser functions & Lua on reparse are marked as bot
 161                  * Also in the case no RC entry could be found due to slave lag
 162                  */
 163                 $bot = 1;
 164                 $lastRevId = 0;
 165                 $ip = '';
 166
 167                 # If no revision is given, the change was probably triggered by parser functions
 168                 if ( $revision !== null ) {
 169                         // TODO if no RC try again from the master DB?
 170                         $correspondingRc = $this->revision->getRecentChange();
 171                         if ( $correspondingRc !== null ) {
 172                                 $bot = $correspondingRc->getAttribute( 'rc_bot' ) ?: 0;
 173                                 $ip = $correspondingRc->getAttribute( 'rc_ip' ) ?: '';
 174                                 $lastRevId = $correspondingRc->getAttribute( 'rc_last_oldid' ) ?: 0;
 175                         }
 176                 }
 177
 178                 $rc = call_user_func_array(
 179                         $this->newForCategorizationCallback,
 180                         array(
 181                                 $timestamp,
 182                                 $categoryTitle,
 183                                 $user,
 184                                 $comment,
 185                                 $pageTitle,
 186                                 $lastRevId,
 187                                 $newRevId,
 188                                 $lastTimestamp,
 189                                 $bot,
 190                                 $ip,
 191                                 $deleted
 192                         )
 193                 );
 194                 $rc->save();
 195         }
 196
 197         /**
 198          * Get the user associated with this change.
 199          *
 200          * If there is no revision associated with the change and thus no editing user
 201          * fallback to a default.
 202          *
 203          * False will be returned if the user name specified in the
 204          * 'autochange-username' message is invalid.
 205          *
 206          * @return User|bool
 207          */
 208         private function getUser() {
 209                 if ( $this->revision ) {
 210                         $userId = $this->revision->getUser( Revision::RAW );
 211                         if ( $userId === 0 ) {
 212                                 return User::newFromName( $this->revision->getUserText( Revision::RAW ), false );
 213                         } else {
 214                                 return User::newFromId( $userId );
 215                         }
 216                 }
 217
 218                 $username = wfMessage( 'autochange-username' )->inContentLanguage()->text();
 219                 $user = User::newFromName( $username );
 220                 # User::newFromName() can return false on a badly configured wiki.
 221                 if ( $user && !$user->isLoggedIn() ) {
 222                         $user->addToDatabase();
 223                 }
 224
 225                 return $user;
 226         }
 227
 228         /**
 229          * Returns the change message according to the type of category membership change
 230          *
 231          * The message keys created in this method may be one of:
 232          * - recentchanges-page-added-to-category
 233          * - recentchanges-page-added-to-category-bundled
 234          * - recentchanges-page-removed-from-category
 235          * - recentchanges-page-removed-from-category-bundled
 236          *
 237          * @param int $type may be CategoryMembershipChange::CATEGORY_ADDITION
 238          * or CategoryMembershipChange::CATEGORY_REMOVAL
 239          * @param array $params
 240          * - prefixedUrl: result of Title::->getPrefixedURL()
 241          *
 242          * @return string
 243          */
 244         private function getChangeMessageText( $type, array $params ) {
 245                 $array = array(
 246                         self::CATEGORY_ADDITION => 'recentchanges-page-added-to-category',
 247                         self::CATEGORY_REMOVAL => 'recentchanges-page-removed-from-category',
 248                 );
 249
 250                 $msgKey = $array[$type];
 251
 252                 if ( intval( $params['numTemplateLinks'] ) > 0 ) {
 253                         $msgKey .= '-bundled';
 254                 }
 255
 256                 return wfMessage( $msgKey, $params )->inContentLanguage()->text();
 257         }
 258
 259         /**
 260          * Returns the timestamp of the page's previous revision or null if the latest revision
 261          * does not refer to a parent revision
 262          *
 263          * @return null|string
 264          */
 265         private function getPreviousRevisionTimestamp() {
 266                 $previousRev = Revision::newFromId(
 267                                 $this->pageTitle->getPreviousRevisionID( $this->pageTitle->getLatestRevID() )
 268                         );
 269
 270                 return $previousRev ? $previousRev->getTimestamp() : null;
 271         }
 272
 273 }