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