Функция cot_parse_autourls в Cotonti

Функция предназначена для того, чтобы автоматически находить в тексте все URL-адреса, начинающиеся с http, https или ftp, и преобразовывать их в HTML-ссылки.

Давайте разберем эту функцию cot_parse_autourls в контексте PHP-фреймворка Cotonti.

 

/**
 * Automatically detect and parse URLs in text into HTML
 *
 * @param string $text Text body
 * @return string
 */
function cot_parse_autourls($text)
{
    $text = preg_replace('`(^|\s)(http|https|ftp)://([^\s"\'\[]+)`', '$1<a href="$2://$3">$2://$3</a>', $text);
    return $text;
}

1. Документация функции cot_parse_autourls

Параметр:
$text — это текст, который будет проверяться на наличие URL.
Возвращаемое значение: Функция возвращает обработанный текст, в котором URL-адреса преобразованы в HTML-ссылки.

2. Основная логика функции cot_parse_autourls

Внутри функции используется регулярное выражение preg_replace, которое ищет URL в тексте и заменяет их на HTML-ссылки.

preg_replace('`(^|\s)(http|https|ftp)://([^\s"\'\[]+)`', '$1<a href="$2://$3">$2://$3</a>', $text);

Разберем это регулярное выражение и замену по частям:

preg_replace — это функция, которая выполняет поиск и замену с использованием регулярных выражений. В нашем случае она ищет все URL-адреса, начинающиеся с http, https или ftp, и заменяет их на HTML-ссылки.

Регулярное выражение:

(^|\s) — Эта часть регулярного выражения ищет начало строки или пробельный символ (например, пробел, табуляция). Это необходимо для того, чтобы URL был разделен от предыдущего текста пробелом или стоял в начале строки.
(http|https|ftp) — Это группа, которая ищет протоколы http, https или ftp. Таким образом, только URL-адреса, начинающиеся с этих протоколов, будут найдены.

:// — После протокола ожидается ://, что является частью URL.
([^\s"\'\[]+) — Это выражение ищет саму часть URL, которая состоит из любых символов, кроме пробела, кавычек и квадратных скобок. Это необходимо для того, чтобы корректно обрабатывать конец URL, не включая в ссылку лишние символы (например, пробел или кавычки).

Заменяющая строка:

$1<a href="$2://$3">$2://$3</a> — Это строка, которая будет заменять найденный URL.
$1 — это либо начало строки, либо пробел (что бы URL не терял свою позицию в тексте).
$2 и $3 — это части URL, где $2 — это протокол (http, https или ftp), а $3 — это сам адрес URL.

Результатом будет строка вида <a href="http://example.com">http://example.com</a>, т.е. URL преобразуется в HTML-ссылку.
В результате, если в тексте есть ссылки типа http://example.com, они будут преобразованы в HTML-ссылки, которые можно будет кликать.

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

После того как все URL-адреса в тексте были обработаны и преобразованы в HTML-ссылки, функция возвращает обновленный текст. Если в тексте не было найдено URL, то текст останется без изменений.

4. Пример работы функции cot_parse_autourls

Входной текст:

Check out this website: http://example.com and this one https://another-site.com

После обработки:

Check out this website: <a href="http://example.com">http://example.com</a> and this one <a href="https://another-site.com">https://another-site.com</a>

Заключение:
Функция cot_parse_autourls очень полезна для автоматического преобразования URL-адресов в тексте в кликабельные HTML-ссылки. Она позволяет легко обеспечить обработку ссылок в текстах на сайте без необходимости вручную вставлять теги <a>.

 

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

Давайте разберем выражение в контексте логики PHP-фреймворка Cotonti.

'FORUMS_NEWTOPIC_SUBTITLE' => htmlspecialchars(cot_parse_autourls(Cot::$structure['forums'][$s]['desc'])),

Структура выражения

'FORUMS_NEWTOPIC_SUBTITLE' — Это ключ массива или шаблонный тег, который будет использоваться для вывода текста в соответствующем месте на сайте.

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

cot_parse_autourls(...) — Это функция, которая автоматически находит URL-адреса в тексте и преобразует их в HTML-ссылки. Подробнее мы уже рассматривали её в предыдущих объяснениях. В данном контексте она применяется для преобразования всех URL в текстовом описании форума в кликабельные ссылки.

Cot::$structure['forums'][$s]['desc'] — Это доступ к описанию форума, хранящемуся в структуре сайта (обычно в массиве, где Cot::$structure['forums'] — это массив с данными о форумах). Переменная $s содержит индекс или ключ конкретного форума, а 'desc' — это описание форума (вероятно, текстовое поле с кратким описанием).

Логика работы
Cot::$structure['forums'][$s]['desc']:

Из массива Cot::$structure берется раздел forums, который содержит информацию о форумах.
$s — это индекс или ключ текущего форума.
'desc' — это описание форума, которое может содержать текст с описанием форума, включая URL-адреса.
cot_parse_autourls(...):

На этом этапе текст из 'desc' передается в функцию cot_parse_autourls, которая находит URL-адреса и преобразует их в кликабельные ссылки.

Например, если описание форума содержит текст вроде "Перейдите на сайт: http://example.com", то после обработки этот текст будет преобразован в: "Перейдите на сайт: <a href='http://example.com'>http://example.com</a>".
htmlspecialchars(...):

После того как все URL были преобразованы в ссылки, текст передается в функцию htmlspecialchars.
Это необходимо для того, чтобы избежать интерпретации потенциального HTML-кода в тексте (если, например, в описании форума содержатся символы, такие как <, >, или кавычки).
htmlspecialchars преобразует такие символы в безопасные HTML-сущности. Например:
< становится &lt;
> становится &gt;
& становится &amp;
и т.д.
Это гарантирует, что текст не будет интерпретироваться как HTML-код, что важно для предотвращения уязвимостей в безопасности (например, XSS-атак).

Результат:

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

Текст будет содержать только корректно экранированные символы, а URL будут отображаться как кликабельные ссылки.

Пример работы
Предположим, что описание форума (Cot::$structure['forums'][$s]['desc']) выглядит так:

Добро пожаловать на наш форум! Посетите наш сайт: http://example.com для получения дополнительной информации.
После того, как мы передаем этот текст в cot_parse_autourls, URL будет преобразован в HTML-ссылку:

Добро пожаловать на наш форум! Посетите наш сайт: <a href="http://example.com">http://example.com</a> для получения дополнительной информации.

Затем, htmlspecialchars экранирует все специальные символы (если они есть):

Например, если описание форума содержит символы < или >, то они будут экранированы в их HTML-эквиваленты.
В нашем примере это не потребуется, так как в тексте нет таких символов, но если бы они были, например, <b>, то это было бы преобразовано в &lt;b&gt;.

Результатом будет безопасная и корректно отображаемая строка, которая может быть использована в шаблоне:

Добро пожаловать на наш форум! Посетите наш сайт: <a href="http://example.com">http://example.com</a> для получения дополнительной информации.

Заключение
Это выражение позволяет корректно обработать описание форума, автоматически преобразовать URL в ссылки и предотвратить возможные проблемы с безопасностью. Использование htmlspecialchars помогает избежать выполнения нежелательного HTML-кода, а cot_parse_autourls делает текст более удобным, добавляя кликабельные ссылки.