Автоматизированный исследовательский артефакт — не вышестоящий проект.

Этот репозиторий — одноразовая лаборатория, созданная автоматизированной средой для магистерской диссертации в Université Laval по воспроизведению опубликованных уязвимостей рабочих процессов GitHub Actions. Это точный снимок phpgt/Dom на коммите b73d7e8b54963796132df99902c3224016511bb9 (2025-03-21), распространённый под собственной лицензией этого проекта, файл которой включён без изменений в этот снимок.

Вышестоящий проект не участвует, никогда не является целью, а изучаемая здесь уязвимость уже публична. Каждый секрет и переменная в этом репозитории — случайно сгенерированное фиктивное значение — никаких реальных учётных данных здесь нет. Ссылки на действия и образы раннеров закреплены на те значения, которым они соответствовали на 2025-03-21; см. pinning.md в выводе среды для каждого изменения, внесённого в снимок.

Вопросы или возражения: [email protected]

---

Современный DOM API.

Построенный на основе нативного DOMDocument в PHP, этот проект предоставляет доступ к современным DOM API, как вы ожидали бы при работе с клиентским кодом в браузере.

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

---

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

Важное примечание: пример, показанный здесь, приведён в иллюстративных целях, но использование DOM для прямой установки данных в значения элементов тесно связывает логику с представлением, что считается плохой практикой. Пожалуйста, обратитесь к библиотеке DomTemplate для более надёжного решения по привязке данных к DOM.

Рассмотрим страницу с формой и элементом ввода для ввода вашего имени. Когда форма отправлена, страница должна поприветствовать вас по имени.

Это простой пример того, как исходные HTML-файлы могут рассматриваться как шаблоны. Это легко можно применить к более продвинутым страницам-шаблонам для предоставления динамического контента без использования нестандартных методов, таких как {{фигурные скобки}} для заполнителей, или подверженного ошибкам конструирования HTML из PHP с помощью echo '<div class='easy-mistake'>' . $content['opa'] . '</div>'.

Исходный HTML (name.html)

<!doctype html>
<h1>
	Hello, <span class="name-output">you</span> !
</h1>

<form>
	<input name="name" placeholder="Your name, please" required />
	<button>Submit</button>
</form>

PHP, используемый для вставки вашего имени (index.php)

<?php
use Gt\Dom\HTMLDocument;
use Gt\Dom\HTMLElement\HTMLSpanElement;
require "vendor/autoload.php";

$html = file_get_contents("name.html");
$document = new HTMLDocument($html);

if(isset($_GET["name"])) {
	$span = $document->querySelector(".name-output");
	$span->innerText = $_GET["name"];
}

echo $document;

Возможности с первого взгляда

• Совместимость с Living Standard DOM от W3C:
  • Тип Element представляет все спецификации HTMLElement, такие как HTMLAnchorElement (<a>), HTMLButtonElement (<button>), HTMLInputElement (<input>), HTMLTableSectionElement (<thead>, <tbody>, <tfoot>) и т. д. Конкретный тип можно определить с помощью Element::getElementType(), который возвращает одно из значений перечисления ElementType.
  • Расширения DOMException для перехвата различных типов исключений, таких как EnumeratedValueException, HierarchyRequestError, IndexSizeException и т. д.
  • Заглушки клиентской функциональности, включая классы для FileList, StyleSheet, VideoTrackList, WindowProxy и т. д.
• Функциональность DOM уровня 4+:
  • Ссылки на элементы с помощью CSS-селекторов через [Element::querySelector()][mdn-qs] и ([Element::querySelectorAll()][mdn-qsa])
  • Добавление/удаление/переключение классов элементов с помощью [ClassList][mdn-classList]
  • Обход узлов, содержащих только элементы, с помощью [Element::previousElementSibling][mdn-pes], [Element::nextElementSibling][mdn-nes], [Element::children][mdn-children], [Element::lastElementChild][mdn-lec] и [firstElementChild][mdn-fec] и т. д.
  • Вставка и удаление дочерних узлов с помощью [ChildNode::remove()][mdn-remove], [ChildNode::before][mdn-before], [ChildNode::after][mdn-after], [ChildNode::replaceWith()][mdn-replaceWith]
• Стандартные свойства HTMLDocument:
  • [anchors][mdn-anchors]
  • [forms][mdn-forms]
  • [image][mdn-images]
  • [links][mdn-links]
  • [scripts][mdn-scripts]
  • [title][mdn-title]

Известные ограничения / соответствие спецификации W3C

Этот репозиторий стремится быть максимально точным по отношению к спецификации DOM на https://dom.spec.whatwg.org/ — начиная с v4.0.0 вся функциональность реализована со следующими незначительными, но неизбежными отклонениями от стандарта:

• Свойство tagName элементов в верхнем регистре.
• Для проверки типа HTMLElement необходимо вызывать Element::getElementType() — подклассы Element для использования с instanceof, например, недоступны.
• Спецификация DOM определяет функциональность, которую можно реализовать только на клиентской стороне. Например, HTMLInputElement::files возвращает FileList, перечисляющий все файлы, выбранные пользователем через интерфейс браузера. Такую функциональность невозможно реализовать на серверной стороне, но она была заглушена для согласованности со спецификацией. Попытка использовать клиентскую функциональность в этой библиотеке вызывает исключение ClientSideOnlyFunctionalityException.

Привязка данных и функции шаблонов страниц

Этот репозиторий предназначен для максимально точного соответствия спецификации DOM. Расширение репозитория доступно на https://php.gt/domtemplate, которое добавляет шаблонизацию страниц и привязку данных через пользовательские элементы и атрибуты шаблонов, вводя серверную функциональность, подобную WebComponents.

Нативный HTMLDocument в PHP 8.4

С момента выпуска PHP 8.4 в PHP нативно появился новый класс HTMLDocument. Благодаря нативным привязкам все операции выполняются гораздо быстрее. Начата работа по адаптации реализации Dom от PHPGT для использования нового нативного кода. К счастью, DOM — это очень хорошо определённый стандарт, поэтому что бы ни произошло, для вашего кода потребуется минимум изменений или они не потребуются вовсе.

Взгляните сами на бенчмарки в ветке php84-benchmark: большинство операций, согласно записям, показывают увеличение скорости на 90% и более при переходе на нативную реализацию!

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