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
26 * @license GNU GPL v2+
27 * @author Jeroen De Dauw < jeroendedauw@gmail.com >
29 class Site
implements Serializable
{
31 const TYPE_UNKNOWN
= 'unknown';
32 const TYPE_MEDIAWIKI
= 'mediawiki';
34 const GROUP_NONE
= 'none';
36 const ID_INTERWIKI
= 'interwiki';
37 const ID_EQUIVALENT
= 'equivalent';
39 const SOURCE_LOCAL
= 'local';
41 const PATH_LINK
= 'link';
45 * A version ID that identifies the serialization structure used by getSerializationData()
46 * and unserialize(). This is useful for constructing cache keys in cases where the cache relies
47 * on serialization for storing the SiteList.
49 * @var string A string uniquely identifying the version of the serialization structure.
51 const SERIAL_VERSION_ID
= '2013-01-23';
58 protected $globalId = null;
65 protected $type = self
::TYPE_UNKNOWN
;
72 protected $group = self
::GROUP_NONE
;
79 protected $source = self
::SOURCE_LOCAL
;
86 protected $languageCode = null;
89 * Holds the local ids for this site.
90 * local id type => [ ids for this type (strings) ]
96 protected $localIds = array();
103 protected $extraData = array();
110 protected $extraConfig = array();
117 protected $forward = false;
124 protected $internalId = null;
131 * @param string $type
133 public function __construct( $type = self
::TYPE_UNKNOWN
) {
138 * Returns the global site identifier (ie enwiktionary).
142 * @return string|null
144 public function getGlobalId() {
145 return $this->globalId
;
149 * Sets the global site identifier (ie enwiktionary).
153 * @param string|null $globalId
155 * @throws MWException
157 public function setGlobalId( $globalId ) {
158 if ( $globalId !== null && !is_string( $globalId ) ) {
159 throw new MWException( '$globalId needs to be string or null' );
162 $this->globalId
= $globalId;
166 * Returns the type of the site (ie mediawiki).
172 public function getType() {
177 * Gets the type of the site (ie wikipedia).
183 public function getGroup() {
188 * Sets the type of the site (ie wikipedia).
192 * @param string $group
194 * @throws MWException
196 public function setGroup( $group ) {
197 if ( !is_string( $group ) ) {
198 throw new MWException( '$group needs to be a string' );
201 $this->group
= $group;
205 * Returns the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
211 public function getSource() {
212 return $this->source
;
216 * Sets the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
220 * @param string $source
222 * @throws MWException
224 public function setSource( $source ) {
225 if ( !is_string( $source ) ) {
226 throw new MWException( '$source needs to be a string' );
229 $this->source
= $source;
233 * Gets if site.tld/path/key:pageTitle should forward users to the page on
234 * the actual site, where "key" is the local identifier.
240 public function shouldForward() {
241 return $this->forward
;
245 * Sets if site.tld/path/key:pageTitle should forward users to the page on
246 * the actual site, where "key" is the local identifier.
250 * @param boolean $shouldForward
252 * @throws MWException
254 public function setForward( $shouldForward ) {
255 if ( !is_bool( $shouldForward ) ) {
256 throw new MWException( '$shouldForward needs to be a boolean' );
259 $this->forward
= $shouldForward;
263 * Returns the domain of the site, ie en.wikipedia.org
264 * Or false if it's not known.
268 * @return string|null
270 public function getDomain() {
271 $path = $this->getLinkPath();
273 if ( $path === null ) {
277 return parse_url( $path, PHP_URL_HOST
);
281 * Returns the protocol of the site.
285 * @throws MWException
288 public function getProtocol() {
289 $path = $this->getLinkPath();
291 if ( $path === null ) {
295 $protocol = parse_url( $path, PHP_URL_SCHEME
);
298 if ( $protocol === false ) {
299 throw new MWException( "failed to parse URL '$path'" );
303 if ( $protocol === null ) {
304 // Used for protocol relative URLs
312 * Sets the path used to construct links with.
313 * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
315 * @param string $fullUrl
319 * @throws MWException
321 public function setLinkPath( $fullUrl ) {
322 $type = $this->getLinkPathType();
324 if ( $type === null ) {
325 throw new MWException( "This Site does not support link paths." );
328 $this->setPath( $type, $fullUrl );
332 * Returns the path used to construct links with or false if there is no such path.
334 * Shall be equivalent to getPath( getLinkPathType() ).
336 * @return string|null
338 public function getLinkPath() {
339 $type = $this->getLinkPathType();
340 return $type === null ?
null: $this->getPath( $type );
344 * Returns the main path type, that is the type of the path that should generally be used to construct links
345 * to the target site.
347 * This default implementation returns Site::PATH_LINK as the default path type. Subclasses can override this
348 * to define a different default path type, or return false to disable site links.
352 * @return string|null
354 public function getLinkPathType() {
355 return self
::PATH_LINK
;
359 * Returns the full URL for the given page on the site.
360 * Or false if the needed information is not known.
362 * This generated URL is usually based upon the path returned by getLinkPath(),
363 * but this is not a requirement.
365 * This implementation returns a URL constructed using the path returned by getLinkPath().
369 * @param bool|String $pageName
371 * @return string|boolean false
373 public function getPageUrl( $pageName = false ) {
374 $url = $this->getLinkPath();
376 if ( $url === false ) {
380 if ( $pageName !== false ) {
381 $url = str_replace( '$1', rawurlencode( $pageName ), $url ) ;
388 * Returns $pageName without changes.
389 * Subclasses may override this to apply some kind of normalization.
391 * @see Site::normalizePageName
395 * @param string $pageName
399 public function normalizePageName( $pageName ) {
404 * Returns the type specific fields.
410 public function getExtraData() {
411 return $this->extraData
;
415 * Sets the type specific fields.
419 * @param array $extraData
421 public function setExtraData( array $extraData ) {
422 $this->extraData
= $extraData;
426 * Returns the type specific config.
432 public function getExtraConfig() {
433 return $this->extraConfig
;
437 * Sets the type specific config.
441 * @param array $extraConfig
443 public function setExtraConfig( array $extraConfig ) {
444 $this->extraConfig
= $extraConfig;
448 * Returns language code of the sites primary language.
449 * Or null if it's not known.
453 * @return string|null
455 public function getLanguageCode() {
456 return $this->languageCode
;
460 * Sets language code of the sites primary language.
464 * @param string $languageCode
466 public function setLanguageCode( $languageCode ) {
467 $this->languageCode
= $languageCode;
471 * Returns the set internal identifier for the site.
475 * @return string|null
477 public function getInternalId() {
478 return $this->internalId
;
482 * Sets the internal identifier for the site.
483 * This typically is a primary key in a db table.
487 * @param int|null $internalId
489 public function setInternalId( $internalId = null ) {
490 $this->internalId
= $internalId;
494 * Adds a local identifier.
498 * @param string $type
499 * @param string $identifier
501 public function addLocalId( $type, $identifier ) {
502 if ( $this->localIds
=== false ) {
503 $this->localIds
= array();
506 if ( !array_key_exists( $type, $this->localIds
) ) {
507 $this->localIds
[$type] = array();
510 if ( !in_array( $identifier, $this->localIds
[$type] ) ) {
511 $this->localIds
[$type][] = $identifier;
516 * Adds an interwiki id to the site.
520 * @param string $identifier
522 public function addInterwikiId( $identifier ) {
523 $this->addLocalId( self
::ID_INTERWIKI
, $identifier );
527 * Adds a navigation id to the site.
531 * @param string $identifier
533 public function addNavigationId( $identifier ) {
534 $this->addLocalId( self
::ID_EQUIVALENT
, $identifier );
538 * Returns the interwiki link identifiers that can be used for this site.
544 public function getInterwikiIds() {
545 return array_key_exists( self
::ID_INTERWIKI
, $this->localIds
) ?
$this->localIds
[self
::ID_INTERWIKI
] : array();
549 * Returns the equivalent link identifiers that can be used to make
550 * the site show up in interfaces such as the "language links" section.
556 public function getNavigationIds() {
557 return array_key_exists( self
::ID_EQUIVALENT
, $this->localIds
) ?
$this->localIds
[self
::ID_EQUIVALENT
] : array();
561 * Returns all local ids
567 public function getLocalIds() {
568 return $this->localIds
;
572 * Sets the path used to construct links with.
573 * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
577 * @param string $pathType
578 * @param string $fullUrl
580 * @throws MWException
582 public function setPath( $pathType, $fullUrl ) {
583 if ( !is_string( $fullUrl ) ) {
584 throw new MWException( '$fullUrl needs to be a string' );
587 if ( !array_key_exists( 'paths', $this->extraData
) ) {
588 $this->extraData
['paths'] = array();
591 $this->extraData
['paths'][$pathType] = $fullUrl;
595 * Returns the path of the provided type or false if there is no such path.
599 * @param string $pathType
601 * @return string|null
603 public function getPath( $pathType ) {
604 $paths = $this->getAllPaths();
605 return array_key_exists( $pathType, $paths ) ?
$paths[$pathType] : null;
609 * Returns the paths as associative array.
610 * The keys are path types, the values are the path urls.
616 public function getAllPaths() {
617 return array_key_exists( 'paths', $this->extraData
) ?
$this->extraData
['paths'] : array();
621 * Removes the path of the provided type if it's set.
625 * @param string $pathType
627 public function removePath( $pathType ) {
628 if ( array_key_exists( 'paths', $this->extraData
) ) {
629 unset( $this->extraData
['paths'][$pathType] );
636 * @param string $siteType
640 public static function newForType( $siteType ) {
643 if ( array_key_exists( $siteType, $wgSiteTypes ) ) {
644 return new $wgSiteTypes[$siteType]();
651 * @see Serializable::serialize
657 public function serialize() {
659 'globalid' => $this->globalId
,
660 'type' => $this->type
,
661 'group' => $this->group
,
662 'source' => $this->source
,
663 'language' => $this->languageCode
,
664 'localids' => $this->localIds
,
665 'config' => $this->extraConfig
,
666 'data' => $this->extraData
,
667 'forward' => $this->forward
,
668 'internalid' => $this->internalId
,
672 return serialize( $fields );
676 * @see Serializable::unserialize
680 * @param string $serialized
682 public function unserialize( $serialized ) {
683 $fields = unserialize( $serialized );
685 $this->__construct( $fields['type'] );
687 $this->setGlobalId( $fields['globalid'] );
688 $this->setGroup( $fields['group'] );
689 $this->setSource( $fields['source'] );
690 $this->setLanguageCode( $fields['language'] );
691 $this->localIds
= $fields['localids'];
692 $this->setExtraConfig( $fields['config'] );
693 $this->setExtraData( $fields['data'] );
694 $this->setForward( $fields['forward'] );
695 $this->setInternalId( $fields['internalid'] );
703 class SiteObject
extends Site
{}