README

HtmlDomParser — это PHP-библиотека для продвинутого парсинга HTML, которая преобразует исходный код в удобное объектное дерево с богатой семантической информацией. Это не просто очередной парсер, а полноценный фреймворк для построения семантически-обогащённого DOM-дерева.

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

• 🧠 Контекстная обработка узлов – каждый узел обрабатывается с учётом его роли в документе (блочный, строчный, фразовый и т.д.) с использованием временных объектов контекста.
• 🔗 Схлопывание строчного контента – объединение последовательности строчных элементов (текст, выделения, ссылки) в один элемент с единым текстом и коллекцией фрагментов форматирования.
• 🧩 Расширяемость через события и модули – подписывайтесь на ключевые этапы парсинга (PRE_NODE, POST_NODE, PRE_INLINE_COLLAPSE, POST_INLINE_COLLAPSE) и модифицируйте результат.
• ⚠️ Продвинутая обработка ошибок – классификация ошибок по уровням (notice, warning, error), узлы-ошибки в дереве, настройка поведения (исключения / сбор).
• 📊 Чистая объектная модель – удобные интерфейсы для навигации, фильтрации и трансформации дерева (ElementInterface, RichTextFragmentInterface, ElementListInterface и др.).

📦 Установка

composer require f4n70m/html-dom-parser

🚀 Быстрый старт

require_once 'vendor/autoload.php';

use HtmlDomParser\Parser;

$html = '<div>Привет, <a href="https://example.com">мир</a>!</div>';
$parser = new Parser($html);
$document = $parser->parse();

$element = $document->getChildren()->get(0);
echo $element->getLabel(); // "Привет, мир!"

// Информация о форматировании сохранена во фрагментах
foreach ($element->getFragments() as $fragment) {
    echo $fragment->getType() . ': ' . $fragment->getStart() . '-' . $fragment->getEnd();
}
// a: 7-10

📚 Документация

1. Общая информация

• Введение – обзор концепций и возможностей библиотеки.
• Установка и начало работы – системные требования, установка через Composer, проверка.
• Быстрый старт – первые примеры парсинга и работы с данными.

2. Ядро системы

• Модель данных элемента (Data, Label, Fragments) – подробно о трёх ключевых свойствах элементов.
• Система контекстов – временные объекты контекста, жизненный цикл узла, типы контекста.
• Утилиты – ContextDataResolver (извлечение основного содержимого) и InlineCollapser (схлопывание строчных элементов).
• Обработка ошибок – уровни ошибок, узлы-ошибки, настройка поведения.

3. События и модули

• Событийная модель – подписка на события, жизненный цикл событий, примеры с использованием EventConstant.
• Система модулей – создание модулей, обнаружение через Composer, зависимости, конфигурация.

4. Информация

• FAQ и решение проблем – ответы на частые вопросы и типичные сложности.
• Справочник API – полный перечень всех интерфейсов с методами (единый источник).

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

Больше примеров можно найти в документации, особенно в разделах «Быстрый старт», «Модель данных» и «Утилиты». Вот ещё один фрагмент, демонстрирующий фильтрацию элементов:

$links = $div->getChildren()->filter(fn($el) => $el->getName() === 'a');
foreach ($links as $link) {
    echo $link->getData() . ': ' . $link->getLabel() . "\n";
}

Работа с фрагментами форматирования

$html = '<p>Это <b>жирный</b> и <i>курсивный</i> текст</p>';
$parser = new Parser($html);
$document = $parser->parse();

$p = $document->getChildren()->get(0);
echo $p->getLabel(); // "Это жирный и курсивный текст"

foreach ($p->getFragments() as $fragment) {
    echo $fragment->getType() . ': ' . $fragment->getStart() . '-' . $fragment->getEnd();
}
// b: 4-10
// i: 13-22

🛠 Требования

• PHP 7.4+
• Расширение ext-dom
• Composer

📄 Лицензия

Этот проект распространяется под лицензией MIT. См. файл LICENSE.

🤝 Сообщество

• Сообщить об ошибке или предложить улучшение: GitHub Issues
• Пакет на Packagist: f4n70m/html-dom-parser