[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Utilities for accessing the parser
   4   *
   5   * @license    GPL 2 (http://www.gnu.org/licenses/gpl.html)
   6   * @author     Harry Fuecks <hfuecks@gmail.com>
   7   * @author     Andreas Gohr <andi@splitbrain.org>
   8   */
   9  
  10  use dokuwiki\Cache\CacheInstructions;
  11  use dokuwiki\Cache\CacheRenderer;
  12  use dokuwiki\ChangeLog\PageChangeLog;
  13  use dokuwiki\Extension\PluginController;
  14  use dokuwiki\Extension\Event;
  15  use dokuwiki\Parsing\Parser;
  16  
  17  /**
  18   * How many pages shall be rendered for getting metadata during one request
  19   * at maximum? Note that this limit isn't respected when METADATA_RENDER_UNLIMITED
  20   * is passed as render parameter to p_get_metadata.
  21   */
  22  if (!defined('P_GET_METADATA_RENDER_LIMIT')) define('P_GET_METADATA_RENDER_LIMIT', 5);
  23  
  24  /** Don't render metadata even if it is outdated or doesn't exist */
  25  define('METADATA_DONT_RENDER', 0);
  26  /**
  27   * Render metadata when the page is really newer or the metadata doesn't exist.
  28   * Uses just a simple check, but should work pretty well for loading simple
  29   * metadata values like the page title and avoids rendering a lot of pages in
  30   * one request. The P_GET_METADATA_RENDER_LIMIT is used in this mode.
  31   * Use this if it is unlikely that the metadata value you are requesting
  32   * does depend e.g. on pages that are included in the current page using
  33   * the include plugin (this is very likely the case for the page title, but
  34   * not for relation references).
  35   */
  36  define('METADATA_RENDER_USING_SIMPLE_CACHE', 1);
  37  /**
  38   * Render metadata using the metadata cache logic. The P_GET_METADATA_RENDER_LIMIT
  39   * is used in this mode. Use this mode when you are requesting more complex
  40   * metadata. Although this will cause rendering more often it might actually have
  41   * the effect that less current metadata is returned as it is more likely than in
  42   * the simple cache mode that metadata needs to be rendered for all pages at once
  43   * which means that when the metadata for the page is requested that actually needs
  44   * to be updated the limit might have been reached already.
  45   */
  46  define('METADATA_RENDER_USING_CACHE', 2);
  47  /**
  48   * Render metadata without limiting the number of pages for which metadata is
  49   * rendered. Use this mode with care, normally it should only be used in places
  50   * like the indexer or in cli scripts where the execution time normally isn't
  51   * limited. This can be combined with the simple cache using
  52   * METADATA_RENDER_USING_CACHE | METADATA_RENDER_UNLIMITED.
  53   */
  54  define('METADATA_RENDER_UNLIMITED', 4);
  55  
  56  /**
  57   * Returns the parsed Wikitext in XHTML for the given id and revision.
  58   *
  59   * If $excuse is true an explanation is returned if the file
  60   * wasn't found
  61   *
  62   * @author Andreas Gohr <andi@splitbrain.org>
  63   *
  64   * @param string $id page id
  65   * @param string|int $rev revision timestamp or empty string
  66   * @param bool $excuse
  67   * @param string $date_at
  68   *
  69   * @return null|string
  70   */
  71  function p_wiki_xhtml($id, $rev='', $excuse=true,$date_at=''){
  72      $file = wikiFN($id,$rev);
  73      $ret  = '';
  74  
  75      //ensure $id is in global $ID (needed for parsing)
  76      global $ID;
  77      $keep = $ID;
  78      $ID   = $id;
  79  
  80      if($rev || $date_at){
  81          if(file_exists($file)){
  82              //no caching on old revisions
  83              $ret = p_render('xhtml',p_get_instructions(io_readWikiPage($file,$id,$rev)),$info,$date_at);
  84          }elseif($excuse){
  85              $ret = p_locale_xhtml('norev');
  86          }
  87      }else{
  88          if(file_exists($file)){
  89              $ret = p_cached_output($file,'xhtml',$id);
  90          }elseif($excuse){
  91              //check if the page once existed
  92              $changelog = new PageChangeLog($id);
  93              if($changelog->hasRevisions()) {
  94                  $ret = p_locale_xhtml('onceexisted');
  95              } else {
  96                  $ret = p_locale_xhtml('newpage');
  97              }
  98          }
  99      }
 100  
 101      //restore ID (just in case)
 102      $ID = $keep;
 103  
 104      return $ret;
 105  }
 106  
 107  /**
 108   * Returns the specified local text in parsed format
 109   *
 110   * @author Andreas Gohr <andi@splitbrain.org>
 111   *
 112   * @param string $id page id
 113   * @return null|string
 114   */
 115  function p_locale_xhtml($id){
 116      //fetch parsed locale
 117      $data = ['id' => $id, 'html' => ''];
 118  
 119      $event = new Event('PARSER_LOCALE_XHTML', $data);
 120      if ($event->advise_before()) {
 121          $data['html'] = p_cached_output(localeFN($data['id']));
 122      }
 123      $event->advise_after();
 124  
 125      return $data['html'];
 126  }
 127  
 128  /**
 129   * Returns the given file parsed into the requested output format
 130   *
 131   * @author Andreas Gohr <andi@splitbrain.org>
 132   * @author Chris Smith <chris@jalakai.co.uk>
 133   *
 134   * @param string $file filename, path to file
 135   * @param string $format
 136   * @param string $id page id
 137   * @return null|string
 138   */
 139  function p_cached_output($file, $format='xhtml', $id='') {
 140      global $conf;
 141  
 142      $cache = new CacheRenderer($id, $file, $format);
 143      if ($cache->useCache()) {
 144          $parsed = $cache->retrieveCache(false);
 145          if($conf['allowdebug'] && $format=='xhtml') {
 146              $parsed .= "\n<!-- cachefile {$cache->cache} used -->\n";
 147          }
 148      } else {
 149          $parsed = p_render($format, p_cached_instructions($file,false,$id), $info);
 150  
 151          if ($info['cache'] && $cache->storeCache($parsed)) {              // storeCache() attempts to save cachefile
 152              if($conf['allowdebug'] && $format=='xhtml') {
 153                  $parsed .= "\n<!-- no cachefile used, but created {$cache->cache} -->\n";
 154              }
 155          }else{
 156              $cache->removeCache();                     //try to delete cachefile
 157              if($conf['allowdebug'] && $format=='xhtml') {
 158                  $parsed .= "\n<!-- no cachefile used, caching forbidden -->\n";
 159              }
 160          }
 161      }
 162  
 163      return $parsed;
 164  }
 165  
 166  /**
 167   * Returns the render instructions for a file
 168   *
 169   * Uses and creates a serialized cache file
 170   *
 171   * @author Andreas Gohr <andi@splitbrain.org>
 172   *
 173   * @param string $file      filename, path to file
 174   * @param bool   $cacheonly
 175   * @param string $id        page id
 176   * @return array|null
 177   */
 178  function p_cached_instructions($file,$cacheonly=false,$id='') {
 179      static $run = null;
 180      if(is_null($run)) $run = array();
 181  
 182      $cache = new CacheInstructions($id, $file);
 183  
 184      if ($cacheonly || $cache->useCache() || (isset($run[$file]) && !defined('DOKU_UNITTEST'))) {
 185          return $cache->retrieveCache();
 186      } else if (file_exists($file)) {
 187          // no cache - do some work
 188          $ins = p_get_instructions(io_readWikiPage($file,$id));
 189          if ($cache->storeCache($ins)) {
 190              $run[$file] = true; // we won't rebuild these instructions in the same run again
 191          } else {
 192              msg('Unable to save cache file. Hint: disk full; file permissions; safe_mode setting.',-1);
 193          }
 194          return $ins;
 195      }
 196  
 197      return null;
 198  }
 199  
 200  /**
 201   * turns a page into a list of instructions
 202   *
 203   * @author Harry Fuecks <hfuecks@gmail.com>
 204   * @author Andreas Gohr <andi@splitbrain.org>
 205   *
 206   * @param string $text  raw wiki syntax text
 207   * @return array a list of instruction arrays
 208   */
 209  function p_get_instructions($text){
 210  
 211      $modes = p_get_parsermodes();
 212  
 213      // Create the parser and handler
 214      $Parser = new Parser(new Doku_Handler());
 215  
 216      //add modes to parser
 217      foreach($modes as $mode){
 218          $Parser->addMode($mode['mode'],$mode['obj']);
 219      }
 220  
 221      // Do the parsing
 222      Event::createAndTrigger('PARSER_WIKITEXT_PREPROCESS', $text);
 223      $p = $Parser->parse($text);
 224      //  dbg($p);
 225      return $p;
 226  }
 227  
 228  /**
 229   * returns the metadata of a page
 230   *
 231   * @param string $id      The id of the page the metadata should be returned from
 232   * @param string $key     The key of the metdata value that shall be read (by default everything)
 233   *                        separate hierarchies by " " like "date created"
 234   * @param int    $render  If the page should be rendererd - possible values:
 235   *     METADATA_DONT_RENDER, METADATA_RENDER_USING_SIMPLE_CACHE, METADATA_RENDER_USING_CACHE
 236   *     METADATA_RENDER_UNLIMITED (also combined with the previous two options),
 237   *     default: METADATA_RENDER_USING_CACHE
 238   * @return mixed The requested metadata fields
 239   *
 240   * @author Esther Brunner <esther@kaffeehaus.ch>
 241   * @author Michael Hamann <michael@content-space.de>
 242   */
 243  function p_get_metadata($id, $key='', $render=METADATA_RENDER_USING_CACHE){
 244      global $ID;
 245      static $render_count = 0;
 246      // track pages that have already been rendered in order to avoid rendering the same page
 247      // again
 248      static $rendered_pages = array();
 249  
 250      // cache the current page
 251      // Benchmarking shows the current page's metadata is generally the only page metadata
 252      // accessed several times. This may catch a few other pages, but that shouldn't be an issue.
 253      $cache = ($ID == $id);
 254      $meta = p_read_metadata($id, $cache);
 255  
 256      if (!is_numeric($render)) {
 257          if ($render) {
 258              $render = METADATA_RENDER_USING_SIMPLE_CACHE;
 259          } else {
 260              $render = METADATA_DONT_RENDER;
 261          }
 262      }
 263  
 264      // prevent recursive calls in the cache
 265      static $recursion = false;
 266      if (!$recursion && $render != METADATA_DONT_RENDER && !isset($rendered_pages[$id])&& page_exists($id)){
 267          $recursion = true;
 268  
 269          $cachefile = new CacheRenderer($id, wikiFN($id), 'metadata');
 270  
 271          $do_render = false;
 272          if ($render & METADATA_RENDER_UNLIMITED || $render_count < P_GET_METADATA_RENDER_LIMIT) {
 273              if ($render & METADATA_RENDER_USING_SIMPLE_CACHE) {
 274                  $pagefn = wikiFN($id);
 275                  $metafn = metaFN($id, '.meta');
 276                  if (!file_exists($metafn) || @filemtime($pagefn) > @filemtime($cachefile->cache)) {
 277                      $do_render = true;
 278                  }
 279              } elseif (!$cachefile->useCache()){
 280                  $do_render = true;
 281              }
 282          }
 283          if ($do_render) {
 284              if (!defined('DOKU_UNITTEST')) {
 285                  ++$render_count;
 286                  $rendered_pages[$id] = true;
 287              }
 288              $old_meta = $meta;
 289              $meta = p_render_metadata($id, $meta);
 290              // only update the file when the metadata has been changed
 291              if ($meta == $old_meta || p_save_metadata($id, $meta)) {
 292                  // store a timestamp in order to make sure that the cachefile is touched
 293                  // this timestamp is also stored when the meta data is still the same
 294                  $cachefile->storeCache(time());
 295              } else {
 296                  msg('Unable to save metadata file. Hint: disk full; file permissions; safe_mode setting.',-1);
 297              }
 298          }
 299  
 300          $recursion = false;
 301      }
 302  
 303      $val = $meta['current'];
 304  
 305      // filter by $key
 306      foreach(preg_split('/\s+/', $key, 2, PREG_SPLIT_NO_EMPTY) as $cur_key) {
 307          if (!isset($val[$cur_key])) {
 308              return null;
 309          }
 310          $val = $val[$cur_key];
 311      }
 312      return $val;
 313  }
 314  
 315  /**
 316   * sets metadata elements of a page
 317   *
 318   * @see http://www.dokuwiki.org/devel:metadata#functions_to_get_and_set_metadata
 319   *
 320   * @param string  $id         is the ID of a wiki page
 321   * @param array   $data       is an array with key ⇒ value pairs to be set in the metadata
 322   * @param boolean $render     whether or not the page metadata should be generated with the renderer
 323   * @param boolean $persistent indicates whether or not the particular metadata value will persist through
 324   *                            the next metadata rendering.
 325   * @return boolean true on success
 326   *
 327   * @author Esther Brunner <esther@kaffeehaus.ch>
 328   * @author Michael Hamann <michael@content-space.de>
 329   */
 330  function p_set_metadata($id, $data, $render=false, $persistent=true){
 331      if (!is_array($data)) return false;
 332  
 333      global $ID, $METADATA_RENDERERS;
 334  
 335      // if there is currently a renderer change the data in the renderer instead
 336      if (isset($METADATA_RENDERERS[$id])) {
 337          $orig =& $METADATA_RENDERERS[$id];
 338          $meta = $orig;
 339      } else {
 340          // cache the current page
 341          $cache = ($ID == $id);
 342          $orig = p_read_metadata($id, $cache);
 343  
 344          // render metadata first?
 345          $meta = $render ? p_render_metadata($id, $orig) : $orig;
 346      }
 347  
 348      // now add the passed metadata
 349      $protected = array('description', 'date', 'contributor');
 350      foreach ($data as $key => $value){
 351  
 352          // be careful with sub-arrays of $meta['relation']
 353          if ($key == 'relation'){
 354  
 355              foreach ($value as $subkey => $subvalue){
 356                  if(isset($meta['current'][$key][$subkey]) && is_array($meta['current'][$key][$subkey])) {
 357                      $meta['current'][$key][$subkey] = array_replace($meta['current'][$key][$subkey], (array)$subvalue);
 358                  } else {
 359                      $meta['current'][$key][$subkey] = $subvalue;
 360                  }
 361                  if($persistent) {
 362                      if(isset($meta['persistent'][$key][$subkey]) && is_array($meta['persistent'][$key][$subkey])) {
 363                          $meta['persistent'][$key][$subkey] = array_replace(
 364                              $meta['persistent'][$key][$subkey],
 365                              (array) $subvalue
 366                          );
 367                      } else {
 368                          $meta['persistent'][$key][$subkey] = $subvalue;
 369                      }
 370                  }
 371              }
 372  
 373              // be careful with some senisitive arrays of $meta
 374          } elseif (in_array($key, $protected)){
 375  
 376              // these keys, must have subkeys - a legitimate value must be an array
 377              if (is_array($value)) {
 378                  $meta['current'][$key] = !empty($meta['current'][$key]) ?
 379                      array_replace((array)$meta['current'][$key],$value) :
 380                      $value;
 381  
 382                  if ($persistent) {
 383                      $meta['persistent'][$key] = !empty($meta['persistent'][$key]) ?
 384                          array_replace((array)$meta['persistent'][$key],$value) :
 385                          $value;
 386                  }
 387              }
 388  
 389              // no special treatment for the rest
 390          } else {
 391              $meta['current'][$key] = $value;
 392              if ($persistent) $meta['persistent'][$key] = $value;
 393          }
 394      }
 395  
 396      // save only if metadata changed
 397      if ($meta == $orig) return true;
 398  
 399      if (isset($METADATA_RENDERERS[$id])) {
 400          // set both keys individually as the renderer has references to the individual keys
 401          $METADATA_RENDERERS[$id]['current']    = $meta['current'];
 402          $METADATA_RENDERERS[$id]['persistent'] = $meta['persistent'];
 403          return true;
 404      } else {
 405          return p_save_metadata($id, $meta);
 406      }
 407  }
 408  
 409  /**
 410   * Purges the non-persistant part of the meta data
 411   * used on page deletion
 412   *
 413   * @author Michael Klier <chi@chimeric.de>
 414   *
 415   * @param string $id page id
 416   * @return bool  success / fail
 417   */
 418  function p_purge_metadata($id) {
 419      $meta = p_read_metadata($id);
 420      foreach($meta['current'] as $key => $value) {
 421          if(isset($meta[$key]) && is_array($meta[$key])) {
 422              $meta['current'][$key] = array();
 423          } else {
 424              $meta['current'][$key] = '';
 425          }
 426  
 427      }
 428      return p_save_metadata($id, $meta);
 429  }
 430  
 431  /**
 432   * read the metadata from source/cache for $id
 433   * (internal use only - called by p_get_metadata & p_set_metadata)
 434   *
 435   * @author   Christopher Smith <chris@jalakai.co.uk>
 436   *
 437   * @param    string   $id      absolute wiki page id
 438   * @param    bool     $cache   whether or not to cache metadata in memory
 439   *                             (only use for metadata likely to be accessed several times)
 440   *
 441   * @return   array             metadata
 442   */
 443  function p_read_metadata($id,$cache=false) {
 444      global $cache_metadata;
 445  
 446      if (isset($cache_metadata[(string)$id])) return $cache_metadata[(string)$id];
 447  
 448      $file = metaFN($id, '.meta');
 449      $meta = file_exists($file) ?
 450          unserialize(io_readFile($file, false)) :
 451          array('current'=>array(),'persistent'=>array());
 452  
 453      if ($cache) {
 454          $cache_metadata[(string)$id] = $meta;
 455      }
 456  
 457      return $meta;
 458  }
 459  
 460  /**
 461   * This is the backend function to save a metadata array to a file
 462   *
 463   * @param    string   $id      absolute wiki page id
 464   * @param    array    $meta    metadata
 465   *
 466   * @return   bool              success / fail
 467   */
 468  function p_save_metadata($id, $meta) {
 469      // sync cached copies, including $INFO metadata
 470      global $cache_metadata, $INFO;
 471  
 472      if (isset($cache_metadata[$id])) $cache_metadata[$id] = $meta;
 473      if (!empty($INFO) && isset($INFO['id']) && ($id == $INFO['id'])) {
 474          $INFO['meta'] = $meta['current'];
 475      }
 476  
 477      return io_saveFile(metaFN($id, '.meta'), serialize($meta));
 478  }
 479  
 480  /**
 481   * renders the metadata of a page
 482   *
 483   * @author Esther Brunner <esther@kaffeehaus.ch>
 484   *
 485   * @param string $id    page id
 486   * @param array  $orig  the original metadata
 487   * @return array|null array('current'=> array,'persistent'=> array);
 488   */
 489  function p_render_metadata($id, $orig){
 490      // make sure the correct ID is in global ID
 491      global $ID, $METADATA_RENDERERS;
 492  
 493      // avoid recursive rendering processes for the same id
 494      if (isset($METADATA_RENDERERS[$id])) {
 495          return $orig;
 496      }
 497  
 498      // store the original metadata in the global $METADATA_RENDERERS so p_set_metadata can use it
 499      $METADATA_RENDERERS[$id] =& $orig;
 500  
 501      $keep = $ID;
 502      $ID   = $id;
 503  
 504      // add an extra key for the event - to tell event handlers the page whose metadata this is
 505      $orig['page'] = $id;
 506      $evt = new Event('PARSER_METADATA_RENDER', $orig);
 507      if ($evt->advise_before()) {
 508  
 509          // get instructions
 510          $instructions = p_cached_instructions(wikiFN($id),false,$id);
 511          if(is_null($instructions)){
 512              $ID = $keep;
 513              unset($METADATA_RENDERERS[$id]);
 514              return null; // something went wrong with the instructions
 515          }
 516  
 517          // set up the renderer
 518          $renderer = new Doku_Renderer_metadata();
 519          $renderer->meta =& $orig['current'];
 520          $renderer->persistent =& $orig['persistent'];
 521  
 522          // loop through the instructions
 523          foreach ($instructions as $instruction){
 524              // execute the callback against the renderer
 525              call_user_func_array(array(&$renderer, $instruction[0]), (array) $instruction[1]);
 526          }
 527  
 528          $evt->result = array('current'=>&$renderer->meta,'persistent'=>&$renderer->persistent);
 529      }
 530      $evt->advise_after();
 531  
 532      // clean up
 533      $ID = $keep;
 534      unset($METADATA_RENDERERS[$id]);
 535      return $evt->result;
 536  }
 537  
 538  /**
 539   * returns all available parser syntax modes in correct order
 540   *
 541   * @author Andreas Gohr <andi@splitbrain.org>
 542   *
 543   * @return array[] with for each plugin the array('sort' => sortnumber, 'mode' => mode string, 'obj'  => plugin object)
 544   */
 545  function p_get_parsermodes(){
 546      global $conf;
 547  
 548      //reuse old data
 549      static $modes = null;
 550      if($modes != null && !defined('DOKU_UNITTEST')){
 551          return $modes;
 552      }
 553  
 554      //import parser classes and mode definitions
 555      require_once  DOKU_INC . 'inc/parser/parser.php';
 556  
 557      // we now collect all syntax modes and their objects, then they will
 558      // be sorted and added to the parser in correct order
 559      $modes = array();
 560  
 561      // add syntax plugins
 562      $pluginlist = plugin_list('syntax');
 563      if(count($pluginlist)){
 564          global $PARSER_MODES;
 565          $obj = null;
 566          foreach($pluginlist as $p){
 567              /** @var \dokuwiki\Extension\SyntaxPlugin $obj */
 568              if(!$obj = plugin_load('syntax',$p)) continue; //attempt to load plugin into $obj
 569              $PARSER_MODES[$obj->getType()][] = "plugin_$p"; //register mode type
 570              //add to modes
 571              $modes[] = array(
 572                      'sort' => $obj->getSort(),
 573                      'mode' => "plugin_$p",
 574                      'obj'  => $obj,
 575                      );
 576              unset($obj); //remove the reference
 577          }
 578      }
 579  
 580      // add default modes
 581      $std_modes = array('listblock','preformatted','notoc','nocache',
 582              'header','table','linebreak','footnote','hr',
 583              'unformatted','php','html','code','file','quote',
 584              'internallink','rss','media','externallink',
 585              'emaillink','windowssharelink','eol');
 586      if($conf['typography']){
 587          $std_modes[] = 'quotes';
 588          $std_modes[] = 'multiplyentity';
 589      }
 590      foreach($std_modes as $m){
 591          $class = 'dokuwiki\\Parsing\\ParserMode\\'.ucfirst($m);
 592          $obj   = new $class();
 593          $modes[] = array(
 594                  'sort' => $obj->getSort(),
 595                  'mode' => $m,
 596                  'obj'  => $obj
 597                  );
 598      }
 599  
 600      // add formatting modes
 601      $fmt_modes = array('strong','emphasis','underline','monospace',
 602              'subscript','superscript','deleted');
 603      foreach($fmt_modes as $m){
 604          $obj   = new \dokuwiki\Parsing\ParserMode\Formatting($m);
 605          $modes[] = array(
 606                  'sort' => $obj->getSort(),
 607                  'mode' => $m,
 608                  'obj'  => $obj
 609                  );
 610      }
 611  
 612      // add modes which need files
 613      $obj     = new \dokuwiki\Parsing\ParserMode\Smiley(array_keys(getSmileys()));
 614      $modes[] = array('sort' => $obj->getSort(), 'mode' => 'smiley','obj'  => $obj );
 615      $obj     = new \dokuwiki\Parsing\ParserMode\Acronym(array_keys(getAcronyms()));
 616      $modes[] = array('sort' => $obj->getSort(), 'mode' => 'acronym','obj'  => $obj );
 617      $obj     = new \dokuwiki\Parsing\ParserMode\Entity(array_keys(getEntities()));
 618      $modes[] = array('sort' => $obj->getSort(), 'mode' => 'entity','obj'  => $obj );
 619  
 620      // add optional camelcase mode
 621      if($conf['camelcase']){
 622          $obj     = new \dokuwiki\Parsing\ParserMode\Camelcaselink();
 623          $modes[] = array('sort' => $obj->getSort(), 'mode' => 'camelcaselink','obj'  => $obj );
 624      }
 625  
 626      //sort modes
 627      usort($modes,'p_sort_modes');
 628  
 629      return $modes;
 630  }
 631  
 632  /**
 633   * Callback function for usort
 634   *
 635   * @author Andreas Gohr <andi@splitbrain.org>
 636   *
 637   * @param array $a
 638   * @param array $b
 639   * @return int $a is lower/equal/higher than $b
 640   */
 641  function p_sort_modes($a, $b){
 642      if($a['sort'] == $b['sort']) return 0;
 643      return ($a['sort'] < $b['sort']) ? -1 : 1;
 644  }
 645  
 646  /**
 647   * Renders a list of instruction to the specified output mode
 648   *
 649   * In the $info array is information from the renderer returned
 650   *
 651   * @author Harry Fuecks <hfuecks@gmail.com>
 652   * @author Andreas Gohr <andi@splitbrain.org>
 653   *
 654   * @param string $mode
 655   * @param array|null|false $instructions
 656   * @param array $info returns render info like enabled toc and cache
 657   * @param string $date_at
 658   * @return null|string rendered output
 659   */
 660  function p_render($mode,$instructions,&$info,$date_at=''){
 661      if(is_null($instructions)) return '';
 662      if($instructions === false) return '';
 663  
 664      $Renderer = p_get_renderer($mode);
 665      if (is_null($Renderer)) return null;
 666  
 667      $Renderer->reset();
 668  
 669      if($date_at) {
 670          $Renderer->date_at = $date_at;
 671      }
 672  
 673      $Renderer->smileys = getSmileys();
 674      $Renderer->entities = getEntities();
 675      $Renderer->acronyms = getAcronyms();
 676      $Renderer->interwiki = getInterwiki();
 677  
 678      // Loop through the instructions
 679      foreach ( $instructions as $instruction ) {
 680          // Execute the callback against the Renderer
 681          if(method_exists($Renderer, $instruction[0])){
 682              call_user_func_array(array(&$Renderer, $instruction[0]), $instruction[1] ? $instruction[1] : array());
 683          }
 684      }
 685  
 686      //set info array
 687      $info = $Renderer->info;
 688  
 689      // Post process and return the output
 690      $data = array($mode,& $Renderer->doc);
 691      Event::createAndTrigger('RENDERER_CONTENT_POSTPROCESS',$data);
 692      return $Renderer->doc;
 693  }
 694  
 695  /**
 696   * Figure out the correct renderer class to use for $mode,
 697   * instantiate and return it
 698   *
 699   * @param string $mode Mode of the renderer to get
 700   * @return null|Doku_Renderer The renderer
 701   *
 702   * @author Christopher Smith <chris@jalakai.co.uk>
 703   */
 704  function p_get_renderer($mode) {
 705      /** @var PluginController $plugin_controller */
 706      global $conf, $plugin_controller;
 707  
 708      $rname = !empty($conf['renderer_'.$mode]) ? $conf['renderer_'.$mode] : $mode;
 709      $rclass = "Doku_Renderer_$rname";
 710  
 711      // if requested earlier or a bundled renderer
 712      if( class_exists($rclass) ) {
 713          $Renderer = new $rclass();
 714          return $Renderer;
 715      }
 716  
 717      // not bundled, see if its an enabled renderer plugin & when $mode is 'xhtml', the renderer can supply that format.
 718      /** @var Doku_Renderer $Renderer */
 719      $Renderer = $plugin_controller->load('renderer',$rname);
 720      if ($Renderer && is_a($Renderer, 'Doku_Renderer')  && ($mode != 'xhtml' || $mode == $Renderer->getFormat())) {
 721          return $Renderer;
 722      }
 723  
 724      // there is a configuration error!
 725      // not bundled, not a valid enabled plugin, use $mode to try to fallback to a bundled renderer
 726      $rclass = "Doku_Renderer_$mode";
 727      if ( class_exists($rclass) ) {
 728          // viewers should see renderered output, so restrict the warning to admins only
 729          $msg = "No renderer '$rname' found for mode '$mode', check your plugins";
 730          if ($mode == 'xhtml') {
 731              $msg .= " and the 'renderer_xhtml' config setting";
 732          }
 733          $msg .= ".<br/>Attempting to fallback to the bundled renderer.";
 734          msg($msg,-1,'','',MSG_ADMINS_ONLY);
 735  
 736          $Renderer = new $rclass;
 737          $Renderer->nocache();     // fallback only (and may include admin alerts), don't cache
 738          return $Renderer;
 739      }
 740  
 741      // fallback failed, alert the world
 742      msg("No renderer '$rname' found for mode '$mode'",-1);
 743      return null;
 744  }
 745  
 746  /**
 747   * Gets the first heading from a file
 748   *
 749   * @param   string   $id       dokuwiki page id
 750   * @param   int      $render   rerender if first heading not known
 751   *                             default: METADATA_RENDER_USING_SIMPLE_CACHE
 752   *                             Possible values: METADATA_DONT_RENDER,
 753   *                                              METADATA_RENDER_USING_SIMPLE_CACHE,
 754   *                                              METADATA_RENDER_USING_CACHE,
 755   *                                              METADATA_RENDER_UNLIMITED
 756   * @return string|null The first heading
 757   *
 758   * @author Andreas Gohr <andi@splitbrain.org>
 759   * @author Michael Hamann <michael@content-space.de>
 760   */
 761  function p_get_first_heading($id, $render=METADATA_RENDER_USING_SIMPLE_CACHE){
 762      return p_get_metadata(cleanID($id),'title',$render);
 763  }
 764  
 765  /**
 766   * Wrapper for GeSHi Code Highlighter, provides caching of its output
 767   *
 768   * @param  string   $code       source code to be highlighted
 769   * @param  string   $language   language to provide highlighting
 770   * @param  string   $wrapper    html element to wrap the returned highlighted text
 771   * @return string xhtml code
 772   *
 773   * @author Christopher Smith <chris@jalakai.co.uk>
 774   * @author Andreas Gohr <andi@splitbrain.org>
 775   */
 776  function p_xhtml_cached_geshi($code, $language, $wrapper='pre', array $options=null) {
 777      global $conf, $config_cascade, $INPUT;
 778      $language = strtolower($language);
 779  
 780      // remove any leading or trailing blank lines
 781      $code = preg_replace('/^\s*?\n|\s*?\n$/','',$code);
 782  
 783      $optionsmd5 = md5(serialize($options));
 784      $cache = getCacheName($language.$code.$optionsmd5,".code");
 785      $ctime = @filemtime($cache);
 786      if($ctime && !$INPUT->bool('purge') &&
 787              $ctime > filemtime(DOKU_INC.'vendor/composer/installed.json') &&  // libraries changed
 788              $ctime > filemtime(reset($config_cascade['main']['default']))){ // dokuwiki changed
 789          $highlighted_code = io_readFile($cache, false);
 790      } else {
 791  
 792          $geshi = new GeSHi($code, $language);
 793          $geshi->set_encoding('utf-8');
 794          $geshi->enable_classes();
 795          $geshi->set_header_type(GESHI_HEADER_PRE);
 796          $geshi->set_link_target($conf['target']['extern']);
 797          if($options !== null) {
 798              foreach ($options as $function => $params) {
 799                  if(is_callable(array($geshi, $function))) {
 800                      $geshi->$function($params);
 801                  }
 802              }
 803          }
 804  
 805          // remove GeSHi's wrapper element (we'll replace it with our own later)
 806          // we need to use a GeSHi wrapper to avoid <BR> throughout the highlighted text
 807          $highlighted_code = trim(preg_replace('!^<pre[^>]*>|</pre>$!','',$geshi->parse_code()),"\n\r");
 808          io_saveFile($cache,$highlighted_code);
 809      }
 810  
 811      // add a wrapper element if required
 812      if ($wrapper) {
 813          return "<$wrapper class=\"code $language\">$highlighted_code</$wrapper>";
 814      } else {
 815          return $highlighted_code;
 816      }
 817  }
 818