includes/Storage/RevisionSlotsUpdate.php

   1 <?php
   2 /**
   3  * Value object representing a modification of revision slots.
   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  */
  22
  23 namespace MediaWiki\Storage;
  24
  25 use Content;
  26 use MediaWiki\Revision\MutableRevisionSlots;
  27 use MediaWiki\Revision\RevisionAccessException;
  28 use MediaWiki\Revision\RevisionSlots;
  29 use MediaWiki\Revision\SlotRecord;
  30
  31 /**
  32  * Value object representing a modification of revision slots.
  33  *
  34  * @since 1.32
  35  */
  36 class RevisionSlotsUpdate {
  37
  38         /**
  39          * @var SlotRecord[] modified slots, using the slot role as the key.
  40          */
  41         private $modifiedSlots = [];
  42
  43         /**
  44          * @var bool[] removed roles, stored in the keys of the array.
  45          */
  46         private $removedRoles = [];
  47
  48         /**
  49          * Constructs a RevisionSlotsUpdate representing the update that turned $parentSlots
  50          * into $newSlots. If $parentSlots is not given, $newSlots is assumed to come from a
  51          * page's first revision.
  52          *
  53          * @param RevisionSlots $newSlots
  54          * @param RevisionSlots|null $parentSlots
  55          *
  56          * @return RevisionSlotsUpdate
  57          */
  58         public static function newFromRevisionSlots(
  59                 RevisionSlots $newSlots,
  60                 RevisionSlots $parentSlots = null
  61         ) {
  62                 $modified = $newSlots->getSlots();
  63                 $removed = [];
  64
  65                 if ( $parentSlots ) {
  66                         foreach ( $parentSlots->getSlots() as $role => $slot ) {
  67                                 if ( !isset( $modified[$role] ) ) {
  68                                         $removed[] = $role;
  69                                 } elseif ( $slot->hasSameContent( $modified[$role] ) ) {
  70                                         // Unset slots that had the same content in the parent revision from $modified.
  71                                         unset( $modified[$role] );
  72                                 }
  73                         }
  74                 }
  75
  76                 return new RevisionSlotsUpdate( $modified, $removed );
  77         }
  78
  79         /**
  80          * Constructs a RevisionSlotsUpdate representing the update of $parentSlots
  81          * when changing $newContent. If a slot has the same content in $newContent
  82          * as in $parentSlots, that slot is considered inherited and thus omitted from
  83          * the resulting RevisionSlotsUpdate.
  84          *
  85          * In contrast to newFromRevisionSlots(), slots in $parentSlots that are not present
  86          * in $newContent are not considered removed. They are instead assumed to be inherited.
  87          *
  88          * @param Content[] $newContent The new content, using slot roles as array keys.
  89          *
  90          * @return RevisionSlotsUpdate
  91          */
  92         public static function newFromContent( array $newContent, RevisionSlots $parentSlots = null ) {
  93                 $modified = [];
  94
  95                 foreach ( $newContent as $role => $content ) {
  96                         $slot = SlotRecord::newUnsaved( $role, $content );
  97
  98                         if ( $parentSlots
  99                                 && $parentSlots->hasSlot( $role )
 100                                 && $slot->hasSameContent( $parentSlots->getSlot( $role ) )
 101                         ) {
 102                                 // Skip slots that had the same content in the parent revision from $modified.
 103                                 continue;
 104                         }
 105
 106                         $modified[$role] = $slot;
 107                 }
 108
 109                 return new RevisionSlotsUpdate( $modified );
 110         }
 111
 112         /**
 113          * @param SlotRecord[] $modifiedSlots
 114          * @param string[] $removedRoles
 115          */
 116         public function __construct( array $modifiedSlots = [], array $removedRoles = [] ) {
 117                 foreach ( $modifiedSlots as $slot ) {
 118                         $this->modifySlot( $slot );
 119                 }
 120
 121                 foreach ( $removedRoles as $role ) {
 122                         $this->removeSlot( $role );
 123                 }
 124         }
 125
 126         /**
 127          * Returns a list of modified slot roles, that is, roles modified by calling modifySlot(),
 128          * and not later removed by calling removeSlot().
 129          *
 130          * Note that slots in modified roles may still be inherited slots. This is for instance
 131          * the case when the RevisionSlotsUpdate objects represents some kind of rollback
 132          * operation, in which slots that existed in an earlier revision are restored in
 133          * a new revision.
 134          *
 135          * @return string[]
 136          */
 137         public function getModifiedRoles() {
 138                 return array_keys( $this->modifiedSlots );
 139         }
 140
 141         /**
 142          * Returns a list of removed slot roles, that is, roles removed by calling removeSlot(),
 143          * and not later re-introduced by calling modifySlot().
 144          *
 145          * @return string[]
 146          */
 147         public function getRemovedRoles() {
 148                 return array_keys( $this->removedRoles );
 149         }
 150
 151         /**
 152          * Returns a list of all slot roles that modified or removed.
 153          *
 154          * @return string[]
 155          */
 156         public function getTouchedRoles() {
 157                 return array_merge( $this->getModifiedRoles(), $this->getRemovedRoles() );
 158         }
 159
 160         /**
 161          * Sets the given slot to be modified.
 162          * If a slot with the same role is already present, it is replaced.
 163          *
 164          * The roles used with modifySlot() will be returned from getModifiedRoles(),
 165          * unless overwritten with removeSlot().
 166          *
 167          * @param SlotRecord $slot
 168          */
 169         public function modifySlot( SlotRecord $slot ) {
 170                 $role = $slot->getRole();
 171
 172                 // XXX: We should perhaps require this to be an unsaved slot!
 173                 unset( $this->removedRoles[$role] );
 174                 $this->modifiedSlots[$role] = $slot;
 175         }
 176
 177         /**
 178          * Sets the content for the slot with the given role to be modified.
 179          * If a slot with the same role is already present, it is replaced.
 180          *
 181          * @param string $role
 182          * @param Content $content
 183          */
 184         public function modifyContent( $role, Content $content ) {
 185                 $slot = SlotRecord::newUnsaved( $role, $content );
 186                 $this->modifySlot( $slot );
 187         }
 188
 189         /**
 190          * Remove the slot for the given role, discontinue the corresponding stream.
 191          *
 192          * The roles used with removeSlot() will be returned from getRemovedSlots(),
 193          * unless overwritten with modifySlot().
 194          *
 195          * @param string $role
 196          */
 197         public function removeSlot( $role ) {
 198                 unset( $this->modifiedSlots[$role] );
 199                 $this->removedRoles[$role] = true;
 200         }
 201
 202         /**
 203          * Returns the SlotRecord associated with the given role, if the slot with that role
 204          * was modified (and not again removed).
 205          *
 206          * @note If the SlotRecord returned by this method returns a non-inherited slot,
 207          *       the content of that slot may or may not already have PST applied. Methods
 208          *       that take a RevisionSlotsUpdate as a parameter should specify whether they
 209          *       expect PST to already have been applied to all slots. Inherited slots
 210          *       should never have PST applied again.
 211          *
 212          * @param string $role The role name of the desired slot
 213          *
 214          * @throws RevisionAccessException if the slot does not exist or was removed.
 215          * @return SlotRecord
 216          */
 217         public function getModifiedSlot( $role ) {
 218                 if ( isset( $this->modifiedSlots[$role] ) ) {
 219                         return $this->modifiedSlots[$role];
 220                 } else {
 221                         throw new RevisionAccessException( 'No such slot: ' . $role );
 222                 }
 223         }
 224
 225         /**
 226          * Returns whether getModifiedSlot() will return a SlotRecord for the given role.
 227          *
 228          * Will return true for the role names returned by getModifiedRoles(), false otherwise.
 229          *
 230          * @param string $role The role name of the desired slot
 231          *
 232          * @return bool
 233          */
 234         public function isModifiedSlot( $role ) {
 235                 return isset( $this->modifiedSlots[$role] );
 236         }
 237
 238         /**
 239          * Returns whether the given role is to be removed from the page.
 240          *
 241          * Will return true for the role names returned by getRemovedRoles(), false otherwise.
 242          *
 243          * @param string $role The role name of the desired slot
 244          *
 245          * @return bool
 246          */
 247         public function isRemovedSlot( $role ) {
 248                 return isset( $this->removedRoles[$role] );
 249         }
 250
 251         /**
 252          * Returns true if $other represents the same update - that is,
 253          * if all methods defined by RevisionSlotsUpdate when called on $this or $other
 254          * will yield the same result when called with the same parameters.
 255          *
 256          * SlotRecords for the same role are compared based on their model and content.
 257          *
 258          * @param RevisionSlotsUpdate $other
 259          * @return bool
 260          */
 261         public function hasSameUpdates( RevisionSlotsUpdate $other ) {
 262                 // NOTE: use != not !==, since the order of entries is not significant!
 263
 264                 if ( $this->getModifiedRoles() != $other->getModifiedRoles() ) {
 265                         return false;
 266                 }
 267
 268                 if ( $this->getRemovedRoles() != $other->getRemovedRoles() ) {
 269                         return false;
 270                 }
 271
 272                 foreach ( $this->getModifiedRoles() as $role ) {
 273                         $s = $this->getModifiedSlot( $role );
 274                         $t = $other->getModifiedSlot( $role );
 275
 276                         if ( !$s->hasSameContent( $t ) ) {
 277                                 return false;
 278                         }
 279                 }
 280
 281                 return true;
 282         }
 283
 284         /**
 285          * Applies this update to the given MutableRevisionSlots, setting all modified slots,
 286          * and removing all removed roles.
 287          *
 288          * @param MutableRevisionSlots $slots
 289          */
 290         public function apply( MutableRevisionSlots $slots ) {
 291                 foreach ( $this->getModifiedRoles() as $role ) {
 292                         $slots->setSlot( $this->getModifiedSlot( $role ) );
 293                 }
 294
 295                 foreach ( $this->getRemovedRoles() as $role ) {
 296                         $slots->removeSlot( $role );
 297                 }
 298         }
 299
 300 }