includes/Storage/RevisionSlots.php

   1 <?php
   2 /**
   3  * Value object representing the set of slots belonging to a revision.
   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 LogicException;
  27 use Wikimedia\Assert\Assert;
  28
  29 /**
  30  * Value object representing the set of slots belonging to a revision.
  31  *
  32  * @since 1.31
  33  */
  34 class RevisionSlots {
  35
  36         /** @var SlotRecord[]|callable */
  37         protected $slots;
  38
  39         /**
  40          * @param SlotRecord[]|callable $slots SlotRecords,
  41          *        or a callback that returns such a structure.
  42          */
  43         public function __construct( $slots ) {
  44                 Assert::parameterType( 'array|callable', $slots, '$slots' );
  45
  46                 if ( is_callable( $slots ) ) {
  47                         $this->slots = $slots;
  48                 } else {
  49                         $this->setSlotsInternal( $slots );
  50                 }
  51         }
  52
  53         /**
  54          * @param SlotRecord[] $slots
  55          */
  56         private function setSlotsInternal( array $slots ) {
  57                 $this->slots = [];
  58
  59                 // re-key the slot array
  60                 foreach ( $slots as $slot ) {
  61                         $role = $slot->getRole();
  62                         $this->slots[$role] = $slot;
  63                 }
  64         }
  65
  66         /**
  67          * Implemented to defy serialization.
  68          *
  69          * @throws LogicException always
  70          */
  71         public function __sleep() {
  72                 throw new LogicException( __CLASS__ . ' is not serializable.' );
  73         }
  74
  75         /**
  76          * Returns the Content of the given slot.
  77          * Call getSlotNames() to get a list of available slots.
  78          *
  79          * Note that for mutable Content objects, each call to this method will return a
  80          * fresh clone.
  81          *
  82          * @param string $role The role name of the desired slot
  83          *
  84          * @throws RevisionAccessException if the slot does not exist or slot data
  85          *        could not be lazy-loaded.
  86          * @return Content
  87          */
  88         public function getContent( $role ) {
  89                 // Return a copy to be safe. Immutable content objects return $this from copy().
  90                 return $this->getSlot( $role )->getContent()->copy();
  91         }
  92
  93         /**
  94          * Returns the SlotRecord of the given slot.
  95          * Call getSlotNames() to get a list of available slots.
  96          *
  97          * @param string $role The role name of the desired slot
  98          *
  99          * @throws RevisionAccessException if the slot does not exist or slot data
 100          *        could not be lazy-loaded.
 101          * @return SlotRecord
 102          */
 103         public function getSlot( $role ) {
 104                 $slots = $this->getSlots();
 105
 106                 if ( isset( $slots[$role] ) ) {
 107                         return $slots[$role];
 108                 } else {
 109                         throw new RevisionAccessException( 'No such slot: ' . $role );
 110                 }
 111         }
 112
 113         /**
 114          * Returns the slot names (roles) of all slots present in this revision.
 115          * getContent() will succeed only for the names returned by this method.
 116          *
 117          * @return string[]
 118          */
 119         public function getSlotRoles() {
 120                 $slots = $this->getSlots();
 121                 return array_keys( $slots );
 122         }
 123
 124         /**
 125          * Computes the total nominal size of the revision's slots, in bogo-bytes.
 126          *
 127          * @warn This is potentially expensive! It may cause all slot's content to be loaded
 128          * and deserialized.
 129          *
 130          * @return int
 131          */
 132         public function computeSize() {
 133                 return array_reduce( $this->getSlots(), function ( $accu, SlotRecord $slot ) {
 134                         return $accu + $slot->getSize();
 135                 }, 0 );
 136         }
 137
 138         /**
 139          * Returns an associative array that maps role names to SlotRecords. Each SlotRecord
 140          * represents the content meta-data of a slot, together they define the content of
 141          * a revision.
 142          *
 143          * @note This may cause the content meta-data for the revision to be lazy-loaded.
 144          *
 145          * @return SlotRecord[] revision slot/content rows, keyed by slot role name.
 146          */
 147         public function getSlots() {
 148                 if ( is_callable( $this->slots ) ) {
 149                         $slots = call_user_func( $this->slots );
 150
 151                         Assert::postcondition(
 152                                 is_array( $slots ),
 153                                 'Slots info callback should return an array of objects'
 154                         );
 155
 156                         $this->setSlotsInternal( $slots );
 157                 }
 158
 159                 return $this->slots;
 160         }
 161
 162         /**
 163          * Computes the combined hash of the revisions's slots.
 164          *
 165          * @note For backwards compatibility, the combined hash of a single slot
 166          * is that slot's hash. For consistency, the combined hash of an empty set of slots
 167          * is the hash of the empty string.
 168          *
 169          * @warn This is potentially expensive! It may cause all slot's content to be loaded
 170          * and deserialized, then re-serialized and hashed.
 171          *
 172          * @return string
 173          */
 174         public function computeSha1() {
 175                 $slots = $this->getSlots();
 176                 ksort( $slots );
 177
 178                 if ( empty( $slots ) ) {
 179                         return SlotRecord::base36Sha1( '' );
 180                 }
 181
 182                 return array_reduce( $slots, function ( $accu, SlotRecord $slot ) {
 183                         return $accu === null
 184                                 ? $slot->getSha1()
 185                                 : SlotRecord::base36Sha1( $accu . $slot->getSha1() );
 186                 }, null );
 187         }
 188
 189 }