includes/site/SiteList.php

   1 <?php
   2
   3 /**
   4  * Collection of Site objects.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @since 1.21
  22  *
  23  * @file
  24  * @ingroup Site
  25  *
  26  * @license GNU GPL v2+
  27  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  28  */
  29 class SiteList extends GenericArrayObject {
  30         /**
  31          * Internal site identifiers pointing to their sites offset value.
  32          *
  33          * @since 1.21
  34          *
  35          * @var array Array of integer
  36          */
  37         protected $byInternalId = [];
  38
  39         /**
  40          * Global site identifiers pointing to their sites offset value.
  41          *
  42          * @since 1.21
  43          *
  44          * @var array Array of string
  45          */
  46         protected $byGlobalId = [];
  47
  48         /**
  49          * Navigational site identifiers alias inter-language prefixes
  50          * pointing to their sites offset value.
  51          *
  52          * @since 1.23
  53          *
  54          * @var array Array of string
  55          */
  56         protected $byNavigationId = [];
  57
  58         /**
  59          * @see GenericArrayObject::getObjectType
  60          *
  61          * @since 1.21
  62          *
  63          * @return string
  64          */
  65         public function getObjectType() {
  66                 return 'Site';
  67         }
  68
  69         /**
  70          * @see GenericArrayObject::preSetElement
  71          *
  72          * @since 1.21
  73          *
  74          * @param int|string $index
  75          * @param Site $site
  76          *
  77          * @return bool
  78          */
  79         protected function preSetElement( $index, $site ) {
  80                 if ( $this->hasSite( $site->getGlobalId() ) ) {
  81                         $this->removeSite( $site->getGlobalId() );
  82                 }
  83
  84                 $this->byGlobalId[$site->getGlobalId()] = $index;
  85                 $this->byInternalId[$site->getInternalId()] = $index;
  86
  87                 $ids = $site->getNavigationIds();
  88                 foreach ( $ids as $navId ) {
  89                         $this->byNavigationId[$navId] = $index;
  90                 }
  91
  92                 return true;
  93         }
  94
  95         /**
  96          * @see ArrayObject::offsetUnset()
  97          *
  98          * @since 1.21
  99          *
 100          * @param mixed $index
 101          */
 102         public function offsetUnset( $index ) {
 103                 if ( $this->offsetExists( $index ) ) {
 104                         /**
 105                          * @var Site $site
 106                          */
 107                         $site = $this->offsetGet( $index );
 108
 109                         unset( $this->byGlobalId[$site->getGlobalId()] );
 110                         unset( $this->byInternalId[$site->getInternalId()] );
 111
 112                         $ids = $site->getNavigationIds();
 113                         foreach ( $ids as $navId ) {
 114                                 unset( $this->byNavigationId[$navId] );
 115                         }
 116                 }
 117
 118                 parent::offsetUnset( $index );
 119         }
 120
 121         /**
 122          * Returns all the global site identifiers.
 123          * Optionally only those belonging to the specified group.
 124          *
 125          * @since 1.21
 126          *
 127          * @return array
 128          */
 129         public function getGlobalIdentifiers() {
 130                 return array_keys( $this->byGlobalId );
 131         }
 132
 133         /**
 134          * Returns if the list contains the site with the provided global site identifier.
 135          *
 136          * @param string $globalSiteId
 137          *
 138          * @return bool
 139          */
 140         public function hasSite( $globalSiteId ) {
 141                 return array_key_exists( $globalSiteId, $this->byGlobalId );
 142         }
 143
 144         /**
 145          * Returns the Site with the provided global site identifier.
 146          * The site needs to exist, so if not sure, call hasGlobalId first.
 147          *
 148          * @since 1.21
 149          *
 150          * @param string $globalSiteId
 151          *
 152          * @return Site
 153          */
 154         public function getSite( $globalSiteId ) {
 155                 return $this->offsetGet( $this->byGlobalId[$globalSiteId] );
 156         }
 157
 158         /**
 159          * Removes the site with the specified global site identifier.
 160          * The site needs to exist, so if not sure, call hasGlobalId first.
 161          *
 162          * @since 1.21
 163          *
 164          * @param string $globalSiteId
 165          */
 166         public function removeSite( $globalSiteId ) {
 167                 $this->offsetUnset( $this->byGlobalId[$globalSiteId] );
 168         }
 169
 170         /**
 171          * Returns if the list contains no sites.
 172          *
 173          * @since 1.21
 174          *
 175          * @return bool
 176          */
 177         public function isEmpty() {
 178                 return $this->byGlobalId === [];
 179         }
 180
 181         /**
 182          * Returns if the list contains the site with the provided site id.
 183          *
 184          * @param int $id
 185          *
 186          * @return bool
 187          */
 188         public function hasInternalId( $id ) {
 189                 return array_key_exists( $id, $this->byInternalId );
 190         }
 191
 192         /**
 193          * Returns the Site with the provided site id.
 194          * The site needs to exist, so if not sure, call has first.
 195          *
 196          * @since 1.21
 197          *
 198          * @param int $id
 199          *
 200          * @return Site
 201          */
 202         public function getSiteByInternalId( $id ) {
 203                 return $this->offsetGet( $this->byInternalId[$id] );
 204         }
 205
 206         /**
 207          * Removes the site with the specified site id.
 208          * The site needs to exist, so if not sure, call has first.
 209          *
 210          * @since 1.21
 211          *
 212          * @param int $id
 213          */
 214         public function removeSiteByInternalId( $id ) {
 215                 $this->offsetUnset( $this->byInternalId[$id] );
 216         }
 217
 218         /**
 219          * Returns if the list contains the site with the provided navigational site id.
 220          *
 221          * @param string $id
 222          *
 223          * @return bool
 224          */
 225         public function hasNavigationId( $id ) {
 226                 return array_key_exists( $id, $this->byNavigationId );
 227         }
 228
 229         /**
 230          * Returns the Site with the provided navigational site id.
 231          * The site needs to exist, so if not sure, call has first.
 232          *
 233          * @since 1.23
 234          *
 235          * @param string $id
 236          *
 237          * @return Site
 238          */
 239         public function getSiteByNavigationId( $id ) {
 240                 return $this->offsetGet( $this->byNavigationId[$id] );
 241         }
 242
 243         /**
 244          * Removes the site with the specified navigational site id.
 245          * The site needs to exist, so if not sure, call has first.
 246          *
 247          * @since 1.23
 248          *
 249          * @param string $id
 250          */
 251         public function removeSiteByNavigationId( $id ) {
 252                 $this->offsetUnset( $this->byNavigationId[$id] );
 253         }
 254
 255         /**
 256          * Sets a site in the list. If the site was not there,
 257          * it will be added. If it was, it will be updated.
 258          *
 259          * @since 1.21
 260          *
 261          * @param Site $site
 262          */
 263         public function setSite( Site $site ) {
 264                 $this[] = $site;
 265         }
 266
 267         /**
 268          * Returns the sites that are in the provided group.
 269          *
 270          * @since 1.21
 271          *
 272          * @param string $groupName
 273          *
 274          * @return SiteList
 275          */
 276         public function getGroup( $groupName ) {
 277                 $group = new self();
 278
 279                 /**
 280                  * @var Site $site
 281                  */
 282                 foreach ( $this as $site ) {
 283                         if ( $site->getGroup() === $groupName ) {
 284                                 $group[] = $site;
 285                         }
 286                 }
 287
 288                 return $group;
 289         }
 290
 291         /**
 292          * A version ID that identifies the serialization structure used by getSerializationData()
 293          * and unserialize(). This is useful for constructing cache keys in cases where the cache relies
 294          * on serialization for storing the SiteList.
 295          *
 296          * @var string A string uniquely identifying the version of the serialization structure,
 297          *             not including any sub-structures.
 298          */
 299         const SERIAL_VERSION_ID = '2014-03-17';
 300
 301         /**
 302          * Returns the version ID that identifies the serialization structure used by
 303          * getSerializationData() and unserialize(), including the structure of any nested structures.
 304          * This is useful for constructing cache keys in cases where the cache relies
 305          * on serialization for storing the SiteList.
 306          *
 307          * @return string A string uniquely identifying the version of the serialization structure,
 308          *                including any sub-structures.
 309          */
 310         public static function getSerialVersionId() {
 311                 return self::SERIAL_VERSION_ID . '+Site:' . Site::SERIAL_VERSION_ID;
 312         }
 313
 314         /**
 315          * @see GenericArrayObject::getSerializationData
 316          *
 317          * @since 1.21
 318          *
 319          * @return array
 320          */
 321         protected function getSerializationData() {
 322                 // NOTE: When changing the structure, either implement unserialize() to handle the
 323                 //      old structure too, or update SERIAL_VERSION_ID to kill any caches.
 324                 return array_merge(
 325                         parent::getSerializationData(),
 326                         [
 327                                 'internalIds' => $this->byInternalId,
 328                                 'globalIds' => $this->byGlobalId,
 329                                 'navigationIds' => $this->byNavigationId
 330                         ]
 331                 );
 332         }
 333
 334         /**
 335          * @see GenericArrayObject::unserialize
 336          *
 337          * @since 1.21
 338          *
 339          * @param string $serialization
 340          *
 341          * @return array
 342          */
 343         public function unserialize( $serialization ) {
 344                 $serializationData = parent::unserialize( $serialization );
 345
 346                 $this->byInternalId = $serializationData['internalIds'];
 347                 $this->byGlobalId = $serializationData['globalIds'];
 348                 $this->byNavigationId = $serializationData['navigationIds'];
 349
 350                 return $serializationData;
 351         }
 352 }