highlight.php

highlight.php - это серверный синтаксический текстовый редактор, написанный на PHP, который в настоящее время поддерживает 185 языков. Это порт highlight.js Ивана Сагалаева, который полностью использует определения языка и стиля оригинального проекта JavaScript.

Это README для highlight.php v10, который в настоящее время находится в разработке. Последний стабильный релиз - 9.18.x series.

Установка + настройка

Рекомендуемый подход - установить проект через Composer.

composer require scrivo/highlight.php

Если вы не используете Composer, убедитесь, что классы, определенные в пространстве имен Highlight, могут быть найдены либо путем включения, либо с помощью автозагрузки. Тривиальный автозагрузчик для этой цели включен в этот проект как Highlight\Autoloader.php

Ограничения версии Composer

При использовании этого проекта в composer.json рекомендуется использовать caret version range и использовать только мажорные и минорные значения; т.е. ^9.14.

Мы заметили, что многие учебники и проекты привязывают себя к очень специфическим версиям этого проекта; например, "scrivo/highlight.php": "v9.12.0.1". Пожалуйста, не делайте этого или поощряйте это. Мы обещаем надежную политику обратной совместимости, поэтому нет причин привязывать себя к такой конкретной версии. Делая это, вы лишаете себя и своих пользователей возможности получать обновления языковых определений и исправления ошибок.

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

Класс \Highlight\Highlighter содержит функциональность подсветки синтаксиса. Вы можете выбрать один из двух режимов подсветки:

1. явный режим
2. режим автоматического определения языка

Явный режим

В явном режиме вы должны определить, какой язык вы будете выделять.

// Instantiate the Highlighter.
$hl = new \Highlight\Highlighter();
$code = file_get_contents('some_ruby_script.rb');

try {
    // Highlight some code.
    $highlighted = $hl->highlight('ruby', $code);

    echo "<pre><code class=\"hljs {$highlighted->language}\">";
    echo $highlighted->value;
    echo "</code></pre>";
}
catch (DomainException $e) {
    // This is thrown if the specified language does not exist

    echo "<pre><code>";
    echo htmlentities($code);
    echo "</code></pre>";
}

Режим автоматического определения языка

В качестве альтернативы вы можете использовать режим автоматического определения языка, который выделяет ваш код тем языком, который библиотека считает наилучшим. Настоятельно рекомендуется явно выбрать язык или ограничить количество языков для автоматического определения, чтобы уменьшить количество неточностей.

Warning: Автоматическое определение происходит методом перебора, и будет выбран язык с наиболее точным результатом. Это крайне неэффективно, поскольку вы добавляете все больше языков, и не всегда может быть на 100% точным, если настроены похожие языки.

$hl = new \Highlight\Highlighter();
$hl->setAutodetectLanguages(array('ruby', 'python', 'perl'));

$highlighted = $hl->highlightAuto(file_get_contents('some_ruby_script.rb'));

echo "<pre><code class=\"hljs {$highlighted->language}\">";
echo $highlighted->value;
echo "</code></pre>";

Языки по умолчанию

Если в подсветке не заданы языки автоопределения, то будет использоваться каждый язык, что приведет к значительным проблемам с производительностью.

Таблицы стилей

Те же таблицы стилей, которые доступны в проекте highlight.js, доступны в каталоге styles этого проекта и могут быть включены в ваш собственный CSS или доступны вашему веб-серверу.

Утилиты хайлайтера

Ядро проекта представляет собой верный порт highlight.js и доступно в основном пространстве имен Highlight. Ряд удобных функций предоставляется в пространстве имен HighlightUtilities для введения дополнительной функциональности без необходимости использования других зависимостей.

Доступные функции:

• getAvailableStyleSheets(bool $filePaths = false): string[]
• getStyleSheet(string $name): false|string
• getStyleSheetFolder(): string
• getStyleSheetPath(string $name): string
• getLanguagesFolder(): string
• getLanguageDefinitionPath(string $name): string
• getThemeBackgroundColor(string $name): float[]
• splitCodeIntoArray(string $html): false|string[]

Версионирование

Этот проект будет следовать тем же номерам версий, что и проект highlight.js в отношении языков, то есть определение языка, доступное в highlight.js 9.12.0, будет доступно и в highlight.php 9.12.0. Однако в этом проекте или в переведенных файлах определений могут возникнуть ошибки, поэтому к номеру версии будет добавлено еще одно число. Например, версия 9.12.0.1 будет содержать все те же языки, что и highlight.js 9.12.0, но также будет содержать исправления исключительно для этого проекта. Это сделано для того, чтобы в случае выпуска highlight.js версии 9.12.1 этот проект мог без конфликтов переходить на новую версию.

Обещание обратной совместимости

Несмотря на то, что семантическая версионность, используемая в этом проекте, является зеркальным отражением версионности highlight.js, этот проект будет придерживаться Symfony's Backward Compatibility Promise. Вы можете быть уверены, что в течение 9.x не будет никаких ломающих изменений, а любые изъятия будут помечены @deprecated и не будут удалены до следующего основного релиза.

Немного истории

Геерт Бергман Sep 30, 2013

Подсветка кода JavaScript - это очень удобно и во многих случаях именно то, что вы хотите использовать. Особенно для блогов о программировании я бы не советовал вам использовать что-то другое. Но бывают случаи, когда лучше использовать более "статичный" подход, например, если вы хотите отправить выделенный код по электронной почте или для документов API. Для этого мне нужна программа подсветки кода, желательно написанная на PHP.

Я не смог найти удовлетворительного PHP-решения, поэтому решил перенести его из JavaScript. После некоторого сравнения различных программ подсветки кода на основе лицензии, технологии, языковой поддержки highlight.js оказался, на мой взгляд, наиболее удачным.

Я решил не делать PHP Highlighter, а сделать порт highlight.js, это разные вещи. Целью было заставить его работать точно так же, как highlight.js, чтобы максимально использовать определения языка и CSS файлы оригинальной программы.

Счастливого кодинга!

Лицензия

BSD