'Site' => __DIR__ . '/includes/site/Site.php',
'SiteArray' => __DIR__ . '/includes/site/SiteList.php',
'SiteConfiguration' => __DIR__ . '/includes/SiteConfiguration.php',
+ 'SiteImporter' => __DIR__ . '/includes/site/SiteImporter.php',
'SiteList' => __DIR__ . '/includes/site/SiteList.php',
'SiteListFileCache' => __DIR__ . '/includes/site/SiteListFileCache.php',
'SiteListFileCacheBuilder' => __DIR__ . '/includes/site/SiteListFileCacheBuilder.php',
--- /dev/null
+<?xml version="1.0" encoding="UTF-8" ?>
+<!--
+ This is an XML Schema description of the format
+ used by MediaWiki's exportSites.php and importSites.php
+ scripts.
+-->
+<schema xmlns="http://www.w3.org/2001/XMLSchema"
+ xmlns:mwsl="http://www.mediawiki.org/xml/sitelist-1.0/"
+ targetNamespace="http://www.mediawiki.org/xml/sitelist-1.0/"
+ elementFormDefault="qualified">
+
+ <annotation>
+ <documentation xml:lang="en">
+ MediaWiki's export format for site definitions.
+ </documentation>
+ </annotation>
+
+ <!-- Our root element -->
+ <element name="sites" type="mwsl:MediaWikiSiteListType">
+ <unique name="GlobalIDConstraint">
+ <selector xpath="mwsl:Site" />
+ <field xpath="mwsl:GlobalID" />
+ </unique>
+ </element>
+
+ <simpleType name="EmptyTagType">
+ <restriction base="string">
+ <length value="0"/>
+ </restriction>
+ </simpleType>
+
+ <complexType name="TypedIDType">
+ <simpleContent>
+ <extension base="NCName">
+ <attribute name="type" use="required" type="NCName" />
+ </extension>
+ </simpleContent>
+ </complexType>
+
+ <complexType name="TypedURIType">
+ <simpleContent>
+ <extension base="anyURI">
+ <attribute name="type" use="required" type="NCName" />
+ </extension>
+ </simpleContent>
+ </complexType>
+
+ <complexType name="MediaWikiSiteListType">
+ <sequence>
+ <element name="site" type="mwsl:SiteType"
+ minOccurs="0" maxOccurs="unbounded" />
+ </sequence>
+ <attribute name="version" type="string" use="optional" />
+ </complexType>
+
+ <complexType name="SiteType">
+ <choice maxOccurs="unbounded">
+ <element name="globalid" type="ID" minOccurs="1" maxOccurs="1" />
+ <element name="localid" type="mwsl:TypedIDType" minOccurs="0" />
+ <element name="group" type="NCName" minOccurs="0" maxOccurs="1" />
+ <element name="source" type="NCName" minOccurs="0" maxOccurs="1" />
+ <element name="forward" type="mwsl:EmptyTagType" minOccurs="0" maxOccurs="1" />
+ <element name="path" type="mwsl:TypedURIType" minOccurs="0" />
+ </choice>
+ <attribute name="type" use="optional" type="NCName" />
+ </complexType>
+
+</schema>
--- /dev/null
+This document describes the XML format used to represent information about external sites known
+to a MediaWiki installation. This information about external sites is used to allow "inter-wiki"
+links, cross-language navigation, as well as close integration via direct access to the other
+site's web API or even directly to their database.
+
+Lists of external sites can be imported and exported using the importSites.php and exportSites.php
+scripts. In the database, external sites are described by the sites and site_ids tables.
+
+The formal specification of the format used by importSites.php and exportSites.php can be found in
+the sitelist-1.0.xsd file. Below is an example and a brief description of what the individual XML
+elements and attributes mean:
+
+
+ <sites version="1.0">
+ <site>
+ <globalid>acme.com</globalid>
+ <localid type="interwiki">acme</localid>
+ <group>Vendor</group>
+ <path type="link">http://acme.com/</path>
+ <source>meta.wikimedia.org</source>
+ </site>
+ <site type="mediawiki">
+ <globalid>de.wikidik.example</globalid>
+ <localid type="equivalent">de</localid>
+ <group>Dictionary</group>
+ <forward/>
+ <path type="page_path">http://acme.com/</path>
+ </site>
+ </sites>
+
+
+The XML elements are used as follows:
+
+* sites: The root element, containing a set of site tags. May have a version attribute with the value 1.0.
+* site: A site entry, representing an external website. May have a type attribute with one of the following values:
+** ''unknown'': (default) any website
+** ''mediawiki'': A MediaWiki site
+* globalid: A unique identifier for the site. For a given site, the same unique global ID must be used across all wikis in a wiki farm (aka wiki family).
+* localid: An identifier for the site, for use on the local wiki. Multiple local IDs may be assigned to a given site. The same local ID can be used to refer to different sites by different wikis on the same farm/family. The localid element may have a type attribute with one of the following values:
+** interwiki: Used as an "interwiki" link prefix, for creating cross-wiki links.
+** equivalent: Used as a "language" link prefix, for cross-linking equivalent content in different languages.
+* group: The site group (e.g. wiki family) the site belongs to.
+* path: A URL template for accessing resources on the site. Several paths may be defined for a given site, for accessing different kinds of resources, identified by the type attribute, using one of the following values:
+** link: Generic URL template, often the document root.
+** page_path: (for mediawiki sites) URL template for wiki pages (corresponds to the target wiki's $wgArticlePath setting)
+** file_path: (for mediawiki sites) URL pattern for application entry points and resources (corresponds to the target wiki's $wgScriptPath setting).
+* forward: Whether using a prefix defined by a localid tag in the URL will cause the request to be redirected to the corresponding page on the target wiki (currently unused). E.g. whether http://wiki.acme.com/wiki/foo:Buzz should be forwarded to http://wiki.foo.com/read/Buzz. (CAVEAT: not yet implement, can be specified but has no effect)
\ No newline at end of file
--- /dev/null
+<?php
+
+/**
+ * Utility for importing site entries from XML.
+ * For the expected format of the input, see docs/sitelist.txt and docs/sitelist-1.0.xsd.
+ *
+ * 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.25
+ *
+ * @file
+ * @ingroup Site
+ *
+ * @license GNU GPL v2+
+ * @author Daniel Kinzler
+ */
+class SiteImporter {
+
+ /**
+ * @var SiteStore
+ */
+ private $store;
+
+ /**
+ * @var callable|null
+ */
+ private $exceptionCallback;
+
+ /**
+ * @param SiteStore $store
+ */
+ public function __construct( SiteStore $store ) {
+ $this->store = $store;
+ }
+
+ /**
+ * @return callable
+ */
+ public function getExceptionCallback() {
+ return $this->exceptionCallback;
+ }
+
+ /**
+ * @param callable $exceptionCallback
+ */
+ public function setExceptionCallback( $exceptionCallback ) {
+ $this->exceptionCallback = $exceptionCallback;
+ }
+
+ /**
+ * @param string $file
+ */
+ public function importFromFile( $file ) {
+ $xml = file_get_contents( $file );
+
+ if ( $xml === false ) {
+ throw new RuntimeException( 'Failed to read ' . $file . '!' );
+ }
+
+ $this->importFromXML( $xml );
+ }
+
+ /**
+ * @param string $xml
+ *
+ * @throws InvalidArgumentException
+ */
+ public function importFromXML( $xml ) {
+ $document = new DOMDocument();
+
+ $oldLibXmlErrors = libxml_use_internal_errors( true );
+ $ok = $document->loadXML( $xml, LIBXML_NONET );
+
+ if ( !$ok ) {
+ $errors = libxml_get_errors();
+ libxml_use_internal_errors( $oldLibXmlErrors );
+
+ foreach ( $errors as $error ) {
+ /** @var LibXMLError $error */
+ throw new InvalidArgumentException( 'Malformed XML: ' . $error->message . ' in line ' . $error->line );
+ }
+
+ throw new InvalidArgumentException( 'Malformed XML!' );
+ }
+
+ libxml_use_internal_errors( $oldLibXmlErrors );
+ $this->importFromDOM( $document->documentElement );
+ }
+
+ /**
+ * @param DOMElement $root
+ */
+ private function importFromDOM( DOMElement $root ) {
+ $sites = $this->makeSiteList( $root );
+ $this->store->saveSites( $sites );
+ }
+
+ /**
+ * @param DOMElement $root
+ *
+ * @return Site[]
+ */
+ private function makeSiteList( DOMElement $root ) {
+ $sites = array();
+
+ // Old sites, to get the row IDs that correspond to the global site IDs.
+ // TODO: Get rid of internal row IDs, they just get in the way. Get rid of ORMRow, too.
+ $oldSites = $this->store->getSites();
+
+ $current = $root->firstChild;
+ while ( $current ) {
+ if ( $current instanceof DOMElement && $current->tagName === 'site' ) {
+ try {
+ $site = $this->makeSite( $current );
+ $key = $site->getGlobalId();
+
+ if ( $oldSites->hasSite( $key ) ) {
+ $oldSite = $oldSites->getSite( $key );
+ $site->setInternalId( $oldSite->getInternalId() );
+ }
+
+ $sites[$key] = $site;
+ } catch ( Exception $ex ) {
+ $this->handleException( $ex );
+ }
+ }
+
+ $current = $current->nextSibling;
+ }
+
+ return $sites;
+ }
+
+ /**
+ * @param DOMElement $siteElement
+ *
+ * @return Site
+ * @throws InvalidArgumentException
+ */
+ public function makeSite( DOMElement $siteElement ) {
+ if ( $siteElement->tagName !== 'site' ) {
+ throw new InvalidArgumentException( 'Expected <site> tag, found ' . $siteElement->tagName );
+ }
+
+ $type = $this->getAttributeValue( $siteElement, 'type', Site::TYPE_UNKNOWN );
+ $site = Site::newForType( $type );
+
+ $site->setForward( $this->hasChild( $siteElement, 'forward' ) );
+ $site->setGlobalId( $this->getChildText( $siteElement, 'globalid' ) );
+ $site->setGroup( $this->getChildText( $siteElement, 'group', Site::GROUP_NONE ) );
+ $site->setSource( $this->getChildText( $siteElement, 'source', Site::SOURCE_LOCAL ) );
+
+ $pathTags = $siteElement->getElementsByTagName( 'path' );
+ for ( $i = 0; $i < $pathTags->length; $i++ ) {
+ $pathElement = $pathTags->item( $i );
+ $pathType = $this->getAttributeValue( $pathElement, 'type' );
+ $path = $pathElement->textContent;
+
+ $site->setPath( $pathType, $path );
+ }
+
+ $idTags = $siteElement->getElementsByTagName( 'localid' );
+ for ( $i = 0; $i < $idTags->length; $i++ ) {
+ $idElement = $idTags->item( $i );
+ $idType = $this->getAttributeValue( $idElement, 'type' );
+ $id = $idElement->textContent;
+
+ $site->addLocalId( $idType, $id );
+ }
+
+ //@todo: import <data>
+ //@todo: import <config>
+
+ return $site;
+ }
+
+ /**
+ * @param DOMElement $element
+ * @param $name
+ * @param string|null|bool $default
+ *
+ * @return null|string
+ * @throws MWException If the attribute is not found and no default is provided
+ */
+ private function getAttributeValue( DOMElement $element, $name, $default = false ) {
+ $node = $element->getAttributeNode( $name );
+
+ if ( !$node ) {
+ if ( $default !== false ) {
+ return $default;
+ } else {
+ throw new MWException( 'Required ' . $name . ' attribute not found in <' . $element->tagName . '> tag' );
+ }
+ }
+
+ return $node->textContent;
+ }
+
+ /**
+ * @param DOMElement $element
+ * @param string $name
+ * @param string|null|bool $default
+ *
+ * @return null|string
+ * @throws MWException If the child element is not found and no default is provided
+ */
+ private function getChildText( DOMElement $element, $name, $default = false ) {
+ $elements = $element->getElementsByTagName( $name );
+
+ if ( $elements->length < 1 ) {
+ if ( $default !== false ) {
+ return $default;
+ } else {
+ throw new MWException( 'Required <' . $name . '> tag not found inside <' . $element->tagName . '> tag' );
+ }
+ }
+
+ $node = $elements->item( 0 );
+ return $node->textContent;
+ }
+
+ /**
+ * @param DOMElement $element
+ * @param string $name
+ *
+ * @return bool
+ * @throws MWException
+ */
+ private function hasChild( DOMElement $element, $name ) {
+ return $this->getChildText( $element, $name, null ) !== null;
+ }
+
+ /**
+ * @param Exception $ex
+ */
+ private function handleException( Exception $ex ) {
+ if ( $this->exceptionCallback ) {
+ call_user_func( $this->exceptionCallback, $ex );
+ } else {
+ wfLogWarning( $ex->getMessage() );
+ }
+ }
+
+}
--- /dev/null
+<?php
+
+$basePath = getenv( 'MW_INSTALL_PATH' ) !== false ? getenv( 'MW_INSTALL_PATH' ) : __DIR__ . '/..';
+
+require_once $basePath . '/maintenance/Maintenance.php';
+
+/**
+ * Maintenance script for importing site definitions from XML into the sites table.
+ *
+ * @since 1.25
+ *
+ * @license GNU GPL v2+
+ * @author Daniel Kinzler
+ */
+class ImportSites extends Maintenance {
+
+ public function __construct() {
+ $this->mDescription = 'Imports site definitions from XML into the sites table.';
+
+ $this->addArg( 'file', 'An XML file containing site definitions (see docs/sitelist.txt). Use "php://stdin" to read from stdin.', true );
+
+ parent::__construct();
+ }
+
+
+ /**
+ * Do the import.
+ */
+ public function execute() {
+ $file = $this->getArg( 0 );
+
+ $importer = new SiteImporter( SiteSQLStore::newInstance() );
+ $importer->setExceptionCallback( array( $this, 'reportException' ) );
+
+ $importer->importFromFile( $file );
+
+ $this->output( "Done.\n" );
+ }
+
+ /**
+ * Outputs a message via the output() method.
+ *
+ * @param Exception $ex
+ */
+ public function reportException( Exception $ex ) {
+ $msg = $ex->getMessage();
+ $this->output( "$msg\n" );
+ }
+}
+
+$maintClass = 'ImportSites';
+require_once( RUN_MAINTENANCE_IF_MAIN );
--- /dev/null
+<?php
+
+/**
+ * Tests for the SiteImporter class.
+ *
+ * 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
+ *
+ * @file
+ *
+ * @ingroup Site
+ * @ingroup Test
+ *
+ * @group Site
+ *
+ * @covers SiteImporter
+ *
+ * @licence GNU GPL v2+
+ * @author Daniel Kinzler
+ */
+class SiteImporterTest extends PHPUnit_Framework_TestCase {
+
+ private function newSiteImporter( array $expectedSites, $errorCount ) {
+ $store = $this->getMock( 'SiteStore' );
+
+ $self = $this;
+ $store->expects( $this->once() )
+ ->method( 'saveSites' )
+ ->will( $this->returnCallback( function ( $sites ) use ( $expectedSites, $self ) {
+ $self->assertSitesEqual( $expectedSites, $sites );
+ } ) );
+
+ $store->expects( $this->any() )
+ ->method( 'getSites' )
+ ->will( $this->returnValue( new SiteList() ) );
+
+ $errorHandler = $this->getMock( 'Psr\Log\LoggerInterface' );
+ $errorHandler->expects( $this->exactly( $errorCount ) )
+ ->method( 'error' );
+
+ $importer = new SiteImporter( $store );
+ $importer->setExceptionCallback( array( $errorHandler, 'error' ) );
+
+ return $importer;
+ }
+
+ public function assertSitesEqual( $expected, $actual, $message = '' ) {
+ $this->assertEquals(
+ $this->getSerializedSiteList( $expected ),
+ $this->getSerializedSiteList( $actual ),
+ $message
+ );
+ }
+
+ public function provideImportFromXML() {
+ $foo = Site::newForType( Site::TYPE_UNKNOWN );
+ $foo->setGlobalId( 'Foo' );
+
+ $acme = Site::newForType( Site::TYPE_UNKNOWN );
+ $acme->setGlobalId( 'acme.com' );
+ $acme->setGroup( 'Test' );
+ $acme->addLocalId( Site::ID_INTERWIKI, 'acme' );
+ $acme->setPath( Site::PATH_LINK, 'http://acme.com/' );
+
+ $dewiki = Site::newForType( Site::TYPE_MEDIAWIKI );
+ $dewiki->setGlobalId( 'dewiki' );
+ $dewiki->setGroup( 'wikipedia' );
+ $dewiki->setForward( true );
+ $dewiki->addLocalId( Site::ID_INTERWIKI, 'wikipedia' );
+ $dewiki->addLocalId( Site::ID_EQUIVALENT, 'de' );
+ $dewiki->setPath( Site::PATH_LINK, 'http://de.wikipedia.org/w/' );
+ $dewiki->setPath( MediaWikiSite::PATH_PAGE, 'http://de.wikipedia.org/wiki/' );
+ $dewiki->setSource( 'meta.wikimedia.org' );
+
+ return array(
+ 'empty' => array(
+ '<sites></sites>',
+ array(),
+ ),
+ 'no sites' => array(
+ '<sites><Foo><globalid>Foo</globalid></Foo><Bar><quux>Bla</quux></Bar></sites>',
+ array(),
+ ),
+ 'minimal' => array(
+ '<sites>' .
+ '<site><globalid>Foo</globalid></site>' .
+ '</sites>',
+ array( $foo ),
+ ),
+ 'full' => array(
+ '<sites>' .
+ '<site><globalid>Foo</globalid></site>' .
+ '<site>' .
+ '<globalid>acme.com</globalid>' .
+ '<localid type="interwiki">acme</localid>' .
+ '<group>Test</group>' .
+ '<path type="link">http://acme.com/</path>' .
+ '</site>' .
+ '<site type="mediawiki">' .
+ '<source>meta.wikimedia.org</source>' .
+ '<globalid>dewiki</globalid>' .
+ '<localid type="interwiki">wikipedia</localid>' .
+ '<localid type="equivalent">de</localid>' .
+ '<group>wikipedia</group>' .
+ '<forward/>' .
+ '<path type="link">http://de.wikipedia.org/w/</path>' .
+ '<path type="page_path">http://de.wikipedia.org/wiki/</path>' .
+ '</site>' .
+ '</sites>',
+ array( $foo, $acme, $dewiki ),
+ ),
+ 'skip' => array(
+ '<sites>' .
+ '<site><globalid>Foo</globalid></site>' .
+ '<site><barf>Foo</barf></site>' .
+ '<site>' .
+ '<globalid>acme.com</globalid>' .
+ '<localid type="interwiki">acme</localid>' .
+ '<silly>boop!</silly>' .
+ '<group>Test</group>' .
+ '<path type="link">http://acme.com/</path>' .
+ '</site>' .
+ '</sites>',
+ array( $foo, $acme ),
+ 1
+ ),
+ );
+ }
+
+ /**
+ * @dataProvider provideImportFromXML
+ */
+ public function testImportFromXML( $xml, array $expectedSites, $errorCount = 0 ) {
+ $importer = $this->newSiteImporter( $expectedSites, $errorCount );
+ $importer->importFromXML( $xml );
+ }
+
+ public function testImportFromXML_malformed() {
+ $this->setExpectedException( 'Exception' );
+
+ $store = $this->getMock( 'SiteStore' );
+ $importer = new SiteImporter( $store );
+ $importer->importFromXML( 'THIS IS NOT XML' );
+ }
+
+ public function testImportFromFile() {
+ $foo = Site::newForType( Site::TYPE_UNKNOWN );
+ $foo->setGlobalId( 'Foo' );
+
+ $acme = Site::newForType( Site::TYPE_UNKNOWN );
+ $acme->setGlobalId( 'acme.com' );
+ $acme->setGroup( 'Test' );
+ $acme->addLocalId( Site::ID_INTERWIKI, 'acme' );
+ $acme->setPath( Site::PATH_LINK, 'http://acme.com/' );
+
+ $dewiki = Site::newForType( Site::TYPE_MEDIAWIKI );
+ $dewiki->setGlobalId( 'dewiki' );
+ $dewiki->setGroup( 'wikipedia' );
+ $dewiki->setForward( true );
+ $dewiki->addLocalId( Site::ID_INTERWIKI, 'wikipedia' );
+ $dewiki->addLocalId( Site::ID_EQUIVALENT, 'de' );
+ $dewiki->setPath( Site::PATH_LINK, 'http://de.wikipedia.org/w/' );
+ $dewiki->setPath( MediaWikiSite::PATH_PAGE, 'http://de.wikipedia.org/wiki/' );
+ $dewiki->setSource( 'meta.wikimedia.org' );
+
+ $importer = $this->newSiteImporter( array( $foo, $acme, $dewiki ), 0 );
+
+ $file = __DIR__ . '/SiteImporterTest.xml';
+ $importer->importFromFile( $file );
+ }
+
+ /**
+ * @param Site[] $sites
+ *
+ * @return array[]
+ */
+ private function getSerializedSiteList( $sites ) {
+ $serialized = array();
+
+ foreach ( $sites as $site ) {
+ $key = $site->getGlobalId();
+ $data = unserialize( $site->serialize() );
+
+ $serialized[$key] = $data;
+ }
+
+ return $serialized;
+ }
+}
--- /dev/null
+<sites version="1.0" xmlns="http://www.mediawiki.org/xml/sitelist-1.0/">
+ <site><globalid>Foo</globalid></site>
+ <site>
+ <globalid>acme.com</globalid>
+ <localid type="interwiki">acme</localid>
+ <group>Test</group>
+ <path type="link">http://acme.com/</path>
+ </site>
+ <site type="mediawiki">
+ <source>meta.wikimedia.org</source>
+ <globalid>dewiki</globalid>
+ <localid type="interwiki">wikipedia</localid>
+ <localid type="equivalent">de</localid>
+ <group>wikipedia</group>
+ <forward/>
+ <path type="link">http://de.wikipedia.org/w/</path>
+ <path type="page_path">http://de.wikipedia.org/wiki/</path>
+ </site>
+</sites>