Функция cot_parse в Cotonti

Общая цель функции:
Функция cot_parse используется для обработки текста, применяя к нему один из парсеров, если это требуется. Парсеры могут использоваться для добавления разметки (например, BB-кодов или Markdown) в текст или для его обработки в другом формате. Важно, что текст может быть представлен как в обычном виде, так и с поддержкой разметки.

/**
 * Parses text body
 *
 * @param string $text Source text
 * @param bool $enable_markup Enable markup or plain text output
 * @param string $parser Non-default parser to use
 * @return string
 */
function cot_parse($text, $enable_markup = true, $parser = '')
{
	global $cot_plugins;

	$plain = true;
	if ($enable_markup) {
		if (empty($parser)) {
			$parser = Cot::$cfg['parser'];
		}
		if (!empty($parser) && $parser != 'none') {
			$func = "cot_parse_$parser";
			if (function_exists($func)) {
				$text = $func($text);
				$plain = false;
			} else {
				// Load the appropriate parser
				if (isset($cot_plugins['parser']) && is_array($cot_plugins['parser'])) {
					foreach ($cot_plugins['parser'] as $k) {
						if ($k['pl_code'] == $parser && cot_auth('plug', $k['pl_code'], 'R')) {
							include Cot::$cfg['plugins_dir'] . '/' . $k['pl_file'];
							$text = $func($text);
							$plain = false;
							break;
						}
					}
				}
			}
		}
	}

	if ($plain && !empty($text)) {
		$text = nl2br(htmlspecialchars($text));
	}

	/* == Hook == */
	foreach (cot_getextplugins('parser.last') as $pl) {
		include $pl;
	}
	/* ===== */

	return $text;
}

Давайте подробно разберем функцию cot_parse в контексте логики работы PHP-фреймворка Cotonti:
Разбор по шагам:

Параметры функции cot_parse:

$text: Текст, который необходимо обработать.
$enable_markup: Булев параметр, который включает поддержку разметки (по умолчанию — включена).
$parser: Указывает, какой конкретно парсер должен быть использован (если не задан, используется парсер по умолчанию).
Переменная $plain:

Это переменная, которая изначально установлена в true. Она будет использоваться, чтобы определить, был ли текст преобразован с использованием парсера, или остался в "чистом" виде.
Проверка на разметку:

Если $enable_markup установлено в true и не указан конкретный парсер ($parser), то используется парсер по умолчанию из настроек (Cot::$cfg['parser']).

Если парсер не равен 'none' (то есть поддержка разметки активирована), то функция пытается найти соответствующий парсер и выполнить его.

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

Если парсер задан:
Функция формирует имя функции парсера (например, если парсер называется bbcode, то будет вызвана функция cot_parse_bbcode).
Если такая функция существует, она вызывается, и текст обрабатывается этим парсером.
Если парсер не установлен:
Происходит перебор плагинов, чтобы найти парсер, который соответствует переданному значению $parser. Для этого проверяется список парсеров в массиве $cot_plugins['parser'].
Если плагин найден и у пользователя есть права на его использование (проверяется с помощью cot_auth), подключается файл плагина, и его парсер применяется.
Обработка текста, если парсер не использовался (plain текст):

Если после попытки использования парсера текст остался в обычном виде (переменная $plain осталась равной true), то применяется стандартная обработка текста: конвертирование символов в HTML-сущности и замена переносов строк на <br>.
Вставка плагинов через хуки:

После основного процесса парсинга вызываются дополнительные плагины с помощью функции cot_getextplugins('parser.last'). Это позволяет подключать дополнительные расширения или фильтры, которые могут изменять текст после применения основного парсера.
Возврат результата:

Функция возвращает обработанный текст, который может быть как обычным (если парсер не использовался), так и с примененной разметкой.
Пример использования:
Если на сайте используется парсер BBCode, то при вызове cot_parse($text, true, 'bbcode') текст будет обработан с помощью функции парсера cot_parse_bbcode, преобразуя BB-коды в HTML-разметку. Если парсер не задан или отключен, текст будет просто преобразован в HTML, заменив специальные символы на их эквиваленты.

Важные моменты:
Если парсер по умолчанию не настроен или передан неправильный парсер, то текст будет обработан как обычный текст.
Функция позволяет использовать плагины для добавления новых парсеров, которые могут быть подключены динамически.
Разделение текста на обработанный с разметкой и обычный текст важно для корректного отображения контента на сайте.

Заключение:
Функция cot_parse является важным инструментом для обработки текста в PHP-фреймворке Cotonti, позволяя пользователям применять различные парсеры (BBCode, Markdown и другие) или просто выводить текст с минимальными преобразованиями.

 

Пример использования функции cot_parse в Cotonti

Давайте разберем выражение, в котором используется эта функция и подробно объясним, как оно работает в контексте PHP-фреймворка Cotonti.

'FORUMS_POSTS_ROW_TEXT' => cot_parse($row['fp_text'], (Cot::$cfg['forums']['markup'] && Cot::$cfg['forums']['cat_' . $s]['allowbbcodes'])),

1. 'FORUMS_POSTS_ROW_TEXT'
Это строка, которая используется как ключ массива. Мы видим, что данное выражение используется для того, чтобы добавить значение в массив, где 'FORUMS_POSTS_ROW_TEXT' является ключом, этот массив используется для отображения текста в шаблоне форума.

2. cot_parse($row['fp_text'], ...)

Это вызов функции cot_parse, которая была ранее рассмотрена. В этой функции происходит обработка текста, который передается в качестве первого аргумента — в данном случае, текст сообщения форума, который хранится в $row['fp_text'].

Первый аргумент — это сам текст сообщения форума. Текст извлекается из базы данных и помещается в переменную $row['fp_text'].
Второй аргумент — это параметр, который указывает, должна ли разметка (например, BB-коды) быть включена для этого текста.

3. Условие для второго аргумента:

Второй аргумент для cot_parse определяет, нужно ли активировать разметку для текста. Рассмотрим это условие:

Cot::$cfg['forums']['markup'] && Cot::$cfg['forums']['cat_' . $s]['allowbbcodes']

Cot::$cfg['forums']['markup']: Это переменная конфигурации Cotonti, которая определяет, разрешена ли разметка для форума. Если это значение true, значит, разметка активирована и тексты сообщений могут содержать разметку (например, BB-коды).
Cot::$cfg['forums']['cat_' . $s]['allowbbcodes']: Это еще одна настройка, которая проверяет, разрешена ли разметка для конкретной категории форума. Значение $s — это идентификатор категории, и эта переменная проверяет, разрешено ли использовать BB-коды в данной категории форума. Если в категории это разрешено, значение будет true.

Условие целиком проверяет два параметра:

Включена ли разметка на форуме (из первой настройки markup).
Разрешены ли BB-коды для текущей категории форума (из второй настройки allowbbcodes).
Если оба условия истинны, то разметка будет включена при обработке текста. В противном случае — текст будет обработан без разметки.

4. Что делает cot_parse с этим условием?

Если разметка включена (оба условия истинны), то текст сообщения будет обработан с использованием парсера, например, BB-кодов или другого парсера, установленного на сайте. Это означает, что любые BB-коды в сообщении будут преобразованы в HTML-разметку, и текст будет отображаться с нужным форматированием.

Если разметка не разрешена (если хотя бы одно из условий не выполнено), то текст будет просто выведен как есть, без какой-либо разметки. В этом случае функция cot_parse применит стандартное преобразование текста (например, замена переносов строк на <br> и экранирование HTML-символов).

Важные моменты:
cot_parse — это функция, которая позволяет гибко обрабатывать текст, добавляя или не добавляя разметку в зависимости от настроек форума и категории.

Условие
 
(Cot::$cfg['forums']['markup'] && Cot::$cfg['forums']['cat_' . $s]['allowbbcodes'])

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

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