[Summary view] [Print] [Text view]

   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 < [email protected] >
  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 = array();
  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 = array();
  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 = array();
  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 === array();
 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              array(
 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  }
 353  
 354  /**
 355   * @deprecated since 1.21
 356   */
 357  class SiteArray extends SiteList {
 358  }