includes/Storage/RevisionSlotsUpdate.php

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