includes/site/MediaWikiPageNameNormalizer.php

   1 <?php
   2
   3 namespace MediaWiki\Site;
   4
   5 use FormatJson;
   6 use Http;
   7 use UtfNormal\Validator;
   8
   9 /**
  10  * Service for normalizing a page name using a MediaWiki api.
  11  *
  12  * This program is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  17  * This program is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  20  * GNU General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License along
  23  * with this program; if not, write to the Free Software Foundation, Inc.,
  24  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  25  * http://www.gnu.org/copyleft/gpl.html
  26  *
  27  * @since 1.27
  28  *
  29  * @license GNU GPL v2+
  30  * @author John Erling Blad < jeblad@gmail.com >
  31  * @author Daniel Kinzler
  32  * @author Jeroen De Dauw < jeroendedauw@gmail.com >
  33  * @author Marius Hoch
  34  */
  35 class MediaWikiPageNameNormalizer {
  36
  37         /**
  38          * @var Http
  39          */
  40         private $http;
  41
  42         /**
  43          * @param Http|null $http
  44          */
  45         public function __construct( Http $http = null ) {
  46                 if ( !$http ) {
  47                         $http = new Http();
  48                 }
  49
  50                 $this->http = $http;
  51         }
  52
  53         /**
  54          * Returns the normalized form of the given page title, using the
  55          * normalization rules of the given site. If the given title is a redirect,
  56          * the redirect will be resolved and the redirect target is returned.
  57          * Only titles of existing pages will be returned.
  58          *
  59          * @note This actually makes an API request to the remote site, so beware
  60          *   that this function is slow and depends on an external service.
  61          *
  62          * @see Site::normalizePageName
  63          *
  64          * @since 1.27
  65          *
  66          * @param string $pageName
  67          * @param string $apiUrl
  68          *
  69          * @return string|false The normalized form of the title,
  70          * or false to indicate an invalid title, a missing page,
  71          * or some other kind of error.
  72          * @throws \MWException
  73          */
  74         public function normalizePageName( $pageName, $apiUrl ) {
  75                 // Check if we have strings as arguments.
  76                 if ( !is_string( $pageName ) ) {
  77                         throw new \MWException( '$pageName must be a string' );
  78                 }
  79
  80                 // Go on call the external site
  81
  82                 // Make sure the string is normalized into NFC (due to T42017)
  83                 // but do nothing to the whitespaces, that should work appropriately.
  84                 // @see https://phabricator.wikimedia.org/T42017
  85                 $pageName = Validator::cleanUp( $pageName );
  86
  87                 // Build the args for the specific call
  88                 $args = [
  89                         'action' => 'query',
  90                         'prop' => 'info',
  91                         'redirects' => true,
  92                         'converttitles' => true,
  93                         'format' => 'json',
  94                         'titles' => $pageName,
  95                         // @todo options for maxlag and maxage
  96                         // Note that maxlag will lead to a long delay before a reply is made,
  97                         // but that maxage can avoid the extreme delay. On the other hand
  98                         // maxage could be nice to use anyhow as it stops unnecessary requests.
  99                         // Also consider smaxage if maxage is used.
 100                 ];
 101
 102                 $url = wfAppendQuery( $apiUrl, $args );
 103
 104                 // Go on call the external site
 105                 // @todo we need a good way to specify a timeout here.
 106                 $ret = $this->http->get( $url, [], __METHOD__ );
 107
 108                 if ( $ret === false ) {
 109                         wfDebugLog( "MediaWikiSite", "call to external site failed: $url" );
 110                         return false;
 111                 }
 112
 113                 $data = FormatJson::decode( $ret, true );
 114
 115                 if ( !is_array( $data ) ) {
 116                         wfDebugLog( "MediaWikiSite", "call to <$url> returned bad json: " . $ret );
 117                         return false;
 118                 }
 119
 120                 $page = static::extractPageRecord( $data, $pageName );
 121
 122                 if ( isset( $page['missing'] ) ) {
 123                         wfDebugLog( "MediaWikiSite", "call to <$url> returned a marker for a missing page title! "
 124                                 . $ret );
 125                         return false;
 126                 }
 127
 128                 if ( isset( $page['invalid'] ) ) {
 129                         wfDebugLog( "MediaWikiSite", "call to <$url> returned a marker for an invalid page title! "
 130                                 . $ret );
 131                         return false;
 132                 }
 133
 134                 if ( !isset( $page['title'] ) ) {
 135                         wfDebugLog( "MediaWikiSite", "call to <$url> did not return a page title! " . $ret );
 136                         return false;
 137                 }
 138
 139                 return $page['title'];
 140         }
 141
 142         /**
 143          * Get normalization record for a given page title from an API response.
 144          *
 145          * @param array $externalData A reply from the API on a external server.
 146          * @param string $pageTitle Identifies the page at the external site, needing normalization.
 147          *
 148          * @return array|bool A 'page' structure representing the page identified by $pageTitle.
 149          */
 150         private static function extractPageRecord( $externalData, $pageTitle ) {
 151                 // If there is a special case with only one returned page
 152                 // we can cheat, and only return
 153                 // the single page in the "pages" substructure.
 154                 if ( isset( $externalData['query']['pages'] ) ) {
 155                         $pages = array_values( $externalData['query']['pages'] );
 156                         if ( count( $pages ) === 1 ) {
 157                                 return $pages[0];
 158                         }
 159                 }
 160                 // This is only used during internal testing, as it is assumed
 161                 // a more optimal (and lossfree) storage.
 162                 // Make initial checks and return if prerequisites are not meet.
 163                 if ( !is_array( $externalData ) || !isset( $externalData['query'] ) ) {
 164                         return false;
 165                 }
 166                 // Loop over the tree different named structures, that otherwise are similar
 167                 $structs = [
 168                         'normalized' => 'from',
 169                         'converted' => 'from',
 170                         'redirects' => 'from',
 171                         'pages' => 'title'
 172                 ];
 173                 foreach ( $structs as $listId => $fieldId ) {
 174                         // Check if the substructure exist at all.
 175                         if ( !isset( $externalData['query'][$listId] ) ) {
 176                                 continue;
 177                         }
 178                         // Filter the substructure down to what we actually are using.
 179                         $collectedHits = array_filter(
 180                                 array_values( $externalData['query'][$listId] ),
 181                                 function ( $a ) use ( $fieldId, $pageTitle ) {
 182                                         return $a[$fieldId] === $pageTitle;
 183                                 }
 184                         );
 185                         // If still looping over normalization, conversion or redirects,
 186                         // then we need to keep the new page title for later rounds.
 187                         if ( $fieldId === 'from' && is_array( $collectedHits ) ) {
 188                                 switch ( count( $collectedHits ) ) {
 189                                         case 0:
 190                                                 break;
 191                                         case 1:
 192                                                 $pageTitle = $collectedHits[0]['to'];
 193                                                 break;
 194                                         default:
 195                                                 return false;
 196                                 }
 197                         } elseif ( $fieldId === 'title' && is_array( $collectedHits ) ) {
 198                                 // If on the pages structure we should prepare for returning.
 199
 200                                 switch ( count( $collectedHits ) ) {
 201                                         case 0:
 202                                                 return false;
 203                                         case 1:
 204                                                 return array_shift( $collectedHits );
 205                                         default:
 206                                                 return false;
 207                                 }
 208                         }
 209                 }
 210                 // should never be here
 211                 return false;
 212         }
 213
 214 }