includes/site/Site.php

   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 < jeroendedauw@gmail.com >
  28  */
  29 class Site implements Serializable {
  30
  31         const TYPE_UNKNOWN = 'unknown';
  32         const TYPE_MEDIAWIKI = 'mediawiki';
  33
  34         const GROUP_NONE = 'none';
  35
  36         const ID_INTERWIKI = 'interwiki';
  37         const ID_EQUIVALENT = 'equivalent';
  38
  39         const SOURCE_LOCAL = 'local';
  40
  41         const PATH_LINK = 'link';
  42
  43         /**
  44          * A version ID that identifies the serialization structure used by getSerializationData()
  45          * and unserialize(). This is useful for constructing cache keys in cases where the cache relies
  46          * on serialization for storing the SiteList.
  47          *
  48          * @var string A string uniquely identifying the version of the serialization structure.
  49          */
  50         const SERIAL_VERSION_ID = '2013-01-23';
  51
  52         /**
  53          * @since 1.21
  54          *
  55          * @var string|null
  56          */
  57         protected $globalId = null;
  58
  59         /**
  60          * @since 1.21
  61          *
  62          * @var string
  63          */
  64         protected $type = self::TYPE_UNKNOWN;
  65
  66         /**
  67          * @since 1.21
  68          *
  69          * @var string
  70          */
  71         protected $group = self::GROUP_NONE;
  72
  73         /**
  74          * @since 1.21
  75          *
  76          * @var string
  77          */
  78         protected $source = self::SOURCE_LOCAL;
  79
  80         /**
  81          * @since 1.21
  82          *
  83          * @var string|null
  84          */
  85         protected $languageCode = null;
  86
  87         /**
  88          * Holds the local ids for this site.
  89          * local id type => [ ids for this type (strings) ]
  90          *
  91          * @since 1.21
  92          *
  93          * @var array[]
  94          */
  95         protected $localIds = array();
  96
  97         /**
  98          * @since 1.21
  99          *
 100          * @var array
 101          */
 102         protected $extraData = array();
 103
 104         /**
 105          * @since 1.21
 106          *
 107          * @var array
 108          */
 109         protected $extraConfig = array();
 110
 111         /**
 112          * @since 1.21
 113          *
 114          * @var bool
 115          */
 116         protected $forward = false;
 117
 118         /**
 119          * @since 1.21
 120          *
 121          * @var int|null
 122          */
 123         protected $internalId = null;
 124
 125         /**
 126          * Constructor.
 127          *
 128          * @since 1.21
 129          *
 130          * @param string $type
 131          */
 132         public function __construct( $type = self::TYPE_UNKNOWN ) {
 133                 $this->type = $type;
 134         }
 135
 136         /**
 137          * Returns the global site identifier (ie enwiktionary).
 138          *
 139          * @since 1.21
 140          *
 141          * @return string|null
 142          */
 143         public function getGlobalId() {
 144                 return $this->globalId;
 145         }
 146
 147         /**
 148          * Sets the global site identifier (ie enwiktionary).
 149          *
 150          * @since 1.21
 151          *
 152          * @param string|null $globalId
 153          *
 154          * @throws MWException
 155          */
 156         public function setGlobalId( $globalId ) {
 157                 if ( $globalId !== null && !is_string( $globalId ) ) {
 158                         throw new MWException( '$globalId needs to be string or null' );
 159                 }
 160
 161                 $this->globalId = $globalId;
 162         }
 163
 164         /**
 165          * Returns the type of the site (ie mediawiki).
 166          *
 167          * @since 1.21
 168          *
 169          * @return string
 170          */
 171         public function getType() {
 172                 return $this->type;
 173         }
 174
 175         /**
 176          * Gets the type of the site (ie wikipedia).
 177          *
 178          * @since 1.21
 179          *
 180          * @return string
 181          */
 182         public function getGroup() {
 183                 return $this->group;
 184         }
 185
 186         /**
 187          * Sets the type of the site (ie wikipedia).
 188          *
 189          * @since 1.21
 190          *
 191          * @param string $group
 192          *
 193          * @throws MWException
 194          */
 195         public function setGroup( $group ) {
 196                 if ( !is_string( $group ) ) {
 197                         throw new MWException( '$group needs to be a string' );
 198                 }
 199
 200                 $this->group = $group;
 201         }
 202
 203         /**
 204          * Returns the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
 205          *
 206          * @since 1.21
 207          *
 208          * @return string
 209          */
 210         public function getSource() {
 211                 return $this->source;
 212         }
 213
 214         /**
 215          * Sets the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
 216          *
 217          * @since 1.21
 218          *
 219          * @param string $source
 220          *
 221          * @throws MWException
 222          */
 223         public function setSource( $source ) {
 224                 if ( !is_string( $source ) ) {
 225                         throw new MWException( '$source needs to be a string' );
 226                 }
 227
 228                 $this->source = $source;
 229         }
 230
 231         /**
 232          * Gets if site.tld/path/key:pageTitle should forward users to  the page on
 233          * the actual site, where "key" is the local identifier.
 234          *
 235          * @since 1.21
 236          *
 237          * @return boolean
 238          */
 239         public function shouldForward() {
 240                 return $this->forward;
 241         }
 242
 243         /**
 244          * Sets if site.tld/path/key:pageTitle should forward users to  the page on
 245          * the actual site, where "key" is the local identifier.
 246          *
 247          * @since 1.21
 248          *
 249          * @param boolean $shouldForward
 250          *
 251          * @throws MWException
 252          */
 253         public function setForward( $shouldForward ) {
 254                 if ( !is_bool( $shouldForward ) ) {
 255                         throw new MWException( '$shouldForward needs to be a boolean' );
 256                 }
 257
 258                 $this->forward = $shouldForward;
 259         }
 260
 261         /**
 262          * Returns the domain of the site, ie en.wikipedia.org
 263          * Or false if it's not known.
 264          *
 265          * @since 1.21
 266          *
 267          * @return string|null
 268          */
 269         public function getDomain() {
 270                 $path = $this->getLinkPath();
 271
 272                 if ( $path === null ) {
 273                         return null;
 274                 }
 275
 276                 return parse_url( $path, PHP_URL_HOST );
 277         }
 278
 279         /**
 280          * Returns the protocol of the site.
 281          *
 282          * @since 1.21
 283          *
 284          * @throws MWException
 285          * @return string
 286          */
 287         public function getProtocol() {
 288                 $path = $this->getLinkPath();
 289
 290                 if ( $path === null ) {
 291                         return '';
 292                 }
 293
 294                 $protocol = parse_url( $path, PHP_URL_SCHEME );
 295
 296                 // Malformed URL
 297                 if ( $protocol === false ) {
 298                         throw new MWException( "failed to parse URL '$path'" );
 299                 }
 300
 301                 // No schema
 302                 if ( $protocol === null ) {
 303                         // Used for protocol relative URLs
 304                         $protocol = '';
 305                 }
 306
 307                 return $protocol;
 308         }
 309
 310         /**
 311          * Sets the path used to construct links with.
 312          * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
 313          *
 314          * @param string $fullUrl
 315          *
 316          * @since 1.21
 317          *
 318          * @throws MWException
 319          */
 320         public function setLinkPath( $fullUrl ) {
 321                 $type = $this->getLinkPathType();
 322
 323                 if ( $type === null ) {
 324                         throw new MWException( "This Site does not support link paths." );
 325                 }
 326
 327                 $this->setPath( $type, $fullUrl );
 328         }
 329
 330         /**
 331          * Returns the path used to construct links with or false if there is no such path.
 332          *
 333          * Shall be equivalent to getPath( getLinkPathType() ).
 334          *
 335          * @return string|null
 336          */
 337         public function getLinkPath() {
 338                 $type = $this->getLinkPathType();
 339                 return $type === null ? null: $this->getPath( $type );
 340         }
 341
 342         /**
 343          * Returns the main path type, that is the type of the path that should generally be used to construct links
 344          * to the target site.
 345          *
 346          * This default implementation returns Site::PATH_LINK as the default path type. Subclasses can override this
 347          * to define a different default path 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|boolean false
 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 ) ? $this->localIds[self::ID_INTERWIKI] : array();
 545         }
 546
 547         /**
 548          * Returns the equivalent link identifiers that can be used to make
 549          * the site show up in interfaces such as the "language links" section.
 550          *
 551          * @since 1.21
 552          *
 553          * @return string[]
 554          */
 555         public function getNavigationIds() {
 556                 return array_key_exists( self::ID_EQUIVALENT, $this->localIds ) ? $this->localIds[self::ID_EQUIVALENT] : array();
 557         }
 558
 559         /**
 560          * Returns all local ids
 561          *
 562          * @since 1.21
 563          *
 564          * @return array[]
 565          */
 566         public function getLocalIds() {
 567                 return $this->localIds;
 568         }
 569
 570         /**
 571          * Sets the path used to construct links with.
 572          * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
 573          *
 574          * @since 1.21
 575          *
 576          * @param string $pathType
 577          * @param string $fullUrl
 578          *
 579          * @throws MWException
 580          */
 581         public function setPath( $pathType, $fullUrl ) {
 582                 if ( !is_string( $fullUrl ) ) {
 583                         throw new MWException( '$fullUrl needs to be a string' );
 584                 }
 585
 586                 if ( !array_key_exists( 'paths', $this->extraData ) ) {
 587                         $this->extraData['paths'] = array();
 588                 }
 589
 590                 $this->extraData['paths'][$pathType] = $fullUrl;
 591         }
 592
 593         /**
 594          * Returns the path of the provided type or false if there is no such path.
 595          *
 596          * @since 1.21
 597          *
 598          * @param string $pathType
 599          *
 600          * @return string|null
 601          */
 602         public function getPath( $pathType ) {
 603                 $paths = $this->getAllPaths();
 604                 return array_key_exists( $pathType, $paths ) ? $paths[$pathType] : null;
 605         }
 606
 607         /**
 608          * Returns the paths as associative array.
 609          * The keys are path types, the values are the path urls.
 610          *
 611          * @since 1.21
 612          *
 613          * @return string[]
 614          */
 615         public function getAllPaths() {
 616                 return array_key_exists( 'paths', $this->extraData ) ? $this->extraData['paths'] : array();
 617         }
 618
 619         /**
 620          * Removes the path of the provided type if it's set.
 621          *
 622          * @since 1.21
 623          *
 624          * @param string $pathType
 625          */
 626         public function removePath( $pathType ) {
 627                 if ( array_key_exists( 'paths', $this->extraData ) ) {
 628                         unset( $this->extraData['paths'][$pathType] );
 629                 }
 630         }
 631
 632         /**
 633          * @since 1.21
 634          *
 635          * @param string $siteType
 636          *
 637          * @return Site
 638          */
 639         public static function newForType( $siteType ) {
 640                 global $wgSiteTypes;
 641
 642                 if ( array_key_exists( $siteType, $wgSiteTypes ) ) {
 643                         return new $wgSiteTypes[$siteType]();
 644                 }
 645
 646                 return new Site();
 647         }
 648
 649         /**
 650          * @see Serializable::serialize
 651          *
 652          * @since 1.21
 653          *
 654          * @return string
 655          */
 656         public function serialize() {
 657                 $fields = array(
 658                         'globalid' => $this->globalId,
 659                         'type' => $this->type,
 660                         'group' => $this->group,
 661                         'source' => $this->source,
 662                         'language' => $this->languageCode,
 663                         'localids' => $this->localIds,
 664                         'config' => $this->extraConfig,
 665                         'data' => $this->extraData,
 666                         'forward' => $this->forward,
 667                         'internalid' => $this->internalId,
 668
 669                 );
 670
 671                 return serialize( $fields );
 672         }
 673
 674         /**
 675          * @see Serializable::unserialize
 676          *
 677          * @since 1.21
 678          *
 679          * @param string $serialized
 680          */
 681         public function unserialize( $serialized ) {
 682                 $fields = unserialize( $serialized );
 683
 684                 $this->__construct( $fields['type'] );
 685
 686                 $this->setGlobalId( $fields['globalid'] );
 687                 $this->setGroup( $fields['group'] );
 688                 $this->setSource( $fields['source'] );
 689                 $this->setLanguageCode( $fields['language'] );
 690                 $this->localIds = $fields['localids'];
 691                 $this->setExtraConfig( $fields['config'] );
 692                 $this->setExtraData( $fields['data'] );
 693                 $this->setForward( $fields['forward'] );
 694                 $this->setInternalId( $fields['internalid'] );
 695         }
 696
 697 }
 698
 699 /**
 700  * @deprecated
 701  */
 702 class SiteObject extends Site {}