includes/site/Site.php

   1 <?php
   2
   3 /**
   4  * Interface for site objects.
   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  * @licence GNU GPL v2+
  27  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  28  */
  29 interface Site {
  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         /**
  42          * Returns the global site identifier (ie enwiktionary).
  43          *
  44          * @since 1.21
  45          *
  46          * @return string
  47          */
  48         public function getGlobalId();
  49
  50         /**
  51          * Sets the global site identifier (ie enwiktionary).
  52          *
  53          * @since 1.21
  54          *
  55          * @param string $globalId
  56          */
  57         public function setGlobalId( $globalId );
  58
  59         /**
  60          * Returns the type of the site (ie mediawiki).
  61          *
  62          * @since 1.21
  63          *
  64          * @return string
  65          */
  66         public function getType();
  67
  68         /**
  69          * Sets the type of the site (ie mediawiki).
  70          * TODO: remove, we cannot change this after instantiation
  71          *
  72          * @since 1.21
  73          *
  74          * @param string $type
  75          */
  76         public function setType( $type );
  77
  78         /**
  79          * Gets the type of the site (ie wikipedia).
  80          *
  81          * @since 1.21
  82          *
  83          * @return string
  84          */
  85         public function getGroup();
  86
  87         /**
  88          * Sets the type of the site (ie wikipedia).
  89          *
  90          * @since 1.21
  91          *
  92          * @param string $group
  93          */
  94         public function setGroup( $group );
  95
  96         /**
  97          * Returns the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
  98          *
  99          * @since 1.21
 100          *
 101          * @return string
 102          */
 103         public function getSource();
 104
 105         /**
 106          * Sets the source of the site data (ie 'local', 'wikidata', 'my-magical-repo').
 107          *
 108          * @since 1.21
 109          *
 110          * @param string $source
 111          */
 112         public function setSource( $source );
 113
 114         /**
 115          * Returns the protocol of the site, ie 'http://', 'irc://', '//'
 116          * Or false if it's not known.
 117          *
 118          * @since 1.21
 119          *
 120          * @return string|false
 121          */
 122         public function getProtocol();
 123
 124         /**
 125          * Returns the domain of the site, ie en.wikipedia.org
 126          * Or false if it's not known.
 127          *
 128          * @since 1.21
 129          *
 130          * @return string|false
 131          */
 132         public function getDomain();
 133
 134         /**
 135          * Returns the full URL for the given page on the site.
 136          * Or false if the needed information is not known.
 137          *
 138          * This generated URL is usually based upon the path returned by getLinkPath(),
 139          * but this is not a requirement.
 140          *
 141          * @since 1.21
 142          * @see Site::getLinkPath()
 143          *
 144          * @param bool|String $page
 145          *
 146          * @return string|false
 147          */
 148         public function getPageUrl( $page = false );
 149
 150         /**
 151          * Returns language code of the sites primary language.
 152          * Or false if it's not known.
 153          *
 154          * @since 1.21
 155          *
 156          * @return string|false
 157          */
 158         public function getLanguageCode();
 159
 160         /**
 161          * Sets language code of the sites primary language.
 162          *
 163          * @since 1.21
 164          *
 165          * @param string $languageCode
 166          */
 167         public function setLanguageCode( $languageCode );
 168
 169         /**
 170          * Returns the normalized, canonical form of the given page name.
 171          * How normalization is performed or what the properties of a normalized name are depends on the site.
 172          * The general contract of this method is that the normalized form shall refer to the same content
 173          * as the original form, and any other page name referring to the same content will have the same normalized form.
 174          *
 175          * Note that this method may call out to the target site to perform the normalization, so it may be slow
 176          * and fail due to IO errors.
 177          *
 178          * @since 1.21
 179          *
 180          * @param string $pageName
 181          *
 182          * @return string the normalized page name
 183          */
 184         public function normalizePageName( $pageName );
 185
 186         /**
 187          * Returns the interwiki link identifiers that can be used for this site.
 188          *
 189          * @since 1.21
 190          *
 191          * @return array of string
 192          */
 193         public function getInterwikiIds();
 194
 195         /**
 196          * Returns the equivalent link identifiers that can be used to make
 197          * the site show up in interfaces such as the "language links" section.
 198          *
 199          * @since 1.21
 200          *
 201          * @return array of string
 202          */
 203         public function getNavigationIds();
 204
 205         /**
 206          * Adds an local identifier to the site.
 207          *
 208          * @since 1.21
 209          *
 210          * @param string $type The type of the identifier, element of the Site::ID_ enum
 211          * @param string $identifier
 212          */
 213         public function addLocalId( $type, $identifier );
 214
 215         /**
 216          * Adds an interwiki id to the site.
 217          *
 218          * @since 1.21
 219          *
 220          * @param string $identifier
 221          */
 222         public function addInterwikiId( $identifier );
 223
 224         /**
 225          * Adds a navigation id to the site.
 226          *
 227          * @since 1.21
 228          *
 229          * @param string $identifier
 230          */
 231         public function addNavigationId( $identifier );
 232
 233         /**
 234          * Saves the site.
 235          *
 236          * @since 1.21
 237          *
 238          * @param string|null $functionName
 239          */
 240         public function save( $functionName = null );
 241
 242         /**
 243          * Returns the internal ID of the site.
 244          *
 245          * @since 1.21
 246          *
 247          * @return integer
 248          */
 249         public function getInternalId();
 250
 251         /**
 252          * Sets the provided url as path of the specified type.
 253          *
 254          * @since 1.21
 255          *
 256          * @param string $pathType
 257          * @param string $fullUrl
 258          */
 259         public function setPath( $pathType, $fullUrl );
 260
 261         /**
 262          * Returns the path of the provided type or false if there is no such path.
 263          *
 264          * @since 1.21
 265          *
 266          * @param string $pathType
 267          *
 268          * @return string|false
 269          */
 270         public function getPath( $pathType );
 271
 272         /**
 273          * Sets the path used to construct links with.
 274          * Shall be equivalent to setPath( getLinkPathType(), $fullUrl ).
 275          *
 276          * @param string $fullUrl
 277          *
 278          * @since 1.21
 279          */
 280         public function setLinkPath( $fullUrl );
 281
 282         /**
 283          * Returns the path used to construct links with or false if there is no such path.
 284          * Shall be equivalent to getPath( getLinkPathType() ).
 285          *
 286          * @return string|false
 287          */
 288         public function getLinkPath();
 289
 290         /**
 291          * Returns the path type used to construct links with.
 292          *
 293          * @return string|false
 294          */
 295         public function getLinkPathType();
 296
 297         /**
 298          * Returns the paths as associative array.
 299          * The keys are path types, the values are the path urls.
 300          *
 301          * @since 1.21
 302          *
 303          * @return array of string
 304          */
 305         public function getAllPaths();
 306
 307         /**
 308          * Removes the path of the provided type if it's set.
 309          *
 310          * @since 1.21
 311          *
 312          * @param string $pathType
 313          */
 314         public function removePath( $pathType );
 315
 316 }