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