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