includes/site/MediaWikiSite.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 namespace MediaWiki\Site;
  22
  23 use MediaWiki\Title\Title;
  24 use RuntimeException;
  25
  26 /**
  27  * Class representing a MediaWiki site.
  28  *
  29  * @since 1.21
  30  * @ingroup Site
  31  * @author John Erling Blad < jeblad@gmail.com >
  32  * @author Daniel Kinzler
  33  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  34  */
  35 class MediaWikiSite extends Site {
  36         /** The script path of a site, e.g. `/w/$1` related to $wgScriptPath */
  37         public const PATH_FILE = 'file_path';
  38         /** The article path of a site, e.g. `/wiki/$1` like $wgArticlePath */
  39         public const PATH_PAGE = 'page_path';
  40
  41         /**
  42          * @since 1.21
  43          * @param string $type
  44          */
  45         public function __construct( $type = self::TYPE_MEDIAWIKI ) {
  46                 parent::__construct( $type );
  47         }
  48
  49         /**
  50          * Get the database form of the given title.
  51          *
  52          * @since 1.21
  53          * @param string $title The target page's title, in normalized form.
  54          * @return string
  55          */
  56         public function toDBKey( $title ) {
  57                 return str_replace( ' ', '_', $title );
  58         }
  59
  60         /**
  61          * Get the normalized form of the given page title.
  62          *
  63          * This uses to normalization rules of the given site. If $followRedirect is set to true
  64          * and the given title is a redirect, the redirect will be resolved and
  65          * the redirect target is returned.
  66          * Only titles of existing pages will be returned.
  67          *
  68          * @note This actually makes an API request to the remote site, so beware
  69          *   that this function is slow and depends on an external service.
  70          *
  71          * @note If MW_PHPUNIT_TEST is defined, the call to the external site is
  72          *   skipped, and the title is normalized using the local normalization
  73          *   rules as implemented by the Title class.
  74          *
  75          * @see Site::normalizePageName
  76          * @since 1.21
  77          * @since 1.37 Added $followRedirect
  78          * @param string $pageName
  79          * @param int $followRedirect either MediaWikiPageNameNormalizer::FOLLOW_REDIRECT or
  80          *  MediaWikiPageNameNormalizer::NOFOLLOW_REDIRECT
  81          * @return string|false The normalized form of the title,
  82          *  or false to indicate an invalid title, a missing page,
  83          *  or some other kind of error.
  84          */
  85         public function normalizePageName( $pageName, $followRedirect = MediaWikiPageNameNormalizer::FOLLOW_REDIRECT ) {
  86                 if ( defined( 'MW_PHPUNIT_TEST' ) || defined( 'MW_DEV_ENV' ) ) {
  87                         // If the code is under test, don't call out to other sites, just
  88                         // normalize locally.
  89                         // Note: this may cause results to be inconsistent with the actual
  90                         // normalization used by the respective remote site!
  91
  92                         $t = Title::newFromText( $pageName );
  93                         return $t->getPrefixedText();
  94                 } else {
  95                         static $mediaWikiPageNameNormalizer = null;
  96                         $mediaWikiPageNameNormalizer ??= new MediaWikiPageNameNormalizer();
  97
  98                         return $mediaWikiPageNameNormalizer->normalizePageName(
  99                                 $pageName,
 100                                 $this->getFileUrl( 'api.php' ),
 101                                 $followRedirect
 102                         );
 103                 }
 104         }
 105
 106         /**
 107          * Get the constant for getting or setting the script path.
 108          *
 109          * This configures how Site::setLinkPath() and Site::getLinkPath()
 110          * will work internally in terms of Site::setPath() and Site::getPath().
 111          *
 112          * @see Site::getLinkPathType
 113          * @since 1.21
 114          * @return string
 115          */
 116         public function getLinkPathType() {
 117                 return self::PATH_PAGE;
 118         }
 119
 120         /**
 121          * Get the article path, as relative path only (without server).
 122          *
 123          * @since 1.21
 124          * @return string
 125          */
 126         public function getRelativePagePath() {
 127                 return parse_url( $this->getPath( self::PATH_PAGE ), PHP_URL_PATH );
 128         }
 129
 130         /**
 131          * Get the script script, as relative path only (without server).
 132          *
 133          * @since 1.21
 134          * @return string
 135          */
 136         public function getRelativeFilePath() {
 137                 return parse_url( $this->getPath( self::PATH_FILE ), PHP_URL_PATH );
 138         }
 139
 140         /**
 141          * Set the article path.
 142          *
 143          * @since 1.21
 144          * @param string $path
 145          */
 146         public function setPagePath( $path ) {
 147                 $this->setPath( self::PATH_PAGE, $path );
 148         }
 149
 150         /**
 151          * Set the script path.
 152          *
 153          * @since 1.21
 154          * @param string $path
 155          */
 156         public function setFilePath( $path ) {
 157                 $this->setPath( self::PATH_FILE, $path );
 158         }
 159
 160         /**
 161          * Get the full URL for the given page on the site.
 162          *
 163          * This implementation returns a URL constructed using the path returned by getLinkPath().
 164          * In addition to the default behavior implemented by Site::getPageUrl(), this
 165          * method converts the $pageName to DBKey-format by replacing spaces with underscores
 166          * before using it in the URL.
 167          *
 168          * @see Site::getPageUrl
 169          * @since 1.21
 170          * @param string|false $pageName Page name or false (default: false)
 171          * @return string|null
 172          */
 173         public function getPageUrl( $pageName = false ) {
 174                 $url = $this->getLinkPath();
 175
 176                 if ( $url === null ) {
 177                         return null;
 178                 }
 179
 180                 if ( $pageName !== false ) {
 181                         $pageName = $this->toDBKey( trim( $pageName ) );
 182                         $url = str_replace( '$1', wfUrlencode( $pageName ), $url );
 183                 }
 184
 185                 return $url;
 186         }
 187
 188         /**
 189          * Get the full URL to an entry point under a wiki's script path.
 190          *
 191          * This is the equivalent of wfScript() for other sites.
 192          *
 193          * The path should go at the `$1` marker. If the $path
 194          * argument is provided, the marker will be replaced by its value.
 195          *
 196          * @since 1.21
 197          * @param string|false $path Not passing a string for this is deprecated since 1.40.
 198          * @return string
 199          */
 200         public function getFileUrl( $path = false ) {
 201                 $filePath = $this->getPath( self::PATH_FILE );
 202                 if ( $filePath === null ) {
 203                         throw new RuntimeException( "getFileUrl called for {$this->getGlobalId()} while PATH_FILE is unset" );
 204                 }
 205
 206                 if ( $path !== false ) {
 207                         $filePath = str_replace( '$1', $path, $filePath );
 208                 } else {
 209                         wfDeprecatedMsg( __METHOD__ . ': omitting $path is deprecated', '1.40' );
 210                 }
 211
 212                 return $filePath;
 213         }
 214 }
 215
 216 /** @deprecated class alias since 1.42 */
 217 class_alias( MediaWikiSite::class, 'MediaWikiSite' );