Merge "Import BatchRowUpdate classes from Echo"
[mediawiki.git] / includes / site / Site.php
blobfafb14c73926bf17e10d8909fd88c663661972aa
1 <?php
3 /**
4 * Represents a single site.
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.
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.
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
21 * @since 1.21
23 * @file
24 * @ingroup Site
26 * @license GNU GPL v2+
27 * @author Jeroen De Dauw < jeroendedauw@gmail.com >
29 class Site implements Serializable {
30 const TYPE_UNKNOWN = 'unknown';
31 const TYPE_MEDIAWIKI = 'mediawiki';
33 const GROUP_NONE = 'none';
35 const ID_INTERWIKI = 'interwiki';
36 const ID_EQUIVALENT = 'equivalent';
38 const SOURCE_LOCAL = 'local';
40 const PATH_LINK = 'link';
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.
47 * @var string A string uniquely identifying the version of the serialization structure.
49 const SERIAL_VERSION_ID = '2013-01-23';
51 /**
52 * @since 1.21
54 * @var string|null
56 protected $globalId = null;
58 /**
59 * @since 1.21
61 * @var string
63 protected $type = self::TYPE_UNKNOWN;
65 /**
66 * @since 1.21
68 * @var string
70 protected $group = self::GROUP_NONE;
72 /**
73 * @since 1.21
75 * @var string
77 protected $source = self::SOURCE_LOCAL;
79 /**
80 * @since 1.21
82 * @var string|null
84 protected $languageCode = null;
86 /**
87 * Holds the local ids for this site.
88 * local id type => [ ids for this type (strings) ]
90 * @since 1.21
92 * @var array[]
94 protected $localIds = array();
96 /**
97 * @since 1.21
99 * @var array
101 protected $extraData = array();
104 * @since 1.21
106 * @var array
108 protected $extraConfig = array();
111 * @since 1.21
113 * @var bool
115 protected $forward = false;
118 * @since 1.21
120 * @var int|null
122 protected $internalId = null;
125 * Constructor.
127 * @since 1.21
129 * @param string $type
131 public function __construct( $type = self::TYPE_UNKNOWN ) {
132 $this->type = $type;
136 * Returns the global site identifier (ie enwiktionary).
138 * @since 1.21
140 * @return string|null
142 public function getGlobalId() {
143 return $this->globalId;
147 * Sets the global site identifier (ie enwiktionary).
149 * @since 1.21
151 * @param string|null $globalId
153 * @throws MWException
155 public function setGlobalId( $globalId ) {
156 if ( $globalId !== null && !is_string( $globalId ) ) {
157 throw new MWException( '$globalId needs to be string or null' );
160 $this->globalId = $globalId;
164 * Returns the type of the site (ie mediawiki).
166 * @since 1.21
168 * @return string
170 public function getType() {
171 return $this->type;
175 * Gets the type of the site (ie wikipedia).
177 * @since 1.21
179 * @return string
181 public function getGroup() {
182 return $this->group;
186 * Sets the type of the site (ie wikipedia).
188 * @since 1.21
190 * @param string $group
192 * @throws MWException
194 public function setGroup( $group ) {
195 if ( !is_string( $group ) ) {
196 throw new MWException( '$group needs to be a string' );
199 $this->group = $group;
203 * Returns the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
205 * @since 1.21
207 * @return string
209 public function getSource() {
210 return $this->source;
214 * Sets the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
216 * @since 1.21
218 * @param string $source
220 * @throws MWException
222 public function setSource( $source ) {
223 if ( !is_string( $source ) ) {
224 throw new MWException( '$source needs to be a string' );
227 $this->source = $source;
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.
234 * @since 1.21
236 * @return bool
238 public function shouldForward() {
239 return $this->forward;
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.
246 * @since 1.21
248 * @param bool $shouldForward
250 * @throws MWException
252 public function setForward( $shouldForward ) {
253 if ( !is_bool( $shouldForward ) ) {
254 throw new MWException( '$shouldForward needs to be a boolean' );
257 $this->forward = $shouldForward;
261 * Returns the domain of the site, ie en.wikipedia.org
262 * Or false if it's not known.
264 * @since 1.21
266 * @return string|null
268 public function getDomain() {
269 $path = $this->getLinkPath();
271 if ( $path === null ) {
272 return null;
275 return parse_url( $path, PHP_URL_HOST );
279 * Returns the protocol of the site.
281 * @since 1.21
283 * @throws MWException
284 * @return string
286 public function getProtocol() {
287 $path = $this->getLinkPath();
289 if ( $path === null ) {
290 return '';
293 $protocol = parse_url( $path, PHP_URL_SCHEME );
295 // Malformed URL
296 if ( $protocol === false ) {
297 throw new MWException( "failed to parse URL '$path'" );
300 // No schema
301 if ( $protocol === null ) {
302 // Used for protocol relative URLs
303 $protocol = '';
306 return $protocol;
310 * Sets the path used to construct links with.
311 * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
313 * @param string $fullUrl
315 * @since 1.21
317 * @throws MWException
319 public function setLinkPath( $fullUrl ) {
320 $type = $this->getLinkPathType();
322 if ( $type === null ) {
323 throw new MWException( "This Site does not support link paths." );
326 $this->setPath( $type, $fullUrl );
330 * Returns the path used to construct links with or false if there is no such path.
332 * Shall be equivalent to getPath( getLinkPathType() ).
334 * @return string|null
336 public function getLinkPath() {
337 $type = $this->getLinkPathType();
338 return $type === null ? null: $this->getPath( $type );
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.
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.
349 * @since 1.21
351 * @return string|null
353 public function getLinkPathType() {
354 return self::PATH_LINK;
358 * Returns the full URL for the given page on the site.
359 * Or false if the needed information is not known.
361 * This generated URL is usually based upon the path returned by getLinkPath(),
362 * but this is not a requirement.
364 * This implementation returns a URL constructed using the path returned by getLinkPath().
366 * @since 1.21
368 * @param bool|string $pageName
370 * @return string|bool
372 public function getPageUrl( $pageName = false ) {
373 $url = $this->getLinkPath();
375 if ( $url === false ) {
376 return false;
379 if ( $pageName !== false ) {
380 $url = str_replace( '$1', rawurlencode( $pageName ), $url );
383 return $url;
387 * Returns $pageName without changes.
388 * Subclasses may override this to apply some kind of normalization.
390 * @see Site::normalizePageName
392 * @since 1.21
394 * @param string $pageName
396 * @return string
398 public function normalizePageName( $pageName ) {
399 return $pageName;
403 * Returns the type specific fields.
405 * @since 1.21
407 * @return array
409 public function getExtraData() {
410 return $this->extraData;
414 * Sets the type specific fields.
416 * @since 1.21
418 * @param array $extraData
420 public function setExtraData( array $extraData ) {
421 $this->extraData = $extraData;
425 * Returns the type specific config.
427 * @since 1.21
429 * @return array
431 public function getExtraConfig() {
432 return $this->extraConfig;
436 * Sets the type specific config.
438 * @since 1.21
440 * @param array $extraConfig
442 public function setExtraConfig( array $extraConfig ) {
443 $this->extraConfig = $extraConfig;
447 * Returns language code of the sites primary language.
448 * Or null if it's not known.
450 * @since 1.21
452 * @return string|null
454 public function getLanguageCode() {
455 return $this->languageCode;
459 * Sets language code of the sites primary language.
461 * @since 1.21
463 * @param string $languageCode
465 public function setLanguageCode( $languageCode ) {
466 $this->languageCode = $languageCode;
470 * Returns the set internal identifier for the site.
472 * @since 1.21
474 * @return string|null
476 public function getInternalId() {
477 return $this->internalId;
481 * Sets the internal identifier for the site.
482 * This typically is a primary key in a db table.
484 * @since 1.21
486 * @param int|null $internalId
488 public function setInternalId( $internalId = null ) {
489 $this->internalId = $internalId;
493 * Adds a local identifier.
495 * @since 1.21
497 * @param string $type
498 * @param string $identifier
500 public function addLocalId( $type, $identifier ) {
501 if ( $this->localIds === false ) {
502 $this->localIds = array();
505 if ( !array_key_exists( $type, $this->localIds ) ) {
506 $this->localIds[$type] = array();
509 if ( !in_array( $identifier, $this->localIds[$type] ) ) {
510 $this->localIds[$type][] = $identifier;
515 * Adds an interwiki id to the site.
517 * @since 1.21
519 * @param string $identifier
521 public function addInterwikiId( $identifier ) {
522 $this->addLocalId( self::ID_INTERWIKI, $identifier );
526 * Adds a navigation id to the site.
528 * @since 1.21
530 * @param string $identifier
532 public function addNavigationId( $identifier ) {
533 $this->addLocalId( self::ID_EQUIVALENT, $identifier );
537 * Returns the interwiki link identifiers that can be used for this site.
539 * @since 1.21
541 * @return string[]
543 public function getInterwikiIds() {
544 return array_key_exists( self::ID_INTERWIKI, $this->localIds )
545 ? $this->localIds[self::ID_INTERWIKI]
546 : array();
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.
553 * @since 1.21
555 * @return string[]
557 public function getNavigationIds() {
558 return array_key_exists( self::ID_EQUIVALENT, $this->localIds )
559 ? $this->localIds[self::ID_EQUIVALENT] :
560 array();
564 * Returns all local ids
566 * @since 1.21
568 * @return array[]
570 public function getLocalIds() {
571 return $this->localIds;
575 * Sets the path used to construct links with.
576 * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
578 * @since 1.21
580 * @param string $pathType
581 * @param string $fullUrl
583 * @throws MWException
585 public function setPath( $pathType, $fullUrl ) {
586 if ( !is_string( $fullUrl ) ) {
587 throw new MWException( '$fullUrl needs to be a string' );
590 if ( !array_key_exists( 'paths', $this->extraData ) ) {
591 $this->extraData['paths'] = array();
594 $this->extraData['paths'][$pathType] = $fullUrl;
598 * Returns the path of the provided type or false if there is no such path.
600 * @since 1.21
602 * @param string $pathType
604 * @return string|null
606 public function getPath( $pathType ) {
607 $paths = $this->getAllPaths();
608 return array_key_exists( $pathType, $paths ) ? $paths[$pathType] : null;
612 * Returns the paths as associative array.
613 * The keys are path types, the values are the path urls.
615 * @since 1.21
617 * @return string[]
619 public function getAllPaths() {
620 return array_key_exists( 'paths', $this->extraData ) ? $this->extraData['paths'] : array();
624 * Removes the path of the provided type if it's set.
626 * @since 1.21
628 * @param string $pathType
630 public function removePath( $pathType ) {
631 if ( array_key_exists( 'paths', $this->extraData ) ) {
632 unset( $this->extraData['paths'][$pathType] );
637 * @since 1.21
639 * @param string $siteType
641 * @return Site
643 public static function newForType( $siteType ) {
644 global $wgSiteTypes;
646 if ( array_key_exists( $siteType, $wgSiteTypes ) ) {
647 return new $wgSiteTypes[$siteType]();
650 return new Site();
654 * @see Serializable::serialize
656 * @since 1.21
658 * @return string
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,
675 return serialize( $fields );
679 * @see Serializable::unserialize
681 * @since 1.21
683 * @param string $serialized
685 public function unserialize( $serialized ) {
686 $fields = unserialize( $serialized );
688 $this->__construct( $fields['type'] );
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'] );
703 * @deprecated since 1.21
705 class SiteObject extends Site {