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         private function checkDeprecationStatus( string $name ) {
 125                 $deprecated = $this->deprecated[ $name ] ?? false;
 126                 if ( $deprecated ) {
 127                         wfDeprecated(
 128                                 'QuickTemplate::(get/html/text/haveData) with parameter `' . $name . '`',
 129                                 $deprecated
 130                         );
 131                 }
 132         }
 133
 134         /**
 135          * Gets the template data requested
 136          * @since 1.22
 137          * @param string $name Key for the data
 138          * @param mixed|null $default Optional default (or null)
 139          * @return mixed The value of the data requested or the default
 140          * @return-taint onlysafefor_htmlnoent
 141          */
 142         public function get( $name, $default = null ) {
 143                 $this->checkDeprecationStatus( $name );
 144                 return $this->data[$name] ?? $default;
 145         }
 146
 147         /**
 148          * Main function, used by classes that subclass QuickTemplate
 149          * to show the actual HTML output
 150          */
 151         abstract public function execute();
 152
 153         /**
 154          * @param string $str
 155          * @suppress SecurityCheck-DoubleEscaped $this->data can be either
 156          */
 157         protected function text( $str ) {
 158                 $this->checkDeprecationStatus( $str );
 159                 echo htmlspecialchars( $this->data[$str] );
 160         }
 161
 162         /**
 163          * @param string $str
 164          * @suppress SecurityCheck-XSS phan-taint-check cannot tell if $str is pre-escaped
 165          */
 166         public function html( $str ) {
 167                 $this->checkDeprecationStatus( $str );
 168                 echo $this->data[$str];
 169         }
 170
 171         /**
 172          * @param string $msgKey
 173          */
 174         public function msg( $msgKey ) {
 175                 echo htmlspecialchars( wfMessage( $msgKey )->text() );
 176         }
 177
 178         /**
 179          * @param string $str
 180          * @return bool
 181          */
 182         private function haveData( $str ) {
 183                 $this->checkDeprecationStatus( $str );
 184                 return isset( $this->data[$str] );
 185         }
 186
 187         /**
 188          * @param string $msgKey
 189          * @return bool
 190          */
 191         protected function haveMsg( $msgKey ) {
 192                 return !wfMessage( $msgKey )->isDisabled();
 193         }
 194
 195         /**
 196          * Get the Skin object related to this object
 197          *
 198          * @return SkinTemplate
 199          */
 200         public function getSkin() {
 201                 return $this->data['skin'];
 202         }
 203
 204         /**
 205          * Fetch the output of a QuickTemplate and return it
 206          *
 207          * @since 1.23
 208          * @return string
 209          */
 210         public function getHTML() {
 211                 ob_start();
 212                 $this->execute();
 213                 $html = ob_get_contents();
 214                 ob_end_clean();
 215                 return $html;
 216         }
 217 }