Parsedown: Быстрый и расширяемый Markdown парсер для PHP

Введение

Markdown стал де-факто стандартом для форматирования текста в вебе. Он прост в использовании, читаем и легко конвертируется в HTML. Если вам нужен Markdown парсер для вашего PHP-проекта, Parsedown – отличный выбор. Эта статья расскажет, что такое Parsedown, как его установить и использовать.

Что такое Parsedown?

Parsedown – это быстрый и расширяемый Markdown парсер, написанный на PHP. Он преобразует текст, написанный на Markdown, в валидный HTML-код. Вот основные преимущества Parsedown:

• Скорость: Parsedown известен своей высокой производительностью. Он значительно быстрее многих других PHP-парсеров Markdown.
• Расширяемость: Parsedown легко расширяется с помощью пользовательских функций и классов. Вы можете добавлять поддержку новых элементов Markdown или изменять поведение существующих.
• Соответствие спецификациям: Parsedown стремится соответствовать спецификации CommonMark, обеспечивая единообразие и предсказуемость обработки Markdown.
• Безопасность: Parsedown включает функции для предотвращения XSS-атак, что делает его безопасным для использования в production-средах.
• Простота использования: Parsedown имеет простой и понятный API.

Установка Parsedown

Есть два основных способа установки Parsedown:

1. Через Composer (рекомендуется):Composer – это менеджер зависимостей для PHP. Если вы используете Composer, установка Parsedown очень проста. Откройте терминал в корне вашего проекта и выполните команду:composer require erusev/parsedownЭта команда скачает последнюю версию Parsedown и добавит ее в ваш проект. Composer автоматически настроит автозагрузку, поэтому вам не нужно будет вручную подключать файлы Parsedown.
2. Вручную:Если вы не используете Composer, вы можете скачать Parsedown вручную с GitHub: https://github.com/erusev/parsedown.
   • Скачайте zip-архив с последним релизом.
   • Распакуйте архив в директорию вашего проекта (например, vendor/erusev/parsedown).
   • Подключите файл Parsedown.php в вашем PHP-коде:
   require_once 'vendor/erusev/parsedown/Parsedown.php';

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

Использовать Parsedown очень просто. Вот базовый пример:

<?php
require_once 'vendor/autoload.php'; // Если используете Composer

$parsedown = new Parsedown();

$markdown = "# Заголовок\n\nЭто абзац с *курсивом* и **жирным** текстом.  \n\n- Список 1\n- Список 2";

$html = $parsedown->text($markdown);

echo $html;
?>

Этот код:

1. Подключает автозагрузчик Composer (или файл Parsedown.php, если установка была вручную).
2. Создает новый экземпляр класса Parsedown.
3. Определяет строку с Markdown-текстом.
4. Использует метод text() для преобразования Markdown в HTML.
5. Выводит полученный HTML-код.

Результат:

<h1>Заголовок</h1>
<p>Это абзац с <em>курсивом</em> и <strong>жирным</strong> текстом.</p>
<ul>
<li>Список 1</li>
<li>Список 2</li>
</ul>

Дополнительные методы и настройки

Parsedown предоставляет несколько полезных методов и настроек:

• line($text): Преобразует одну строку Markdown в HTML. Полезно, когда нужно обрабатывать Markdown построчно.
• setSafeMode($boolean): Включает/выключает безопасный режим. В безопасном режиме Parsedown экранирует HTML-теги, введенные пользователем, чтобы предотвратить XSS-атаки. По умолчанию false (выключен). Рекомендуется включать для обработки пользовательского ввода.
• $parsedown->setSafeMode(true);
• setMarkupEscaped($boolean): Включает/выключает экранирование HTML-разметки внутри Markdown. Если установлено значение true, HTML-разметка внутри Markdown будет отображаться как есть, а не интерпретироваться как HTML. По умолчанию false (выключено).
• $parsedown->setMarkupEscaped(true);
• setBreaksEnabled($boolean): Включает/выключает автоматические переносы строк. Если установлено true, одиночные переносы строк в Markdown будут преобразовываться в теги <br>. По умолчанию false (выключен) в версии 1.x.
• $parsedown->setBreaksEnabled(true);
• setUrlsLinked($boolean): Включает/выключает автоматическое преобразование URL-адресов в ссылки. По умолчанию true (включено).
• $parsedown->setUrlsLinked(false);

Расширение Parsedown (ParsedownExtra)

Для более продвинутых возможностей, таких как таблицы, сноски и определения списков, используйте ParsedownExtra:

composer require erusev/parsedown-extra

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

<?php
require_once 'vendor/autoload.php';

$parsedown = new ParsedownExtra();

$markdown = "
| Заголовок 1 | Заголовок 2 |
| ----------- | ----------- |
| Ячейка      | Ячейка    |

Это сноска[^1].

[^1]: Текст сноски.
";

$html = $parsedown->text($markdown);

echo $html;

?>

Вывод:

<table>
<thead>
<tr>
<th>Заголовок 1</th>
<th>Заголовок 2</th>
</tr>
</thead>
<tbody>
<tr>
<td>Ячейка</td>
<td>Ячейка</td>
</tr>
</tbody>
</table>
<p>Это сноска<sup id="fnref:1"><a href="#fn:1" class="footnote-ref">1</a></sup>.</p>
<div class="footnotes">
<hr>
<ol>
<li id="fn:1">
<p>Текст сноски. <a href="#fnref:1" class="footnote-backref">&#8617;</a></p>
</li>
</ol>
</div>

Заключение

Parsedown – это мощный, быстрый и простой в использовании Markdown парсер для PHP. Он предоставляет все необходимые функции для преобразования Markdown в HTML, а также легко расширяется. Благодаря своей скорости, безопасности и соответствию спецификациям, Parsedown является отличным выбором для любого PHP-проекта, который требует обработки Markdown. Использование Composer делает установку и управление зависимостями чрезвычайно простыми. Если вам нужен Markdown парсер, обязательно попробуйте Parsedown!