includes/parser/Preprocessor.php

   1 <?php
   2 /**
   3  * Interfaces for preprocessors
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup Parser
  22  */
  23
  24 use MediaWiki\Logger\LoggerFactory;
  25 use MediaWiki\MediaWikiServices;
  26
  27 /**
  28  * @ingroup Parser
  29  */
  30 abstract class Preprocessor {
  31
  32         const CACHE_VERSION = 1;
  33
  34         /**
  35          * @var array Brace matching rules.
  36          */
  37         protected $rules = [
  38                 '{' => [
  39                         'end' => '}',
  40                         'names' => [
  41                                 2 => 'template',
  42                                 3 => 'tplarg',
  43                         ],
  44                         'min' => 2,
  45                         'max' => 3,
  46                 ],
  47                 '[' => [
  48                         'end' => ']',
  49                         'names' => [ 2 => null ],
  50                         'min' => 2,
  51                         'max' => 2,
  52                 ],
  53                 '-{' => [
  54                         'end' => '}-',
  55                         'names' => [ 2 => null ],
  56                         'min' => 2,
  57                         'max' => 2,
  58                 ],
  59         ];
  60
  61         /**
  62          * Store a document tree in the cache.
  63          *
  64          * @param string $text
  65          * @param int $flags
  66          * @param string $tree
  67          */
  68         protected function cacheSetTree( $text, $flags, $tree ) {
  69                 $config = RequestContext::getMain()->getConfig();
  70
  71                 $length = strlen( $text );
  72                 $threshold = $config->get( 'PreprocessorCacheThreshold' );
  73                 if ( $threshold === false || $length < $threshold || $length > 1e6 ) {
  74                         return;
  75                 }
  76
  77                 $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
  78                 $key = $cache->makeKey(
  79                         // @phan-suppress-next-line PhanUndeclaredConstant
  80                         defined( 'static::CACHE_PREFIX' ) ? static::CACHE_PREFIX : static::class,
  81                         md5( $text ),
  82                         $flags
  83                 );
  84                 $value = sprintf( "%08d", static::CACHE_VERSION ) . $tree;
  85
  86                 $cache->set( $key, $value, 86400 );
  87
  88                 LoggerFactory::getInstance( 'Preprocessor' )
  89                         ->info( "Cached preprocessor output (key: $key)" );
  90         }
  91
  92         /**
  93          * Attempt to load a precomputed document tree for some given wikitext
  94          * from the cache.
  95          *
  96          * @param string $text
  97          * @param int $flags
  98          * @return PPNode_Hash_Tree|bool
  99          */
 100         protected function cacheGetTree( $text, $flags ) {
 101                 $config = RequestContext::getMain()->getConfig();
 102
 103                 $length = strlen( $text );
 104                 $threshold = $config->get( 'PreprocessorCacheThreshold' );
 105                 if ( $threshold === false || $length < $threshold || $length > 1e6 ) {
 106                         return false;
 107                 }
 108
 109                 $cache = MediaWikiServices::getInstance()->getMainWANObjectCache();
 110
 111                 $key = $cache->makeKey(
 112                         // @phan-suppress-next-line PhanUndeclaredConstant
 113                         defined( 'static::CACHE_PREFIX' ) ? static::CACHE_PREFIX : static::class,
 114                         md5( $text ),
 115                         $flags
 116                 );
 117
 118                 $value = $cache->get( $key );
 119                 if ( !$value ) {
 120                         return false;
 121                 }
 122
 123                 $version = intval( substr( $value, 0, 8 ) );
 124                 if ( $version !== static::CACHE_VERSION ) {
 125                         return false;
 126                 }
 127
 128                 LoggerFactory::getInstance( 'Preprocessor' )
 129                         ->info( "Loaded preprocessor output from cache (key: $key)" );
 130
 131                 return substr( $value, 8 );
 132         }
 133
 134         /**
 135          * Create a new top-level frame for expansion of a page
 136          *
 137          * @return PPFrame
 138          */
 139         abstract public function newFrame();
 140
 141         /**
 142          * Create a new custom frame for programmatic use of parameter replacement
 143          * as used in some extensions.
 144          *
 145          * @param array $args
 146          *
 147          * @return PPFrame
 148          */
 149         abstract public function newCustomFrame( $args );
 150
 151         /**
 152          * Create a new custom node for programmatic use of parameter replacement
 153          * as used in some extensions.
 154          *
 155          * @param array $values
 156          */
 157         abstract public function newPartNodeArray( $values );
 158
 159         /**
 160          * Preprocess text to a PPNode
 161          *
 162          * @param string $text
 163          * @param int $flags
 164          *
 165          * @return PPNode
 166          */
 167         abstract public function preprocessToObj( $text, $flags = 0 );
 168 }