highlight_file()

В этой статье мы рассмотрим PHP-функцию highlight_file(). Вы получите общее представление о функции, узнаете, как она работает, и познакомитесь с примерами её применения.

Введение в функцию highlight_file()

Функция highlight_file() — это встроенная PHP-функция, которая выводит исходный код PHP-файла с синтаксической раскраской в виде HTML. Она удобна, когда нужно отобразить содержимое скрипта на веб-странице — например, в учебном пособии, галерее фрагментов кода или простой документации — без написания собственного подсветчика.

Синтаксис

highlight_file(string $filename, bool $return = false): string|bool

• $filename — путь к PHP-файлу, который нужно отобразить.
• $return — если false (по умолчанию), подсвеченный HTML отправляется прямо в буфер вывода, а функция возвращает true. Если true, HTML возвращается в виде строки вместо непосредственного вывода.

Под капотом PHP токенизирует файл и оборачивает каждый токен (ключевые слова, строки, комментарии и т. д.) в элементы <span> со встроенными цветами, взятыми из директив highlight.* в php.ini.

Примечание по безопасности: highlight_file() раскрывает исходный код файла, включая любые учётные данные, API-ключи или пароли к базам данных, прописанные в нём. Никогда не направляйте её на файл, основываясь на непроверенных данных от пользователя, и никогда не открывайте с её помощью файлы, содержащие секреты.

Как использовать функцию highlight_file()

Использовать функцию highlight_file() очень просто. Нужно лишь вызвать функцию и передать имя PHP-файла, который требуется подсветить. Вот пример:

Как использовать функцию highlight_file()?

<?php
$file = 'example.php';
highlight_file($file);
?>

В этом примере $file содержит путь к скрипту, который мы хотим отобразить. Если example.php содержит:

<?php
$name = "World";
echo "Hello, $name!";

вызов highlight_file($file) выводит HTML, похожий на следующий (цвета задаются через встроенные атрибуты style, здесь сокращены для удобства чтения):

<pre><code style="color: #000000"><span style="color: #0000BB">&lt;?php
$name </span><span style="color: #007700">= </span><span style="color: #DD0000">"World"</span><span style="color: #007700">;
echo </span><span style="color: #DD0000">"Hello, $name!"</span><span style="color: #007700">;</span></code></pre>

Функция уже оборачивает всё в блок <pre><code>, поэтому исходные переносы строк и отступы сохраняются в браузере без каких-либо дополнительных разметок с вашей стороны.

Настройка вывода

Функция highlight_file() имеет ограниченные встроенные возможности настройки. Она принимает лишь второй булев параметр $return. Если установить его в true, функция возвращает подсвеченный HTML в виде строки вместо непосредственного вывода в браузер.

Это полезно, когда требуется дополнительная обработка разметки, её кэширование или встраивание в более крупный шаблон вместо немедленного вывода. Вот пример захвата вывода:

Пример захвата вывода

<?php
$file = 'example.php';
$highlighted = highlight_file($file, true);

// $highlighted is already a complete <pre><code>...</code></pre> block,
// so you can store it, insert it into a template, or echo it directly.
echo $highlighted;
?>

Вы можете глобально изменить цвета, задав директивы highlight.comment, highlight.default, highlight.html, highlight.keyword и highlight.string в php.ini (или во время выполнения с помощью ini_set()), однако функция всегда генерирует встроенные стили — возможности вывода CSS-классов не предусмотрено.

Если вам нужна расширенная настройка (собственные CSS-классы, нумерация строк или другие цветовые схемы), highlight_file() — не лучший инструмент:

• Чтобы подсветить код, хранящийся в строковой переменной, а не в файле, используйте highlight_string().
• Чтобы прочитать содержимое файла без подсветки, используйте readfile() или file_get_contents().
• Для полного контроля над выводом создайте собственный подсветчик на основе token_get_all() в PHP или воспользуйтесь сторонней библиотекой, такой как highlight.js или Prism, на фронтенде.

Заключение

Таким образом, функция highlight_file() — это простой инструмент для генерации отформатированного PHP-кода с подсветкой синтаксиса. Понимая её реальные параметры и ограничения, вы сможете эффективно применять её для базового отображения синтаксиса или интегрировать с внешними инструментами для более сложного форматирования.

Практика