IT.php

Go to the documentation of this file.

<?php

declare(strict_types=1);

// +----------------------------------------------------------------------+
// +----------------------------------------------------------------------+
// | This source file is subject to the New BSD license, That is bundled  |
// | the world-wide-web at                                                |
// | http://www.opensource.org/licenses/bsd-license.php                   |
// | If you did not receive a copy of the new BSD license and are unable  |
// | to obtain it through the world-wide-web, please send a note to       |
// | pajoye@php.net, so we can mail you a copy immediately.               |
// +----------------------------------------------------------------------+
// | Author: Ulf Wendel <ulf.wendel@phpdoc.de>                            |
// |         Pierre-Alain Joye <pajoye@php.net>                           |
// +----------------------------------------------------------------------+
use ILIAS\components\UICore\Cache\BlockCache;
use ILIAS\components\UICore\Cache\VariableCache;
use ILIAS\components\UICore\Cache\TemplateCache;
use ILIAS\Refinery\Custom\Transformation;
use ILIAS\Refinery\To\Transformation\ListTransformation;
use ILIAS\Refinery\To\Transformation\StringTransformation;
use ILIAS\DI\Container;

require_once __DIR__ . '/../../exceptions/class.ilTemplateException.php';

class HTML_Template_IT
{
    public const IT_OK = 1;
    public const IT_ERROR = -1;
    public const IT_TPL_NOT_FOUND = -2;
    public const IT_BLOCK_NOT_FOUND = -3;
    public const IT_BLOCK_DUPLICATE = -4;
    public const IT_UNKNOWN_OPTION = -6;
    public const IT_DEFAULT_BLOCK = '__global__';
    private \ILIAS\Cache\Container\Container $block_cache;
    private \ILIAS\Cache\Container\Container $variable_cache;
    private \ILIAS\Cache\Container\Container $template_cache;

    public array $err = [];

    public bool $clearCache = false;

    public string $openingDelimiter = '{';

    public string $closingDelimiter = '}';

    public string $blocknameRegExp = '[\.0-9A-Za-z_-]+';

    public string $variablenameRegExp = '[\.0-9A-Za-z_-]+';

    public string $variablesRegExp = '';

    public string $removeVariablesRegExp = '';

    public bool $removeUnknownVariables = true;

    public bool $removeEmptyBlocks = true;

    public string $blockRegExp = '';

    public string $currentBlock = self::IT_DEFAULT_BLOCK;

    public string $template = '';

    public array $blocklist = [];

    public array $blockdata = [];

    public array $blockvariables = [];

    public array $blockparents = [];

    public array $blockinner = [];

    public array $touchedBlocks = [];

    public array $variableCache = [];

    public bool $clearCacheOnParse = false;

    public string $fileRoot = '';

    public bool $flagBlocktrouble = false;

    public bool $flagGlobalParsed = false;

    public bool $flagCacheTemplatefile = true;

    public string $lastTemplatefile = '';

    public array $_options = [
        'preserve_data' => false,
        'use_preg' => true
    ];

    protected string $real_filename = '';

    public function __construct(string $root = '', ?array $options = null)
    {
        global $DIC;
        $DIC = $DIC instanceof Container ? $DIC : new Container([]);
        $this->block_cache = $DIC->globalCache()->get(new BlockCache());
        $this->variable_cache = $DIC->globalCache()->get(new VariableCache());
        $this->template_cache = $DIC->globalCache()->get(new TemplateCache());

        if (!is_null($options)) {
            $this->setOptions($options);
        }
        $this->variablesRegExp = '@' . $this->openingDelimiter .
            '(' . $this->variablenameRegExp . ')' .
            $this->closingDelimiter . '@sm';
        $this->removeVariablesRegExp = '@' . $this->openingDelimiter .
            "\s*(" . $this->variablenameRegExp .
            ")\s*" . $this->closingDelimiter . '@sm';

        $this->blockRegExp = '@<!--\s+BEGIN\s+(' . $this->blocknameRegExp .
            ')\s+-->(.*)<!--\s+END\s+\1\s+-->@sm';

        $this->setRoot($root);
    }

    public function setOption(string $option, $value): int
    {
        if (array_key_exists($option, $this->_options)) {
            $this->_options[$option] = $value;
            return self::IT_OK;
        }

        throw new ilTemplateException($this->errorMessage(self::IT_UNKNOWN_OPTION) . ": '$option'");
    }

    public function setOptions(array $options): int
    {
        foreach ($options as $option => $value) {
            $this->setOption($option, $value);
        }

        return self::IT_OK;
    }

    public function show(string $block = self::IT_DEFAULT_BLOCK): void
    {
        print $this->get($block);
    }

    public function get(string $block = self::IT_DEFAULT_BLOCK): string
    {
        if ($block === self::IT_DEFAULT_BLOCK && !$this->flagGlobalParsed) {
            $this->parse();
        }

        if (!isset($this->blocklist[$block])) {
            throw new ilTemplateException($this->errorMessage(self::IT_BLOCK_NOT_FOUND) . '"' . $block . "'");
        }

        if (isset($this->blockdata[$block])) {
            $ret = $this->blockdata[$block];
            if ($this->clearCache) {
                unset($this->blockdata[$block]);
            }
            if ($this->_options['preserve_data']) {
                $ret = str_replace(
                    $this->openingDelimiter .
                    '%preserved%' . $this->closingDelimiter,
                    $this->openingDelimiter,
                    $ret
                );
            }
            return $ret;
        }

        return '';
    }

    public function parse(string $block = self::IT_DEFAULT_BLOCK, bool $flag_recursion = false): bool
    {
        static $regs, $values;

        if (!isset($this->blocklist[$block])) {
            throw new ilTemplateException($this->errorMessage(self::IT_BLOCK_NOT_FOUND) . '"' . $block . "'");
        }

        if (self::IT_DEFAULT_BLOCK === $block) {
            $this->flagGlobalParsed = true;
        }

        if (!$flag_recursion) {
            $regs = [];
            $values = [];
        }
        $outer = $this->blocklist[$block];
        $empty = true;

        if ($this->clearCacheOnParse) {
            foreach ($this->variableCache as $name => $value) {
                $regs[] = $this->openingDelimiter .
                    $name . $this->closingDelimiter;
                $values[] = $value;
                $empty = false;
            }
            $this->variableCache = [];
        } else {
            foreach ($this->blockvariables[$block] as $allowedvar => $v) {
                if (isset($this->variableCache[$allowedvar])) {
                    $regs[] = $this->openingDelimiter .
                        $allowedvar . $this->closingDelimiter;
                    $values[] = $this->variableCache[$allowedvar];
                    unset($this->variableCache[$allowedvar]);
                    $empty = false;
                }
            }
        }

        if (isset($this->blockinner[$block])) {
            foreach ($this->blockinner[$block] as $k => $innerblock) {
                $this->parse($innerblock, true);
                if ($this->blockdata[$innerblock] !== '') {
                    $empty = false;
                }

                $placeholder = $this->openingDelimiter . "__" .
                    $innerblock . "__" . $this->closingDelimiter;
                $outer = str_replace(
                    $placeholder,
                    $this->blockdata[$innerblock],
                    $outer
                );
                $this->blockdata[$innerblock] = "";
            }
        }

        if (!$flag_recursion && 0 !== count($values)) {
            if ($this->_options['use_preg']) {
                $regs = array_map(
                    [
                        &$this,
                        '_addPregDelimiters'
                    ],
                    $regs
                );
                $funcReplace = 'preg_replace';
            } else {
                $funcReplace = 'str_replace';
            }

            if ($this->_options['preserve_data']) {
                $values = array_map(
                    [&$this, '_preserveOpeningDelimiter'],
                    $values
                );
            }

            $outer = $funcReplace($regs, $values, $outer);

            if ($this->removeUnknownVariables) {
                $outer = preg_replace($this->removeVariablesRegExp, "", $outer);
            }
        }

        if ($empty) {
            if (!$this->removeEmptyBlocks) {
                $this->blockdata[$block] .= $outer;
            } elseif (isset($this->touchedBlocks[$block])) {
                $this->blockdata[$block] .= $outer;
                unset($this->touchedBlocks[$block]);
            }
        } elseif (empty($this->blockdata[$block])) {
            $this->blockdata[$block] = $outer;
        } else {
            $this->blockdata[$block] .= $outer;
        }

        return $empty;
    }

    public function parseCurrentBlock(): bool
    {
        return $this->parse($this->currentBlock);
    }

    public function setVariable($variable, $value = ''): void
    {
        if (is_array($variable)) {
            $this->variableCache = array_merge(
                $this->variableCache,
                $variable
            );
        } else {
            $this->variableCache[$variable] = $value;
        }
    }

    public function setCurrentBlock(string $block = self::IT_DEFAULT_BLOCK): bool
    {
        if (!isset($this->blocklist[$block])) {
            throw new ilTemplateException($this->errorMessage(self::IT_BLOCK_NOT_FOUND) . '"' . $block . "'");
        }

        $this->currentBlock = $block;

        return true;
    }

    public function touchBlock(string $block): bool
    {
        if (!isset($this->blocklist[$block])) {
            throw new ilTemplateException($this->errorMessage(self::IT_BLOCK_NOT_FOUND) . '"' . $block . "'");
        }

        $this->touchedBlocks[$block] = true;

        return true;
    }

    protected function init(): void
    {
        $this->free();

        if (($blockdata = $this->block_cache->get($this->real_filename, new ListTransformation(new StringTransformation()))) !== null) {
            $this->blockdata = $blockdata['blockdata'];
            $this->blocklist = $blockdata['blocklist'];
        } else {
            $this->findBlocks($this->template);
            $blockdata['blockdata'] = $this->blockdata;
            $blockdata['blocklist'] = $this->blocklist;
            $this->block_cache->set($this->real_filename, $blockdata);
        }

        // we don't need it any more
        $this->template = '';

        if (($blockvariables = $this->variable_cache->get($this->real_filename))!==null) {
            $this->blockvariables = $blockvariables;
        } else {
            $this->buildBlockvariablelist();
            $this->variable_cache->set($this->real_filename, $this->blockvariables);
        }
    }

    public function free(): void
    {
        $this->err = [];

        $this->currentBlock = self::IT_DEFAULT_BLOCK;

        $this->variableCache = [];
        $this->blocklist = [];
        $this->touchedBlocks = [];

        $this->flagBlocktrouble = false;
        $this->flagGlobalParsed = false;
    }

    public function setTemplate(
        string $template,
        bool $removeUnknownVariables = true,
        bool $removeEmptyBlocks = true
    ): bool {
        $this->removeUnknownVariables = $removeUnknownVariables;
        $this->removeEmptyBlocks = $removeEmptyBlocks;

        if ($template === '' && $this->flagCacheTemplatefile) {
            $this->variableCache = [];
            $this->blockdata = [];
            $this->touchedBlocks = [];
            $this->currentBlock = self::IT_DEFAULT_BLOCK;
        } else {
            $this->template =
                '<!-- BEGIN ' . self::IT_DEFAULT_BLOCK . ' -->' .
                $template .
                '<!-- END ' . self::IT_DEFAULT_BLOCK . ' -->';
            $this->init();
        }

        if ($this->flagBlocktrouble) {
            return false;
        }

        return true;
    }

    public function loadTemplatefile(
        string $filename,
        bool $removeUnknownVariables = true,
        bool $removeEmptyBlocks = true
    ): bool {
        $template = '';
        if (!$this->flagCacheTemplatefile ||
            $this->lastTemplatefile !== $filename
        ) {
            $template = $this->getFile($filename);
        }
        $this->lastTemplatefile = $filename;

        return $template !== '' && $this->setTemplate(
            $template,
            $removeUnknownVariables,
            $removeEmptyBlocks
        );
    }

    public function setRoot(string $root): void
    {
        if ($root !== '' && substr($root, -1) !== '/') {
            $root .= '/';
        }

        $this->fileRoot = $root;
    }

    public function buildBlockvariablelist(): void
    {
        foreach ($this->blocklist as $name => $content) {
            preg_match_all($this->variablesRegExp, $content, $regs);

            if (count($regs[1]) !== 0) {
                foreach ($regs[1] as $var) {
                    $this->blockvariables[$name][$var] = true;
                }
            } else {
                $this->blockvariables[$name] = [];
            }
        }
    }

    public function findBlocks(string $string): array
    {
        $blocklist = [];
        if (preg_match_all($this->blockRegExp, $string, $regs, PREG_SET_ORDER)) {
            foreach ($regs as $match) {
                $blockname = $match[1];
                $blockcontent = $match[2];

                if (isset($this->blocklist[$blockname])) {
                    throw new ilTemplateException($this->errorMessage(self::IT_BLOCK_DUPLICATE, $blockname));
                }

                $this->blocklist[$blockname] = $blockcontent;
                $this->blockdata[$blockname] = "";

                $blocklist[] = $blockname;

                $inner = $this->findBlocks($blockcontent);
                foreach ($inner as $name) {
                    $pattern = sprintf(
                        '@<!--\s+BEGIN\s+%s\s+-->(.*)<!--\s+END\s+%s\s+-->@sm',
                        $name,
                        $name
                    );

                    $this->blocklist[$blockname] = preg_replace(
                        $pattern,
                        $this->openingDelimiter .
                        '__' . $name . '__' .
                        $this->closingDelimiter,
                        $this->blocklist[$blockname]
                    );
                    $this->blockinner[$blockname][] = $name;
                    $this->blockparents[$name] = $blockname;
                }
            }
        }

        return $blocklist;
    }

    public function getFile(string $filename): string
    {
        if ($filename[0] === '/' && substr($this->fileRoot, -1) === '/') {
            $filename = substr($filename, 1);
        }

        $filename = $this->fileRoot . $filename;

        $this->real_filename = $filename;

        if (($content = $this->template_cache->get($filename, new StringTransformation())) === null) {
            if (!($fh = @fopen($filename, 'rb'))) {
                throw new ilTemplateException($this->errorMessage(self::IT_TPL_NOT_FOUND) . ': "' . $filename . '"');
            }

            $fsize = filesize($filename);
            if ($fsize < 1) {
                fclose($fh);
                return '';
            }

            $content = fread($fh, $fsize);
            $this->template_cache->set($filename, $content);
            fclose($fh);
        }

        return $content;
    }

    public function _addPregDelimiters(string $str): string
    {
        return '@' . $str . '@';
    }

    public function _preserveOpeningDelimiter(string $str): string
    {
        return (false === strpos($str, $this->openingDelimiter)) ?
            $str :
            str_replace(
                $this->openingDelimiter,
                $this->openingDelimiter .
                '%preserved%' . $this->closingDelimiter,
                $str
            );
    }

    public function errorMessage(int $value, string $blockname = ''): string
    {
        static $errorMessages;
        if (!isset($errorMessages)) {
            $errorMessages = [
                self::IT_OK => '',
                self::IT_ERROR => 'unknown error',
                self::IT_TPL_NOT_FOUND => 'Cannot read the template file',
                self::IT_BLOCK_NOT_FOUND => 'Cannot find this block',
                self::IT_BLOCK_DUPLICATE => 'The name of a block must be' .
                    ' uniquewithin a template.' .
                    ' Found "' . $blockname . '" twice.' .
                    'Unpredictable results ' .
                    'may appear.',
                self::IT_UNKNOWN_OPTION => 'Unknown option'
            ];
        }

        return $errorMessages[$value] ?? $errorMessages[self::IT_ERROR];
    }
}