Merge "Typo fix"

[mediawiki.git] / includes / site / Site.php

<?php

/**
 * Represents a single site.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 * http://www.gnu.org/copyleft/gpl.html
 *
 * @since 1.21
 *
 * @file
 * @ingroup Site
 *
 * @license GNU GPL v2+
 * @author Jeroen De Dauw < jeroendedauw@gmail.com >
 */
class Site implements Serializable {

        const TYPE_UNKNOWN = 'unknown';
        const TYPE_MEDIAWIKI = 'mediawiki';

        const GROUP_NONE = 'none';

        const ID_INTERWIKI = 'interwiki';
        const ID_EQUIVALENT = 'equivalent';

        const SOURCE_LOCAL = 'local';

        const PATH_LINK = 'link';

        /**
         * A version ID that identifies the serialization structure used by getSerializationData()
         * and unserialize(). This is useful for constructing cache keys in cases where the cache relies
         * on serialization for storing the SiteList.
         *
         * @var string A string uniquely identifying the version of the serialization structure.
         */
        const SERIAL_VERSION_ID = '2013-01-23';

        /**
         * @since 1.21
         *
         * @var string|null
         */
        protected $globalId = null;

        /**
         * @since 1.21
         *
         * @var string
         */
        protected $type = self::TYPE_UNKNOWN;

        /**
         * @since 1.21
         *
         * @var string
         */
        protected $group = self::GROUP_NONE;

        /**
         * @since 1.21
         *
         * @var string
         */
        protected $source = self::SOURCE_LOCAL;

        /**
         * @since 1.21
         *
         * @var string|null
         */
        protected $languageCode = null;

        /**
         * Holds the local ids for this site.
         * local id type => [ ids for this type (strings) ]
         *
         * @since 1.21
         *
         * @var array[]
         */
        protected $localIds = array();

        /**
         * @since 1.21
         *
         * @var array
         */
        protected $extraData = array();

        /**
         * @since 1.21
         *
         * @var array
         */
        protected $extraConfig = array();

        /**
         * @since 1.21
         *
         * @var bool
         */
        protected $forward = false;

        /**
         * @since 1.21
         *
         * @var int|null
         */
        protected $internalId = null;

        /**
         * Constructor.
         *
         * @since 1.21
         *
         * @param string $type
         */
        public function __construct( $type = self::TYPE_UNKNOWN ) {
                $this->type = $type;
        }

        /**
         * Returns the global site identifier (ie enwiktionary).
         *
         * @since 1.21
         *
         * @return string|null
         */
        public function getGlobalId() {
                return $this->globalId;
        }

        /**
         * Sets the global site identifier (ie enwiktionary).
         *
         * @since 1.21
         *
         * @param string|null $globalId
         *
         * @throws MWException
         */
        public function setGlobalId( $globalId ) {
                if ( $globalId !== null && !is_string( $globalId ) ) {
                        throw new MWException( '$globalId needs to be string or null' );
                }

                $this->globalId = $globalId;
        }

        /**
         * Returns the type of the site (ie mediawiki).
         *
         * @since 1.21
         *
         * @return string
         */
        public function getType() {
                return $this->type;
        }

        /**
         * Gets the type of the site (ie wikipedia).
         *
         * @since 1.21
         *
         * @return string
         */
        public function getGroup() {
                return $this->group;
        }

        /**
         * Sets the type of the site (ie wikipedia).
         *
         * @since 1.21
         *
         * @param string $group
         *
         * @throws MWException
         */
        public function setGroup( $group ) {
                if ( !is_string( $group ) ) {
                        throw new MWException( '$group needs to be a string' );
                }

                $this->group = $group;
        }

        /**
         * Returns the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
         *
         * @since 1.21
         *
         * @return string
         */
        public function getSource() {
                return $this->source;
        }

        /**
         * Sets the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
         *
         * @since 1.21
         *
         * @param string $source
         *
         * @throws MWException
         */
        public function setSource( $source ) {
                if ( !is_string( $source ) ) {
                        throw new MWException( '$source needs to be a string' );
                }

                $this->source = $source;
        }

        /**
         * Gets if site.tld/path/key:pageTitle should forward users to  the page on
         * the actual site, where "key" is the local identifier.
         *
         * @since 1.21
         *
         * @return boolean
         */
        public function shouldForward() {
                return $this->forward;
        }

        /**
         * Sets if site.tld/path/key:pageTitle should forward users to  the page on
         * the actual site, where "key" is the local identifier.
         *
         * @since 1.21
         *
         * @param boolean $shouldForward
         *
         * @throws MWException
         */
        public function setForward( $shouldForward ) {
                if ( !is_bool( $shouldForward ) ) {
                        throw new MWException( '$shouldForward needs to be a boolean' );
                }

                $this->forward = $shouldForward;
        }

        /**
         * Returns the domain of the site, ie en.wikipedia.org
         * Or false if it's not known.
         *
         * @since 1.21
         *
         * @return string|null
         */
        public function getDomain() {
                $path = $this->getLinkPath();

                if ( $path === null ) {
                        return null;
                }

                return parse_url( $path, PHP_URL_HOST );
        }

        /**
         * Returns the protocol of the site.
         *
         * @since 1.21
         *
         * @throws MWException
         * @return string
         */
        public function getProtocol() {
                $path = $this->getLinkPath();

                if ( $path === null ) {
                        return '';
                }

                $protocol = parse_url( $path, PHP_URL_SCHEME );

                // Malformed URL
                if ( $protocol === false ) {
                        throw new MWException( "failed to parse URL '$path'" );
                }

                // No schema
                if ( $protocol === null ) {
                        // Used for protocol relative URLs
                        $protocol = '';
                }

                return $protocol;
        }

        /**
         * Sets the path used to construct links with.
         * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
         *
         * @param string $fullUrl
         *
         * @since 1.21
         *
         * @throws MWException
         */
        public function setLinkPath( $fullUrl ) {
                $type = $this->getLinkPathType();

                if ( $type === null ) {
                        throw new MWException( "This Site does not support link paths." );
                }

                $this->setPath( $type, $fullUrl );
        }

        /**
         * Returns the path used to construct links with or false if there is no such path.
         *
         * Shall be equivalent to getPath( getLinkPathType() ).
         *
         * @return string|null
         */
        public function getLinkPath() {
                $type = $this->getLinkPathType();
                return $type === null ? null: $this->getPath( $type );
        }

        /**
         * Returns the main path type, that is the type of the path that should generally be used to construct links
         * to the target site.
         *
         * This default implementation returns Site::PATH_LINK as the default path type. Subclasses can override this
         * to define a different default path type, or return false to disable site links.
         *
         * @since 1.21
         *
         * @return string|null
         */
        public function getLinkPathType() {
                return self::PATH_LINK;
        }

        /**
         * Returns the full URL for the given page on the site.
         * Or false if the needed information is not known.
         *
         * This generated URL is usually based upon the path returned by getLinkPath(),
         * but this is not a requirement.
         *
         * This implementation returns a URL constructed using the path returned by getLinkPath().
         *
         * @since 1.21
         *
         * @param bool|String $pageName
         *
         * @return string|boolean false
         */
        public function getPageUrl( $pageName = false ) {
                $url = $this->getLinkPath();

                if ( $url === false ) {
                        return false;
                }

                if ( $pageName !== false ) {
                        $url = str_replace( '$1', rawurlencode( $pageName ), $url );
                }

                return $url;
        }

        /**
         * Returns $pageName without changes.
         * Subclasses may override this to apply some kind of normalization.
         *
         * @see Site::normalizePageName
         *
         * @since 1.21
         *
         * @param string $pageName
         *
         * @return string
         */
        public function normalizePageName( $pageName ) {
                return $pageName;
        }

        /**
         * Returns the type specific fields.
         *
         * @since 1.21
         *
         * @return array
         */
        public function getExtraData() {
                return $this->extraData;
        }

        /**
         * Sets the type specific fields.
         *
         * @since 1.21
         *
         * @param array $extraData
         */
        public function setExtraData( array $extraData ) {
                $this->extraData = $extraData;
        }

        /**
         * Returns the type specific config.
         *
         * @since 1.21
         *
         * @return array
         */
        public function getExtraConfig() {
                return $this->extraConfig;
        }

        /**
         * Sets the type specific config.
         *
         * @since 1.21
         *
         * @param array $extraConfig
         */
        public function setExtraConfig( array $extraConfig ) {
                $this->extraConfig = $extraConfig;
        }

        /**
         * Returns language code of the sites primary language.
         * Or null if it's not known.
         *
         * @since 1.21
         *
         * @return string|null
         */
        public function getLanguageCode() {
                return $this->languageCode;
        }

        /**
         * Sets language code of the sites primary language.
         *
         * @since 1.21
         *
         * @param string $languageCode
         */
        public function setLanguageCode( $languageCode ) {
                $this->languageCode = $languageCode;
        }

        /**
         * Returns the set internal identifier for the site.
         *
         * @since 1.21
         *
         * @return string|null
         */
        public function getInternalId() {
                return $this->internalId;
        }

        /**
         * Sets the internal identifier for the site.
         * This typically is a primary key in a db table.
         *
         * @since 1.21
         *
         * @param int|null $internalId
         */
        public function setInternalId( $internalId = null ) {
                $this->internalId = $internalId;
        }

        /**
         * Adds a local identifier.
         *
         * @since 1.21
         *
         * @param string $type
         * @param string $identifier
         */
        public function addLocalId( $type, $identifier ) {
                if ( $this->localIds === false ) {
                        $this->localIds = array();
                }

                if ( !array_key_exists( $type, $this->localIds ) ) {
                        $this->localIds[$type] = array();
                }

                if ( !in_array( $identifier, $this->localIds[$type] ) ) {
                        $this->localIds[$type][] = $identifier;
                }
        }

        /**
         * Adds an interwiki id to the site.
         *
         * @since 1.21
         *
         * @param string $identifier
         */
        public function addInterwikiId( $identifier ) {
                $this->addLocalId( self::ID_INTERWIKI, $identifier );
        }

        /**
         * Adds a navigation id to the site.
         *
         * @since 1.21
         *
         * @param string $identifier
         */
        public function addNavigationId( $identifier ) {
                $this->addLocalId( self::ID_EQUIVALENT, $identifier );
        }

        /**
         * Returns the interwiki link identifiers that can be used for this site.
         *
         * @since 1.21
         *
         * @return string[]
         */
        public function getInterwikiIds() {
                return array_key_exists( self::ID_INTERWIKI, $this->localIds ) ? $this->localIds[self::ID_INTERWIKI] : array();
        }

        /**
         * Returns the equivalent link identifiers that can be used to make
         * the site show up in interfaces such as the "language links" section.
         *
         * @since 1.21
         *
         * @return string[]
         */
        public function getNavigationIds() {
                return array_key_exists( self::ID_EQUIVALENT, $this->localIds ) ? $this->localIds[self::ID_EQUIVALENT] : array();
        }

        /**
         * Returns all local ids
         *
         * @since 1.21
         *
         * @return array[]
         */
        public function getLocalIds() {
                return $this->localIds;
        }

        /**
         * Sets the path used to construct links with.
         * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
         *
         * @since 1.21
         *
         * @param string $pathType
         * @param string $fullUrl
         *
         * @throws MWException
         */
        public function setPath( $pathType, $fullUrl ) {
                if ( !is_string( $fullUrl ) ) {
                        throw new MWException( '$fullUrl needs to be a string' );
                }

                if ( !array_key_exists( 'paths', $this->extraData ) ) {
                        $this->extraData['paths'] = array();
                }

                $this->extraData['paths'][$pathType] = $fullUrl;
        }

        /**
         * Returns the path of the provided type or false if there is no such path.
         *
         * @since 1.21
         *
         * @param string $pathType
         *
         * @return string|null
         */
        public function getPath( $pathType ) {
                $paths = $this->getAllPaths();
                return array_key_exists( $pathType, $paths ) ? $paths[$pathType] : null;
        }

        /**
         * Returns the paths as associative array.
         * The keys are path types, the values are the path urls.
         *
         * @since 1.21
         *
         * @return string[]
         */
        public function getAllPaths() {
                return array_key_exists( 'paths', $this->extraData ) ? $this->extraData['paths'] : array();
        }

        /**
         * Removes the path of the provided type if it's set.
         *
         * @since 1.21
         *
         * @param string $pathType
         */
        public function removePath( $pathType ) {
                if ( array_key_exists( 'paths', $this->extraData ) ) {
                        unset( $this->extraData['paths'][$pathType] );
                }
        }

        /**
         * @since 1.21
         *
         * @param string $siteType
         *
         * @return Site
         */
        public static function newForType( $siteType ) {
                global $wgSiteTypes;

                if ( array_key_exists( $siteType, $wgSiteTypes ) ) {
                        return new $wgSiteTypes[$siteType]();
                }

                return new Site();
        }

        /**
         * @see Serializable::serialize
         *
         * @since 1.21
         *
         * @return string
         */
        public function serialize() {
                $fields = array(
                        'globalid' => $this->globalId,
                        'type' => $this->type,
                        'group' => $this->group,
                        'source' => $this->source,
                        'language' => $this->languageCode,
                        'localids' => $this->localIds,
                        'config' => $this->extraConfig,
                        'data' => $this->extraData,
                        'forward' => $this->forward,
                        'internalid' => $this->internalId,

                );

                return serialize( $fields );
        }

        /**
         * @see Serializable::unserialize
         *
         * @since 1.21
         *
         * @param string $serialized
         */
        public function unserialize( $serialized ) {
                $fields = unserialize( $serialized );

                $this->__construct( $fields['type'] );

                $this->setGlobalId( $fields['globalid'] );
                $this->setGroup( $fields['group'] );
                $this->setSource( $fields['source'] );
                $this->setLanguageCode( $fields['language'] );
                $this->localIds = $fields['localids'];
                $this->setExtraConfig( $fields['config'] );
                $this->setExtraData( $fields['data'] );
                $this->setForward( $fields['forward'] );
                $this->setInternalId( $fields['internalid'] );
        }

}

/**
 * @deprecated
 */
class SiteObject extends Site {}