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          * @param SlotRecord[] $modifiedSlots
  77          * @param string[] $removedRoles
  78          */
  79         public function __construct( array $modifiedSlots = [], array $removedRoles = [] ) {
  80                 foreach ( $modifiedSlots as $slot ) {
  81                         $this->modifySlot( $slot );
  82                 }
  83
  84                 foreach ( $removedRoles as $role ) {
  85                         $this->removeSlot( $role );
  86                 }
  87         }
  88
  89         /**
  90          * Returns a list of modified slot roles, that is, roles modified by calling modifySlot(),
  91          * and not later removed by calling removeSlot().
  92          *
  93          * @return string[]
  94          */
  95         public function getModifiedRoles() {
  96                 return array_keys( $this->modifiedSlots );
  97         }
  98
  99         /**
 100          * Returns a list of removed slot roles, that is, roles removed by calling removeSlot(),
 101          * and not later re-introduced by calling modifySlot().
 102          *
 103          * @return string[]
 104          */
 105         public function getRemovedRoles() {
 106                 return array_keys( $this->removedRoles );
 107         }
 108
 109         /**
 110          * Returns a list of all slot roles that modified or removed.
 111          *
 112          * @return string[]
 113          */
 114         public function getTouchedRoles() {
 115                 return array_merge( $this->getModifiedRoles(), $this->getRemovedRoles() );
 116         }
 117
 118         /**
 119          * Sets the given slot to be modified.
 120          * If a slot with the same role is already present, it is replaced.
 121          *
 122          * The roles used with modifySlot() will be returned from getModifiedRoles(),
 123          * unless overwritten with removeSlot().
 124          *
 125          * @param SlotRecord $slot
 126          */
 127         public function modifySlot( SlotRecord $slot ) {
 128                 $role = $slot->getRole();
 129
 130                 // XXX: We should perhaps require this to be an unsaved slot!
 131                 unset( $this->removedRoles[$role] );
 132                 $this->modifiedSlots[$role] = $slot;
 133         }
 134
 135         /**
 136          * Sets the content for the slot with the given role to be modified.
 137          * If a slot with the same role is already present, it is replaced.
 138          *
 139          * @param string $role
 140          * @param Content $content
 141          */
 142         public function modifyContent( $role, Content $content ) {
 143                 $slot = SlotRecord::newUnsaved( $role, $content );
 144                 $this->modifySlot( $slot );
 145         }
 146
 147         /**
 148          * Remove the slot for the given role, discontinue the corresponding stream.
 149          *
 150          * The roles used with removeSlot() will be returned from getRemovedSlots(),
 151          * unless overwritten with modifySlot().
 152          *
 153          * @param string $role
 154          */
 155         public function removeSlot( $role ) {
 156                 unset( $this->modifiedSlots[$role] );
 157                 $this->removedRoles[$role] = true;
 158         }
 159
 160         /**
 161          * Returns the SlotRecord associated with the given role, if the slot with that role
 162          * was modified (and not again removed).
 163          *
 164          * @note If the SlotRecord returned by this method returns a non-inherited slot,
 165          *       the content of that slot may or may not already have PST applied. Methods
 166          *       that take a RevisionSlotsUpdate as a parameter should specify whether they
 167          *       expect PST to already have been applied to all slots. Inherited slots
 168          *       should never have PST applied again.
 169          *
 170          * @param string $role The role name of the desired slot
 171          *
 172          * @throws RevisionAccessException if the slot does not exist or was removed.
 173          * @return SlotRecord
 174          */
 175         public function getModifiedSlot( $role ) {
 176                 if ( isset( $this->modifiedSlots[$role] ) ) {
 177                         return $this->modifiedSlots[$role];
 178                 } else {
 179                         throw new RevisionAccessException( 'No such slot: ' . $role );
 180                 }
 181         }
 182
 183         /**
 184          * Returns whether getModifiedSlot() will return a SlotRecord for the given role.
 185          *
 186          * Will return true for the role names returned by getModifiedRoles(), false otherwise.
 187          *
 188          * @param string $role The role name of the desired slot
 189          *
 190          * @return bool
 191          */
 192         public function isModifiedSlot( $role ) {
 193                 return isset( $this->modifiedSlots[$role] );
 194         }
 195
 196         /**
 197          * Returns whether the given role is to be removed from the page.
 198          *
 199          * Will return true for the role names returned by getRemovedRoles(), false otherwise.
 200          *
 201          * @param string $role The role name of the desired slot
 202          *
 203          * @return bool
 204          */
 205         public function isRemovedSlot( $role ) {
 206                 return isset( $this->removedRoles[$role] );
 207         }
 208
 209         /**
 210          * Returns true if $other represents the same update - that is,
 211          * if all methods defined by RevisionSlotsUpdate when called on $this or $other
 212          * will yield the same result when called with the same parameters.
 213          *
 214          * SlotRecords for the same role are compared based on their model and content.
 215          *
 216          * @param RevisionSlotsUpdate $other
 217          * @return bool
 218          */
 219         public function hasSameUpdates( RevisionSlotsUpdate $other ) {
 220                 // NOTE: use != not !==, since the order of entries is not significant!
 221
 222                 if ( $this->getModifiedRoles() != $other->getModifiedRoles() ) {
 223                         return false;
 224                 }
 225
 226                 if ( $this->getRemovedRoles() != $other->getRemovedRoles() ) {
 227                         return false;
 228                 }
 229
 230                 foreach ( $this->getModifiedRoles() as $role ) {
 231                         $s = $this->getModifiedSlot( $role );
 232                         $t = $other->getModifiedSlot( $role );
 233
 234                         if ( !$s->hasSameContent( $t ) ) {
 235                                 return false;
 236                         }
 237                 }
 238
 239                 return true;
 240         }
 241
 242 }