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
10use dokuwiki\Cache\CacheInstructions;
11use dokuwiki\Cache\CacheRenderer;
12use dokuwiki\ChangeLog\PageChangeLog;
13use dokuwiki\Extension\PluginController;
14use dokuwiki\Extension\Event;
15use 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 */
22if (!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 */
25define('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 */
36define('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 */
46define('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 */
54define('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 */
71function 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 */
115function 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 */
139function 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 */
178function 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 */
209function 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 */
243function 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 */
330function 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 */
418function 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 */
443function 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 */
468function 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 */
489function 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 */
545function 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','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 */
641function 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 */
660function 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 */
704function 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 */
761function 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 */
776function 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
819