includes/skins/QuickTemplate.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 use MediaWiki\Config\Config;
  22 use MediaWiki\HookContainer\ProtectedHookAccessorTrait;
  23 use MediaWiki\MediaWikiServices;
  24
  25 /**
  26  * PHP-based skin template that holds data.
  27  *
  28  * Modern usage with returned output:
  29  *
  30  *     class MyTemplate extends QuickTemplate {
  31  *         public function execute() {
  32  *             $html = 'Hello, ' . Html::element( 'strong', [], $this->get( 'name' ) );
  33  *             echo $html;
  34  *         }
  35  *     }
  36  *     $tpl = new MyTemplate();
  37  *     $tpl->set( 'name', 'World' );
  38  *     $output = $tpl->getHTML();
  39  *
  40  * Classic usage with native HTML echo:
  41  *
  42  *     class MyTemplate extends QuickTemplate {
  43  *         public function execute() { ?>
  44  *
  45  *             Hello, <strong><?php $this->text( 'name' ); ?></strong>
  46  *
  47  *         <?php
  48  *         }
  49  *     }
  50  *     $tpl = new MyTemplate();
  51  *     $tpl->set( 'name', 'World' );
  52  *
  53  *     $tpl->execute(); // echo output
  54  *
  55  *
  56  * QuickTemplate was originally developed as drop-in replacement for PHPTAL 0.7 (<http://phptal.org/>).
  57  *
  58  * @stable to extend
  59  * @ingroup Skins
  60  */
  61 abstract class QuickTemplate {
  62         use ProtectedHookAccessorTrait;
  63
  64         /**
  65          * @var array
  66          */
  67         public $data;
  68
  69         /** @var Config */
  70         protected $config;
  71
  72         /** @var array */
  73         private $deprecated = [];
  74
  75         /**
  76          * @param Config|null $config
  77          */
  78         public function __construct( ?Config $config = null ) {
  79                 $this->data = [];
  80                 if ( $config === null ) {
  81                         wfDebug( __METHOD__ . ' was called with no Config instance passed to it' );
  82                         $config = MediaWikiServices::getInstance()->getMainConfig();
  83                 }
  84                 $this->config = $config;
  85         }
  86
  87         /**
  88          * Sets a template key as deprecated.
  89          *
  90          * @internal only for usage inside Skin and SkinTemplate class.
  91          * @param string $name
  92          * @param string $version When it was deprecated e.g. 1.38
  93          */
  94         public function deprecate( string $name, string $version ) {
  95                 $this->deprecated[$name] = $version;
  96         }
  97
  98         /**
  99          * Sets the value $value to $name
 100          * @param string $name
 101          * @param mixed $value
 102          */
 103         public function set( $name, $value ) {
 104                 $this->data[$name] = $value;
 105         }
 106
 107         /**
 108          * extends the value of data with name $name with the value $value
 109          * @since 1.25
 110          * @param string $name
 111          * @param mixed $value
 112          */
 113         public function extend( $name, $value ) {
 114                 if ( $this->haveData( $name ) ) {
 115                         $this->data[$name] .= $value;
 116                 } else {
 117                         $this->data[$name] = $value;
 118                 }
 119         }
 120
 121         /**
 122          * Checks if the template key is deprecated
 123          *
 124          * @param string $name
 125          */
 126         private function checkDeprecationStatus( string $name ) {
 127                 $deprecated = $this->deprecated[ $name ] ?? false;
 128                 if ( $deprecated ) {
 129                         wfDeprecated(
 130                                 'QuickTemplate::(get/html/text/haveData) with parameter `' . $name . '`',
 131                                 $deprecated
 132                         );
 133                 }
 134         }
 135
 136         /**
 137          * Gets the template data requested
 138          * @since 1.22
 139          * @param string $name Key for the data
 140          * @param mixed|null $default Optional default (or null)
 141          * @return mixed The value of the data requested or the default
 142          * @return-taint onlysafefor_htmlnoent
 143          */
 144         public function get( $name, $default = null ) {
 145                 $this->checkDeprecationStatus( $name );
 146                 return $this->data[$name] ?? $default;
 147         }
 148
 149         /**
 150          * Main function, used by classes that subclass QuickTemplate
 151          * to show the actual HTML output
 152          */
 153         abstract public function execute();
 154
 155         /**
 156          * @param string $str
 157          * @suppress SecurityCheck-DoubleEscaped $this->data can be either
 158          */
 159         protected function text( $str ) {
 160                 $this->checkDeprecationStatus( $str );
 161                 echo htmlspecialchars( $this->data[$str] );
 162         }
 163
 164         /**
 165          * @param string $str
 166          * @suppress SecurityCheck-XSS phan-taint-check cannot tell if $str is pre-escaped
 167          */
 168         public function html( $str ) {
 169                 $this->checkDeprecationStatus( $str );
 170                 echo $this->data[$str];
 171         }
 172
 173         /**
 174          * @param string $msgKey
 175          */
 176         public function msg( $msgKey ) {
 177                 echo htmlspecialchars( wfMessage( $msgKey )->text() );
 178         }
 179
 180         /**
 181          * @param string $str
 182          * @return bool
 183          */
 184         private function haveData( $str ) {
 185                 $this->checkDeprecationStatus( $str );
 186                 return isset( $this->data[$str] );
 187         }
 188
 189         /**
 190          * @param string $msgKey
 191          * @return bool
 192          */
 193         protected function haveMsg( $msgKey ) {
 194                 return !wfMessage( $msgKey )->isDisabled();
 195         }
 196
 197         /**
 198          * Get the Skin object related to this object
 199          *
 200          * @return SkinTemplate
 201          */
 202         public function getSkin() {
 203                 return $this->data['skin'];
 204         }
 205
 206         /**
 207          * Fetch the output of a QuickTemplate and return it
 208          *
 209          * @since 1.23
 210          * @return string
 211          */
 212         public function getHTML() {
 213                 ob_start();
 214                 $this->execute();
 215                 $html = ob_get_contents();
 216                 ob_end_clean();
 217                 return $html;
 218         }
 219 }