README

highlight.php 是一个用PHP编写的服务器端语法高亮器，目前支持185种语言。它是Ivan Sagalaev编写的 highlight.js 的移植，充分利用了原始JavaScript项目的语言和样式定义。

这是 highlight.php v10 的 README，目前处于开发中。最新的稳定版本是 9.18.x 系列。

目录

• 安装 + 设置
  • Composer 版本约束
• 使用
  • 显式模式
  • 自动语言检测模式
  • 样式表
• 高亮器实用工具
• 版本控制
  • 向后兼容性承诺
• 一些历史
• 许可协议

安装 + 设置

建议通过 Composer 安装项目。

composer require scrivo/highlight.php

如果您不使用 Composer，请确保可以通过包含或自动加载器找到在 Highlight 命名空间中定义的类。此项目包含一个用于此目的的简单自动加载器，名为 Highlight\Autoloader.php。

Composer 版本约束

在您的 composer.json 中引入此项目时，建议您使用 插入版本范围，并仅使用主版本和次版本值；例如，^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>";
}

自动语言检测模式

或者，您可以使用自动检测模式，该模式使用库认为最佳的编程语言来高亮显示您的代码。强烈建议您显式选择语言或限制自动检测的语言数量，以减少不准确的次数。

警告：自动检测以暴力方式发生，并将选择最准确的结果的语言。当您提供更多语言时，这非常低效，并且如果配置了类似语言，则可能不总是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中或使其对您的Web服务器可用。

高亮器实用工具

项目的核心是 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的向后兼容承诺。您可以放心，在 9.x 期间不会有破坏性的更改，任何弃用都会用 @deprecated 标记，并且直到下一个主要版本发布之前都不会被删除。

一些历史

Geert Bergman Sep 30, 2013

JavaScript代码高亮非常方便，在许多情况下正是您想要使用的。特别是在编程博客上，我不会建议您使用其他方式。但有时使用更“静态”的方法会更好，例如，如果您想在电子邮件中发送高亮代码或API文档。为此，我需要一个代码高亮程序，最好是使用PHP编写的。

我没有找到任何令人满意的PHP解决方案，所以我决定从JavaScript移植一个。经过对不同高亮程序在许可、技术、语言支持等方面的比较后，我认为highlight.js是最受欢迎的。

我的决定不是制作一个PHP高亮器，而是要移植highlight.js，这两者不同。目标是使其与highlight.js完全一样，尽可能多地使用原始程序的语言定义和CSS文件。

祝您编码愉快！

许可协议

BSD