includes/TemplateParser.php

   1 <?php
   2 /**
   3  * Handles compiling Mustache templates into PHP rendering functions
   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  * @since 1.25
  22  */
  23 class TemplateParser {
  24         /**
  25          * @var string The path to the Mustache templates
  26          */
  27         protected $templateDir;
  28
  29         /**
  30          * @var callable[] Array of cached rendering functions
  31          */
  32         protected $renderers;
  33
  34         /**
  35          * @var bool Always compile template files
  36          */
  37         protected $forceRecompile = false;
  38
  39         /**
  40          * @param string $templateDir
  41          * @param boolean $forceRecompile
  42          */
  43         public function __construct( $templateDir = null, $forceRecompile = false ) {
  44                 $this->templateDir = $templateDir ? $templateDir : __DIR__ . '/templates';
  45                 $this->forceRecompile = $forceRecompile;
  46         }
  47
  48         /**
  49          * Constructs the location of the the source Mustache template
  50          * @param string $templateName The name of the template
  51          * @return string
  52          * @throws Exception Disallows upwards directory traversal via $templateName
  53          */
  54         public function getTemplateFilename( $templateName ) {
  55                 // Prevent upwards directory traversal using same methods as Title::secureAndSplit
  56                 if (
  57                         strpos( $templateName, '.' ) !== false &&
  58                         (
  59                                 $templateName === '.' || $templateName === '..' ||
  60                                 strpos( $templateName, './' ) === 0 ||
  61                                 strpos( $templateName, '../' ) === 0 ||
  62                                 strpos( $templateName, '/./' ) !== false ||
  63                                 strpos( $templateName, '/../' ) !== false ||
  64                                 substr( $templateName, -2 ) === '/.' ||
  65                                 substr( $templateName, -3 ) === '/..'
  66                         )
  67                 ) {
  68                         throw new Exception( "Malformed \$templateName: $templateName" );
  69                 }
  70
  71                 return "{$this->templateDir}/{$templateName}.mustache";
  72         }
  73
  74         /**
  75          * Returns a given template function if found, otherwise throws an exception.
  76          * @param string $templateName The name of the template (without file suffix)
  77          * @return Function
  78          * @throws Exception
  79          */
  80         public function getTemplate( $templateName ) {
  81                 // If a renderer has already been defined for this template, reuse it
  82                 if ( isset( $this->renderers[$templateName] ) ) {
  83                         return $this->renderers[$templateName];
  84                 }
  85
  86                 $filename = $this->getTemplateFilename( $templateName );
  87
  88                 if ( !file_exists( $filename ) ) {
  89                         throw new Exception( "Could not locate template: {$filename}" );
  90                 }
  91
  92                 // Read the template file
  93                 $fileContents = file_get_contents( $filename );
  94
  95                 // Generate a quick hash for cache invalidation
  96                 $fastHash = md5( $fileContents );
  97
  98                 // Fetch a secret key for building a keyed hash of the PHP code
  99                 $config = ConfigFactory::getDefaultInstance()->makeConfig( 'main' );
 100                 $secretKey = $config->get( 'SecretKey' );
 101
 102                 if ( $secretKey ) {
 103                         // See if the compiled PHP code is stored in cache.
 104                         // CACHE_ACCEL throws an exception if no suitable object cache is present, so fall
 105                         // back to CACHE_ANYTHING.
 106                         try {
 107                                 $cache = wfGetCache( CACHE_ACCEL );
 108                         } catch ( Exception $e ) {
 109                                 $cache = wfGetCache( CACHE_ANYTHING );
 110                         }
 111                         $key = wfMemcKey( 'template', $templateName, $fastHash );
 112                         $code = $this->forceRecompile ? null : $cache->get( $key );
 113
 114                         if ( !$code ) {
 115                                 $code = $this->compileForEval( $fileContents, $filename );
 116
 117                                 // Prefix the code with a keyed hash (64 hex chars) as an integrity check
 118                                 $code = hash_hmac( 'sha256', $code, $secretKey ) . $code;
 119
 120                                 // Cache the compiled PHP code
 121                                 $cache->set( $key, $code );
 122                         } else {
 123                                 // Verify the integrity of the cached PHP code
 124                                 $keyedHash = substr( $code, 0, 64 );
 125                                 $code = substr( $code, 64 );
 126                                 if ( $keyedHash !== hash_hmac( 'sha256', $code, $secretKey ) ) {
 127                                         // Generate a notice if integrity check fails
 128                                         trigger_error( "Template failed integrity check: {$filename}" );
 129                                 }
 130                         }
 131                 // If there is no secret key available, don't use cache
 132                 } else {
 133                         $code = $this->compileForEval( $fileContents, $filename );
 134                 }
 135
 136                 $renderer = eval( $code );
 137                 return $this->renderers[$templateName] = $renderer;
 138         }
 139
 140         /**
 141          * Wrapper for compile() function that verifies successful compilation and strips
 142          * out the '<?php' part so that the code is ready for eval()
 143          * @param string $fileContents Mustache code
 144          * @param string $filename Name of the template
 145          * @return string PHP code (without '<?php')
 146          * @throws Exception
 147          */
 148         public function compileForEval( $fileContents, $filename ) {
 149                 // Compile the template into PHP code
 150                 $code = self::compile( $fileContents );
 151
 152                 if ( !$code ) {
 153                         throw new Exception( "Could not compile template: {$filename}" );
 154                 }
 155
 156                 // Strip the "<?php" added by lightncandy so that it can be eval()ed
 157                 if ( substr( $code, 0, 5 ) === '<?php' ) {
 158                         $code = substr( $code, 5 );
 159                 }
 160
 161                 return $code;
 162         }
 163
 164         /**
 165          * Compile the Mustache code into PHP code using LightnCandy
 166          * @param string $code Mustache code
 167          * @return string PHP code (with '<?php')
 168          * @throws Exception
 169          */
 170         public static function compile( $code ) {
 171                 if ( !class_exists( 'LightnCandy' ) ) {
 172                         throw new Exception( 'LightnCandy class not defined' );
 173                 }
 174                 return LightnCandy::compile(
 175                         $code,
 176                         array(
 177                                 // Do not add more flags here without discussion.
 178                                 // If you do add more flags, be sure to update unit tests as well.
 179                                 'flags' => LightnCandy::FLAG_ERROR_EXCEPTION
 180                         )
 181                 );
 182         }
 183
 184         /**
 185          * Returns HTML for a given template by calling the template function with the given args
 186          *
 187          * @code
 188          *     echo $templateParser->processTemplate(
 189          *         'ExampleTemplate',
 190          *         array(
 191          *             'username' => $user->getName(),
 192          *             'message' => 'Hello!'
 193          *         )
 194          *     );
 195          * @endcode
 196          * @param string $templateName The name of the template
 197          * @param mixed $args
 198          * @param array $scopes
 199          * @return string
 200          */
 201         public function processTemplate( $templateName, $args, array $scopes = array() ) {
 202                 $template = $this->getTemplate( $templateName );
 203                 return call_user_func( $template, $args, $scopes );
 204         }
 205 }