[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  /**
   4   * Represents a single site.
   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 Site implements Serializable {
  30      const TYPE_UNKNOWN = 'unknown';
  31      const TYPE_MEDIAWIKI = 'mediawiki';
  32  
  33      const GROUP_NONE = 'none';
  34  
  35      const ID_INTERWIKI = 'interwiki';
  36      const ID_EQUIVALENT = 'equivalent';
  37  
  38      const SOURCE_LOCAL = 'local';
  39  
  40      const PATH_LINK = 'link';
  41  
  42      /**
  43       * A version ID that identifies the serialization structure used by getSerializationData()
  44       * and unserialize(). This is useful for constructing cache keys in cases where the cache relies
  45       * on serialization for storing the SiteList.
  46       *
  47       * @var string A string uniquely identifying the version of the serialization structure.
  48       */
  49      const SERIAL_VERSION_ID = '2013-01-23';
  50  
  51      /**
  52       * @since 1.21
  53       *
  54       * @var string|null
  55       */
  56      protected $globalId = null;
  57  
  58      /**
  59       * @since 1.21
  60       *
  61       * @var string
  62       */
  63      protected $type = self::TYPE_UNKNOWN;
  64  
  65      /**
  66       * @since 1.21
  67       *
  68       * @var string
  69       */
  70      protected $group = self::GROUP_NONE;
  71  
  72      /**
  73       * @since 1.21
  74       *
  75       * @var string
  76       */
  77      protected $source = self::SOURCE_LOCAL;
  78  
  79      /**
  80       * @since 1.21
  81       *
  82       * @var string|null
  83       */
  84      protected $languageCode = null;
  85  
  86      /**
  87       * Holds the local ids for this site.
  88       * local id type => [ ids for this type (strings) ]
  89       *
  90       * @since 1.21
  91       *
  92       * @var array[]
  93       */
  94      protected $localIds = array();
  95  
  96      /**
  97       * @since 1.21
  98       *
  99       * @var array
 100       */
 101      protected $extraData = array();
 102  
 103      /**
 104       * @since 1.21
 105       *
 106       * @var array
 107       */
 108      protected $extraConfig = array();
 109  
 110      /**
 111       * @since 1.21
 112       *
 113       * @var bool
 114       */
 115      protected $forward = false;
 116  
 117      /**
 118       * @since 1.21
 119       *
 120       * @var int|null
 121       */
 122      protected $internalId = null;
 123  
 124      /**
 125       * Constructor.
 126       *
 127       * @since 1.21
 128       *
 129       * @param string $type
 130       */
 131  	public function __construct( $type = self::TYPE_UNKNOWN ) {
 132          $this->type = $type;
 133      }
 134  
 135      /**
 136       * Returns the global site identifier (ie enwiktionary).
 137       *
 138       * @since 1.21
 139       *
 140       * @return string|null
 141       */
 142  	public function getGlobalId() {
 143          return $this->globalId;
 144      }
 145  
 146      /**
 147       * Sets the global site identifier (ie enwiktionary).
 148       *
 149       * @since 1.21
 150       *
 151       * @param string|null $globalId
 152       *
 153       * @throws MWException
 154       */
 155  	public function setGlobalId( $globalId ) {
 156          if ( $globalId !== null && !is_string( $globalId ) ) {
 157              throw new MWException( '$globalId needs to be string or null' );
 158          }
 159  
 160          $this->globalId = $globalId;
 161      }
 162  
 163      /**
 164       * Returns the type of the site (ie mediawiki).
 165       *
 166       * @since 1.21
 167       *
 168       * @return string
 169       */
 170  	public function getType() {
 171          return $this->type;
 172      }
 173  
 174      /**
 175       * Gets the type of the site (ie wikipedia).
 176       *
 177       * @since 1.21
 178       *
 179       * @return string
 180       */
 181  	public function getGroup() {
 182          return $this->group;
 183      }
 184  
 185      /**
 186       * Sets the type of the site (ie wikipedia).
 187       *
 188       * @since 1.21
 189       *
 190       * @param string $group
 191       *
 192       * @throws MWException
 193       */
 194  	public function setGroup( $group ) {
 195          if ( !is_string( $group ) ) {
 196              throw new MWException( '$group needs to be a string' );
 197          }
 198  
 199          $this->group = $group;
 200      }
 201  
 202      /**
 203       * Returns the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
 204       *
 205       * @since 1.21
 206       *
 207       * @return string
 208       */
 209  	public function getSource() {
 210          return $this->source;
 211      }
 212  
 213      /**
 214       * Sets the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
 215       *
 216       * @since 1.21
 217       *
 218       * @param string $source
 219       *
 220       * @throws MWException
 221       */
 222  	public function setSource( $source ) {
 223          if ( !is_string( $source ) ) {
 224              throw new MWException( '$source needs to be a string' );
 225          }
 226  
 227          $this->source = $source;
 228      }
 229  
 230      /**
 231       * Gets if site.tld/path/key:pageTitle should forward users to  the page on
 232       * the actual site, where "key" is the local identifier.
 233       *
 234       * @since 1.21
 235       *
 236       * @return bool
 237       */
 238  	public function shouldForward() {
 239          return $this->forward;
 240      }
 241  
 242      /**
 243       * Sets if site.tld/path/key:pageTitle should forward users to  the page on
 244       * the actual site, where "key" is the local identifier.
 245       *
 246       * @since 1.21
 247       *
 248       * @param bool $shouldForward
 249       *
 250       * @throws MWException
 251       */
 252  	public function setForward( $shouldForward ) {
 253          if ( !is_bool( $shouldForward ) ) {
 254              throw new MWException( '$shouldForward needs to be a boolean' );
 255          }
 256  
 257          $this->forward = $shouldForward;
 258      }
 259  
 260      /**
 261       * Returns the domain of the site, ie en.wikipedia.org
 262       * Or false if it's not known.
 263       *
 264       * @since 1.21
 265       *
 266       * @return string|null
 267       */
 268  	public function getDomain() {
 269          $path = $this->getLinkPath();
 270  
 271          if ( $path === null ) {
 272              return null;
 273          }
 274  
 275          return parse_url( $path, PHP_URL_HOST );
 276      }
 277  
 278      /**
 279       * Returns the protocol of the site.
 280       *
 281       * @since 1.21
 282       *
 283       * @throws MWException
 284       * @return string
 285       */
 286  	public function getProtocol() {
 287          $path = $this->getLinkPath();
 288  
 289          if ( $path === null ) {
 290              return '';
 291          }
 292  
 293          $protocol = parse_url( $path, PHP_URL_SCHEME );
 294  
 295          // Malformed URL
 296          if ( $protocol === false ) {
 297              throw new MWException( "failed to parse URL '$path'" );
 298          }
 299  
 300          // No schema
 301          if ( $protocol === null ) {
 302              // Used for protocol relative URLs
 303              $protocol = '';
 304          }
 305  
 306          return $protocol;
 307      }
 308  
 309      /**
 310       * Sets the path used to construct links with.
 311       * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
 312       *
 313       * @param string $fullUrl
 314       *
 315       * @since 1.21
 316       *
 317       * @throws MWException
 318       */
 319  	public function setLinkPath( $fullUrl ) {
 320          $type = $this->getLinkPathType();
 321  
 322          if ( $type === null ) {
 323              throw new MWException( "This Site does not support link paths." );
 324          }
 325  
 326          $this->setPath( $type, $fullUrl );
 327      }
 328  
 329      /**
 330       * Returns the path used to construct links with or false if there is no such path.
 331       *
 332       * Shall be equivalent to getPath( getLinkPathType() ).
 333       *
 334       * @return string|null
 335       */
 336  	public function getLinkPath() {
 337          $type = $this->getLinkPathType();
 338          return $type === null ? null: $this->getPath( $type );
 339      }
 340  
 341      /**
 342       * Returns the main path type, that is the type of the path that should
 343       * generally be used to construct links to the target site.
 344       *
 345       * This default implementation returns Site::PATH_LINK as the default path
 346       * type. Subclasses can override this to define a different default path
 347       * type, or return false to disable site links.
 348       *
 349       * @since 1.21
 350       *
 351       * @return string|null
 352       */
 353  	public function getLinkPathType() {
 354          return self::PATH_LINK;
 355      }
 356  
 357      /**
 358       * Returns the full URL for the given page on the site.
 359       * Or false if the needed information is not known.
 360       *
 361       * This generated URL is usually based upon the path returned by getLinkPath(),
 362       * but this is not a requirement.
 363       *
 364       * This implementation returns a URL constructed using the path returned by getLinkPath().
 365       *
 366       * @since 1.21
 367       *
 368       * @param bool|string $pageName
 369       *
 370       * @return string|bool
 371       */
 372  	public function getPageUrl( $pageName = false ) {
 373          $url = $this->getLinkPath();
 374  
 375          if ( $url === false ) {
 376              return false;
 377          }
 378  
 379          if ( $pageName !== false ) {
 380              $url = str_replace( '$1', rawurlencode( $pageName ), $url );
 381          }
 382  
 383          return $url;
 384      }
 385  
 386      /**
 387       * Returns $pageName without changes.
 388       * Subclasses may override this to apply some kind of normalization.
 389       *
 390       * @see Site::normalizePageName
 391       *
 392       * @since 1.21
 393       *
 394       * @param string $pageName
 395       *
 396       * @return string
 397       */
 398  	public function normalizePageName( $pageName ) {
 399          return $pageName;
 400      }
 401  
 402      /**
 403       * Returns the type specific fields.
 404       *
 405       * @since 1.21
 406       *
 407       * @return array
 408       */
 409  	public function getExtraData() {
 410          return $this->extraData;
 411      }
 412  
 413      /**
 414       * Sets the type specific fields.
 415       *
 416       * @since 1.21
 417       *
 418       * @param array $extraData
 419       */
 420  	public function setExtraData( array $extraData ) {
 421          $this->extraData = $extraData;
 422      }
 423  
 424      /**
 425       * Returns the type specific config.
 426       *
 427       * @since 1.21
 428       *
 429       * @return array
 430       */
 431  	public function getExtraConfig() {
 432          return $this->extraConfig;
 433      }
 434  
 435      /**
 436       * Sets the type specific config.
 437       *
 438       * @since 1.21
 439       *
 440       * @param array $extraConfig
 441       */
 442  	public function setExtraConfig( array $extraConfig ) {
 443          $this->extraConfig = $extraConfig;
 444      }
 445  
 446      /**
 447       * Returns language code of the sites primary language.
 448       * Or null if it's not known.
 449       *
 450       * @since 1.21
 451       *
 452       * @return string|null
 453       */
 454  	public function getLanguageCode() {
 455          return $this->languageCode;
 456      }
 457  
 458      /**
 459       * Sets language code of the sites primary language.
 460       *
 461       * @since 1.21
 462       *
 463       * @param string $languageCode
 464       */
 465  	public function setLanguageCode( $languageCode ) {
 466          $this->languageCode = $languageCode;
 467      }
 468  
 469      /**
 470       * Returns the set internal identifier for the site.
 471       *
 472       * @since 1.21
 473       *
 474       * @return string|null
 475       */
 476  	public function getInternalId() {
 477          return $this->internalId;
 478      }
 479  
 480      /**
 481       * Sets the internal identifier for the site.
 482       * This typically is a primary key in a db table.
 483       *
 484       * @since 1.21
 485       *
 486       * @param int|null $internalId
 487       */
 488  	public function setInternalId( $internalId = null ) {
 489          $this->internalId = $internalId;
 490      }
 491  
 492      /**
 493       * Adds a local identifier.
 494       *
 495       * @since 1.21
 496       *
 497       * @param string $type
 498       * @param string $identifier
 499       */
 500  	public function addLocalId( $type, $identifier ) {
 501          if ( $this->localIds === false ) {
 502              $this->localIds = array();
 503          }
 504  
 505          if ( !array_key_exists( $type, $this->localIds ) ) {
 506              $this->localIds[$type] = array();
 507          }
 508  
 509          if ( !in_array( $identifier, $this->localIds[$type] ) ) {
 510              $this->localIds[$type][] = $identifier;
 511          }
 512      }
 513  
 514      /**
 515       * Adds an interwiki id to the site.
 516       *
 517       * @since 1.21
 518       *
 519       * @param string $identifier
 520       */
 521  	public function addInterwikiId( $identifier ) {
 522          $this->addLocalId( self::ID_INTERWIKI, $identifier );
 523      }
 524  
 525      /**
 526       * Adds a navigation id to the site.
 527       *
 528       * @since 1.21
 529       *
 530       * @param string $identifier
 531       */
 532  	public function addNavigationId( $identifier ) {
 533          $this->addLocalId( self::ID_EQUIVALENT, $identifier );
 534      }
 535  
 536      /**
 537       * Returns the interwiki link identifiers that can be used for this site.
 538       *
 539       * @since 1.21
 540       *
 541       * @return string[]
 542       */
 543  	public function getInterwikiIds() {
 544          return array_key_exists( self::ID_INTERWIKI, $this->localIds )
 545              ? $this->localIds[self::ID_INTERWIKI]
 546              : array();
 547      }
 548  
 549      /**
 550       * Returns the equivalent link identifiers that can be used to make
 551       * the site show up in interfaces such as the "language links" section.
 552       *
 553       * @since 1.21
 554       *
 555       * @return string[]
 556       */
 557  	public function getNavigationIds() {
 558          return array_key_exists( self::ID_EQUIVALENT, $this->localIds )
 559              ? $this->localIds[self::ID_EQUIVALENT] :
 560              array();
 561      }
 562  
 563      /**
 564       * Returns all local ids
 565       *
 566       * @since 1.21
 567       *
 568       * @return array[]
 569       */
 570  	public function getLocalIds() {
 571          return $this->localIds;
 572      }
 573  
 574      /**
 575       * Sets the path used to construct links with.
 576       * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
 577       *
 578       * @since 1.21
 579       *
 580       * @param string $pathType
 581       * @param string $fullUrl
 582       *
 583       * @throws MWException
 584       */
 585  	public function setPath( $pathType, $fullUrl ) {
 586          if ( !is_string( $fullUrl ) ) {
 587              throw new MWException( '$fullUrl needs to be a string' );
 588          }
 589  
 590          if ( !array_key_exists( 'paths', $this->extraData ) ) {
 591              $this->extraData['paths'] = array();
 592          }
 593  
 594          $this->extraData['paths'][$pathType] = $fullUrl;
 595      }
 596  
 597      /**
 598       * Returns the path of the provided type or false if there is no such path.
 599       *
 600       * @since 1.21
 601       *
 602       * @param string $pathType
 603       *
 604       * @return string|null
 605       */
 606  	public function getPath( $pathType ) {
 607          $paths = $this->getAllPaths();
 608          return array_key_exists( $pathType, $paths ) ? $paths[$pathType] : null;
 609      }
 610  
 611      /**
 612       * Returns the paths as associative array.
 613       * The keys are path types, the values are the path urls.
 614       *
 615       * @since 1.21
 616       *
 617       * @return string[]
 618       */
 619  	public function getAllPaths() {
 620          return array_key_exists( 'paths', $this->extraData ) ? $this->extraData['paths'] : array();
 621      }
 622  
 623      /**
 624       * Removes the path of the provided type if it's set.
 625       *
 626       * @since 1.21
 627       *
 628       * @param string $pathType
 629       */
 630  	public function removePath( $pathType ) {
 631          if ( array_key_exists( 'paths', $this->extraData ) ) {
 632              unset( $this->extraData['paths'][$pathType] );
 633          }
 634      }
 635  
 636      /**
 637       * @since 1.21
 638       *
 639       * @param string $siteType
 640       *
 641       * @return Site
 642       */
 643  	public static function newForType( $siteType ) {
 644          global $wgSiteTypes;
 645  
 646          if ( array_key_exists( $siteType, $wgSiteTypes ) ) {
 647              return new $wgSiteTypes[$siteType]();
 648          }
 649  
 650          return new Site();
 651      }
 652  
 653      /**
 654       * @see Serializable::serialize
 655       *
 656       * @since 1.21
 657       *
 658       * @return string
 659       */
 660  	public function serialize() {
 661          $fields = array(
 662              'globalid' => $this->globalId,
 663              'type' => $this->type,
 664              'group' => $this->group,
 665              'source' => $this->source,
 666              'language' => $this->languageCode,
 667              'localids' => $this->localIds,
 668              'config' => $this->extraConfig,
 669              'data' => $this->extraData,
 670              'forward' => $this->forward,
 671              'internalid' => $this->internalId,
 672  
 673          );
 674  
 675          return serialize( $fields );
 676      }
 677  
 678      /**
 679       * @see Serializable::unserialize
 680       *
 681       * @since 1.21
 682       *
 683       * @param string $serialized
 684       */
 685  	public function unserialize( $serialized ) {
 686          $fields = unserialize( $serialized );
 687  
 688          $this->__construct( $fields['type'] );
 689  
 690          $this->setGlobalId( $fields['globalid'] );
 691          $this->setGroup( $fields['group'] );
 692          $this->setSource( $fields['source'] );
 693          $this->setLanguageCode( $fields['language'] );
 694          $this->localIds = $fields['localids'];
 695          $this->setExtraConfig( $fields['config'] );
 696          $this->setExtraData( $fields['data'] );
 697          $this->setForward( $fields['forward'] );
 698          $this->setInternalId( $fields['internalid'] );
 699      }
 700  }
 701  
 702  /**
 703   * @deprecated since 1.21
 704   */
 705  class SiteObject extends Site {
 706  }