Файл cotemplate.php в Cotonti

Основное назначение файла cotemplate.php в системной папке Cotonti CMF — это реализация системы шаблонов (или движка шаблонов), которая используется для рендеринга различных компонентов на сайте. Этот файл является частью ядра фреймворка и отвечает за обработку шаблонов, работу с переменными, их обработку и вычисление, а также за функции, связанные с шаблонной логикой и выводом информации на страницы.

Основное назначение:

Файл cotemplate.php предоставляет функциональность для работы с шаблонами в системе, в частности:

• Разделение шаблонов на блоки и переменные.
• Разбор и обработка данных, передаваемых в шаблоны.
• Осуществление рендеринга шаблонов с учётом различных операций (например, фильтрация данных, обработка переменных, выполнение функций).
• Обеспечение взаимодействия шаблонов с другими частями системы, такими как глобальные переменные PHP и другие данные, передаваемые через шаблонный движок.

Ключевые особенности:

• Использование синтаксиса шаблонов с переменными и встроенными функциями.
• Поддержка функций обратного вызова, которые могут быть использованы для динамического вычисления значений в шаблонах.
• Возможность обработки и отладки данных, используемых в шаблонах.

Суть содержания кода:

Код включает в себя различные функции и классы, которые позволяют:

1. Осуществлять рендеринг данных и переменных в шаблонах.
2. Работать с переменными в шаблонах (например, извлечение значений переменных, обработка выражений).
3. Поддерживать выполнение функций и методов внутри шаблонов с передачей параметров.
4. Работать с синтаксисом шаблонов, включая фильтры и другие обработки (например, cotpl_tokenize для разбора строк).
5. Управлять динамическими переменными и их вычислением на основе контекста.

Определение класса XTemplate, который используется для работы с шаблонами в Cotonti. Методы для загрузки, обработки и рендеринга шаблонов (.tpl).

/**
 * Библиотека класса CoTemplate. Быстрый и легковесный шаблонный движок на основе блоков. // Перевод заголовочного комментария
 * - Совместимость с XTemplate (http://www.phpxtemplate.org) // Перевод: совместимость с XTemplate
 * - Компиляция в объекты PHP // Перевод: компиляция шаблонов в PHP-объекты
 * - Специально для Cotonti // Перевод: предназначено для системы Cotonti
 *
 * @package API - CoTemplate // Указывает, что данный файл принадлежит API CoTemplate
 * @version 2.8.5 // Версия шаблонного движка
 * @copyright (c) Cotonti Team // Авторские права принадлежат команде Cotonti
 * @license https://github.com/Cotonti/Cotonti/blob/master/License.txt // Лицензия на использование библиотеки
 */

/**
 * Минималистичная реализация XTemplate для Cotonti // Перевод заголовочного комментария о назначении класса
 */
class XTemplate // Объявление класса XTemplate для реализации шаблонного движка
{

/**
 * @var string Template file name
 */
public $filename = ''; // Переменная $filename хранит имя файла шаблона, по умолчанию пустая строка.

/**
 * @var array Assigned template vars
 */
public $vars = []; // Массив $vars используется для хранения переменных, назначенных в шаблоне.

/**
 * @var Cotpl_block[] Blocks
 */
protected $blocks = []; // Массив $blocks содержит объекты блоков шаблона типа Cotpl_block. Защищённый доступ ограничивает прямое изменение извне.

/**
 * @var array Blocks already displayed (for debug mode)
 */
protected $displayed_blocks = []; // Массив $displayed_blocks отслеживает блоки, которые уже были отображены, в основном для режима отладки.

/**
 * Maps block paths to actual array indices.
 * @var array Index for quick block search.
 */
protected $index = []; // Массив $index сопоставляет пути блоков с индексами массива для быстрого поиска нужного блока.

/**
 * Contains a list of names of all tags present in the template
 * @var array
 */
protected $tags = null; // Переменная $tags хранит список имён всех тегов, присутствующих в шаблоне. По умолчанию значение равно null.

/**
 * @var bool Enables disk caching of precompiled templates
 */
protected static $cacheEnabled = false; // Переменная $cacheEnabled включает или отключает кэширование предварительно скомпилированных шаблонов на диске. По умолчанию отключено.

/**
 * @var string Cache directory path
 */
protected static $cacheDir = ''; // Переменная $cacheDir хранит путь к директории для кэша шаблонов, по умолчанию пустая строка.

/**
 * @var array Stores debug data
 */
protected static $debugData = []; // Массив $debugData используется для хранения данных отладки, которые могут быть полезны при анализе работы шаблонов.

/**
 * @var bool Enables debug dumping
 */
protected static $debugMode = false; // Переменная $debugMode включает или отключает режим отладки. По умолчанию режим отладки выключен.

/**
 * @var bool Prints debug mode screen
 */
protected static $debugOutput = false; // Переменная $debugOutput отвечает за вывод экрана отладки. По умолчанию вывод отключён.

/**
 * Enables space removal for compact output
 * @var bool
 */
private static $cleanupEnabled = false; // Переменная $cleanupEnabled включает удаление лишних пробелов для компактного вывода. По умолчанию отключено.

/**
 * @var bool Indicates that root-level blocks were found during another run
 */
private $found = false; // Переменная $found указывает, были ли найдены блоки верхнего уровня в ходе предыдущего выполнения. По умолчанию значение false.

    /**
     * Упрощённый конструктор
     *
     * @param string $path Имя файла шаблона
     */
    public function __construct($path = null) // Объявляется конструктор класса XTemplate, принимающий путь к шаблону.
    {
        // Применение переопределений темы, если они необходимы
        global $theme_reload; // Используется глобальная переменная $theme_reload для работы с переопределениями темы.

        if (is_array($theme_reload)) { // Проверяется, является ли $theme_reload массивом.
            foreach ($theme_reload as $keyReload => $valueReload) { // Перебираются все элементы массива $theme_reload.
                $GLOBALS[$keyReload] = (is_array($GLOBALS[$keyReload]) && is_array($valueReload)) 
                    ? array_merge($GLOBALS[$keyReload], $valueReload) // Если оба значения массивы, выполняется их слияние.
                    : $valueReload; // Иначе значение $valueReload напрямую присваивается глобальной переменной.
            }
        }
        if (is_string($path)) { // Проверяется, является ли переданный параметр $path строкой.
            $this->restart($path); // Если это строка, вызывается метод restart() для инициализации шаблона с указанным именем файла.
        }
    }

• Конструктор __construct служит для первичной инициализации объекта шаблона.
• Если глобальная переменная $theme_reload содержит массив, то её содержимое объединяется с текущими глобальными переменными.
• Метод restart($path) вызывается для инициализации шаблона, если передан путь к файлу шаблона в виде строки.

    /**
     * Представление объекта CoTemplate в виде TPL-кода для отладки
     *
     * @return string
     */
    public function __toString() // Метод возвращает объект в виде строки, представляющей TPL-код.
    {
        $str = ''; // Инициализируется пустая строка для формирования результата.
        foreach ($this->blocks as $name => $block) { // Перебираются все блоки в шаблоне.
            $str .= "<!-- BEGIN: $name -->\n" . $block->__toString() . "<!-- END: $name -->\n"; 
            // Добавляются маркеры начала и конца блока с его именем, а также содержимое блока, преобразованное в строку.
        }
        return $str; // Возвращается строковое представление всех блоков шаблона.
    }

• Цель метода: Предоставить удобное представление объекта шаблона для отладки. Он преобразует все блоки в строку, включая их содержимое, в формате, похожем на оригинальный TPL-код.
• Переменная $this->blocks: Содержит массив всех блоков шаблона, где ключи — это имена блоков, а значения — объекты блоков.
• Формирование строки:
  • Для каждого блока создаётся строка, содержащая HTML-комментарии <!-- BEGIN: <name> --> и <!-- END: <name> -->.
  • Между комментариями добавляется содержимое блока, преобразованное в строку через его метод __toString().
• Применение: Этот метод полезен для отладки, когда требуется вывести структуру шаблона и его содержимое в читаемом виде.

    /**
     * Назначает переменную шаблона или массив переменных
     *
     * @param mixed $name Имя переменной или массив значений
     * @param mixed $val Значение тега, если $name не является массивом
     * @param string $prefix Необязательный префикс для ключей переменных
     * @return XTemplate Возвращает текущий объект для возможности цепочки вызовов
     */
    public function assign($name, $val = NULL, $prefix = '')
    {
        if (is_array($name)) { // Проверяем, является ли $name массивом.
            foreach ($name as $key => $val) { // Перебираем массив $name, где $key — ключ, а $val — значение.
                $this->vars[$prefix.$key] = $val; // Формируем ключ с префиксом и присваиваем значение переменной в массиве $vars.
            }
        } else { // Если $name не массив, обрабатываем его как одиночную переменную.
            $this->vars[$prefix.$name] = $val; // Формируем ключ с префиксом и присваиваем значение переменной в массиве $vars.
        }

        return $this; // Возвращаем текущий объект для возможности последовательных вызовов (chaining).
    }

• Функция назначения переменных:

  • Функция используется для добавления одной или нескольких переменных в шаблон.
  • Можно передать либо массив значений, либо одиночную переменную.

• Массив $this->vars:

  • Это внутреннее хранилище всех переменных, назначенных в шаблон.
  • Ключи могут быть сформированы с добавлением необязательного префикса.

• Обработка массива переменных:

  • Если $name — массив, функция перебирает все его элементы.
  • Каждая пара ключ-значение записывается в массив $this->vars, при этом к ключу добавляется префикс (если он указан).

• Обработка одиночной переменной:

  • Если $name — строка, то она становится ключом, а $val — её значением. Ключ также дополняется префиксом.

• Возврат объекта $this:

  • Возврат текущего объекта позволяет вызывать методы цепочкой, например:

$tpl->assign('title', 'Главная страница')->assign('content', 'Добро пожаловать!');

Применение префикса:

• Префикс полезен для уникальности ключей или группировки переменных. Например, переменные одной секции шаблона могут иметь общий префикс: header_title, header_logo.

// Пример с одиночной переменной
$tpl->assign('title', 'Мой сайт');

// Пример с массивом переменных
$tpl->assign(['title' => 'Мой сайт', 'footer' => 'Все права защищены']);

    /**
     * Возвращает отладочные данные, собранные CoTemplate, если включена опция отладки.
     * Отладочные данные имеют следующий формат:
     * <code>
     * array(
     * 	'filename.tpl' => array( // Имя файла шаблона
     * 		'BLOCK.NAME' => array( // Имя блока в шаблоне
     * 			'TAG_NAME' => 'tag value', // Имя тега и его значение
     * 			// ...
     * 		),
     * 		// ...
     * 	),
     * 	// ...
     * );
     * </code>
     *
     * @return array Массив отладочных данных
     */
    public static function debugData()
    {
        return self::$debugData; // Возвращает статическое свойство $debugData, содержащее собранные отладочные данные.
    }

Пояснения:

1. Функция debugData:

   • Эта функция используется для получения отладочных данных, собранных движком шаблонов CoTemplate.
   • Она возвращает массив, в котором описаны имена файлов шаблонов, блоки и значения тегов, обработанные движком.

2. Формат данных:

   • Каждому файлу шаблона соответствует массив блоков.
   • Каждый блок включает массив тегов и их значений.

3. Статическое свойство $debugData:

   • Это свойство хранит все отладочные данные, которые были собраны в процессе выполнения шаблонов, при условии, что включён режим отладки.

4. Назначение функции:

   • Используется разработчиками для анализа данных, переданных и обработанных шаблонами.
   • Полезно для проверки правильности работы блоков и тегов в шаблонах.

Пример отладочных данных:

array(
    'example.tpl' => array(
        'MAIN.BLOCK' => array(
            'TITLE' => 'Заголовок страницы',
            'CONTENT' => 'Содержимое страницы'
        ),
        'FOOTER.BLOCK' => array(
            'FOOTER_TEXT' => 'Текст внизу страницы'
        )
    )
);

Использование:

$debugInfo = XTemplate::debugData(); // Получить массив отладочных данных
print_r($debugInfo); // Вывести отладочные данные для анализа

    /**
     * Вывод отладочной информации о теге и его текущем значении.
     *
     * @param string $name Имя тега.
     * @param mixed $value Значение тега, будет преобразовано в строку.
     * @return string Строка, представляющая элемент списка для вывода отладочной информации.
     */
    public static function debugVar($name, $value)
    {
        if (is_numeric($value)) { // Проверка, является ли значение числовым.
            $val_disp = (string) $value; // Если да, приводим значение к строке.
        } elseif (is_object($value)) { // Проверка, является ли значение объектом.
            $val_disp = get_class($value) . ' ' . json_encode((array)$value); // Получаем имя класса объекта и сериализуем его свойства в JSON.
        } else { 
            if (!is_string($value)) { // Если значение не строка.
                $value = (string) $value; // Приводим значение к строке.
            }
            $val_disp = '"' . htmlspecialchars($value) . '"'; // Экранируем специальные символы в строке для HTML и заключаем её в кавычки.
        }
        // Формируем строку HTML для вывода отладочной информации: имя тега и его значение.
        return '<li>{' . htmlspecialchars($name) . '} =&gt; <em>' . $val_disp . '</em></li>';
    }

Пояснения:

1. Назначение функции debugVar:

   • Эта функция используется для создания HTML-элемента <li> с отладочной информацией о теге (его имени и значении).
   • Вывод пригоден для использования в списках HTML.

2. Параметры:

   • $name — имя тега. Оно отображается в фигурных скобках.
   • $value — значение тега. Может быть числом, объектом или любым другим типом данных, который будет приведён к строке.

3. Логика обработки значения $value:

   • Число: Преобразуется в строку.
   • Объект: Определяется класс объекта, его свойства сериализуются в JSON.
   • Другие типы: Преобразуются в строку, если ещё не являются строкой. Затем значение экранируется для безопасного отображения в HTML.

4. Использование htmlspecialchars:

   • Эта функция предотвращает выполнение вредоносного кода (например, JavaScript), экранируя специальные символы (<, >, &, ").

5. Результат работы функции:

   • Возвращается HTML-строка, представляющая элемент списка <li>:

<li>{TAG_NAME} =&gt; <em>"Значение"</em></li>

Пример использования:

echo XTemplate::debugVar('TITLE', 'Привет, мир!');
// Вывод:
// <li>{TITLE} =&gt; <em>"Привет, мир!"</em></li>

Особенности:

• Функция полезна для вывода структурированной отладочной информации в удобном для чтения HTML-формате.
• Обрабатывает сложные типы данных, такие как объекты, безопасно и информативно.

    /**
     * Возвращает текущее значение переменной шаблона.
     *
     * @param string $name Имя переменной.
     * @return mixed Значение переменной.
     */
    public function get($name)
    {
        return $this->vars[$name]; // Возвращает значение переменной из массива $this->vars по её имени.
    }

Пояснение:

1. Назначение функции get:

   • Функция предназначена для получения значения переменной шаблона по её имени.

2. Параметр:

   • $name — имя переменной, значение которой требуется получить.

3. Возвращаемое значение:

   • Возвращает значение из массива $this->vars, которое соответствует переданному имени $name.

4. Как это работает:

   • Внутри объекта класса XTemplate переменные шаблона хранятся в ассоциативном массиве $this->vars, где ключами являются имена переменных, а значениями — их текущие значения.
   • При вызове этой функции она просто возвращает значение, связанное с указанным ключом $name.

5. Пример использования:

$template = new XTemplate();
$template->assign('TITLE', 'Заголовок страницы'); // Назначаем значение переменной.
echo $template->get('TITLE'); // Выведет: Заголовок страницы.

Особенности:

• Если переменной с указанным именем $name не существует в массиве $this->vars, PHP вернёт NULL или вызовет предупреждение, если включены строгие уведомления.
• Удобно для доступа к значениям переменных в шаблоне во время выполнения кода.

    /**
     * Возвращает список всех тегов, присутствующих в шаблоне.
     * 
     * @return array Список имен всех тегов.
     */
    public function getTags()
    {
        if (is_null($this->tags)) { // Проверяем, равна ли переменная $this->tags значению null.
            // Собираем все теги.
            $this->tags = []; // Инициализируем пустой массив для хранения тегов.
            foreach ($this->blocks as $block) { // Проходим по всем блокам шаблона.
                $this->tags = array_merge($this->tags, $block->getTags()); // Объединяем текущие теги с тегами блока.
            }
        }
        return array_keys($this->tags); // Возвращаем список ключей (имен тегов) из массива $this->tags.
    }

Пояснение:

1. Назначение функции getTags:

   • Эта функция собирает и возвращает список всех тегов, которые присутствуют в текущем шаблоне.

2. Как работает:

   • Если массив $this->tags ещё не инициализирован (null), функция выполняет его заполнение.
   • Пробегает по всем блокам шаблона, извлекая их теги с помощью метода getTags() каждого блока.
   • Все найденные теги объединяются в массив $this->tags.

3. Возвращаемое значение:

   • Функция возвращает массив, состоящий из всех уникальных имён тегов, присутствующих в шаблоне. Используется array_keys для получения списка ключей из массива тегов.

4. Параметры:

   • У метода нет входных параметров.

5. Пример работы:

$template = new XTemplate('template.tpl');
$tags = $template->getTags();
print_r($tags); // Выведет массив с именами всех тегов, найденных в шаблоне.

• Особенности:

  • Массив $this->tags инициализируется только один раз, чтобы избежать повторного выполнения ресурсоёмкого процесса сборки тегов.
  • Метод getTags() каждого блока вызывается для получения тегов из вложенных блоков.

• Реализация на практике:

  • Этот метод полезен для отладки или анализа шаблона, чтобы быстро получить список всех доступных тегов.

    /**
     * Возвращает TRUE, если блок присутствует в шаблоне, или FALSE в противном случае.
     *
     * @param string $name Полное имя блока, включая точки и родительские блоки.
     * @return boolean TRUE, если блок найден, иначе FALSE.
     */
    public function hasBlock($name)
    {
        return isset($this->index[$name]); // Проверяем, существует ли указанный блок в массиве индексов $this->index.
    }

Пояснение:

1. Назначение функции hasBlock:

   • Функция проверяет, существует ли указанный блок в текущем шаблоне.

2. Как работает:

   • Метод принимает параметр $name, который представляет полное имя блока. Полное имя включает вложенность блоков, разделённую точками, например: MAIN.BLOCK.SUBBLOCK.
   • Проверяется массив $this->index, который выступает в роли индекса для быстрого поиска блоков. Если ключ с именем блока существует в этом массиве, возвращается TRUE, иначе — FALSE.

3. Параметры:

   • $name — строка, содержащая имя искомого блока. Имя должно быть указано в формате, соответствующем структуре шаблона.

4. Возвращаемое значение:

   • Булевое значение:
     • TRUE, если блок найден.
     • FALSE, если блок отсутствует.

5. Пример работы:

$template = new XTemplate('template.tpl');
if ($template->hasBlock('MAIN.BLOCK')) {
    echo "Блок существует!";
} else {
    echo "Блок отсутствует.";
}

• Массив $this->index:

  • Этот массив содержит индекс всех блоков, присутствующих в шаблоне, для ускорения поиска. Ключами являются имена блоков, а значениями — соответствующие данные о блоках.

• Применение:

  • Этот метод полезен для проверки существования блока перед его обработкой или отображением. Он предотвращает ошибки, связанные с попыткой работы с несуществующими блоками.

• Особенность:

  • Метод работает быстро благодаря использованию массива $this->index и функции isset, которая оптимизирована для проверки существования ключей.

    /**
     * Возвращает TRUE, если тег присутствует в шаблоне, или FALSE в противном случае.
     *
     * @param string $name Имя тега (чувствительно к регистру).
     * @return boolean TRUE, если тег найден, иначе FALSE.
     */
    public function hasTag($name)
    {
        if (is_null($this->tags)) { // Проверяем, инициализирован ли массив $this->tags.
            $this->getTags(); // Если массив $this->tags не инициализирован, вызываем метод getTags() для сбора всех тегов.
        }
        return isset($this->tags[$name]); // Проверяем, существует ли указанный тег в массиве $this->tags.
    }