README

此包提供了一个用于服务器端代码高亮的Twig扩展。在底层，使用了scrivo/highlight.php包来完成艰苦的工作。您可以使用highlight.js提供的所有主题。

除了代码高亮外，此Twig扩展还提供了一些额外的（有争议的）功能

• 语言别名
• 额外语言
• 行号
• 强调行
• 类
• 可用语言列表

此包处于测试阶段！您已经可以使用它，但API可能会更改。

用法

将扩展添加到Twig环境中

$twig->addExtension(new Brotkrueml\TwigCodeHighlight\Extension());

在Twig模板中使用它

{{ "<?php echo 'test'; ?>" | codehighlight("php") }}

如果语言不可用，则显示原始代码块。

您还可以注入一个实现\Psr\Log\LoggerInterface的记录器，以在给定语言不可用时显示警告，无论是通过依赖注入还是手动进行

$twig->addExtension(new Brotkrueml\TwigCodeHighlight\Extension($myLogger));

您还可以使用命名参数，上面的示例也可以写成

{{ "<?php echo 'test'; ?>" | codehighlight(language="php") }}

这将渲染如下内容

<pre><code class="hljs php"><span class="hljs-meta">&lt;?php</span> <span class="hljs-keyword">echo</span> <span class="hljs-string">"test"</span>; <span class="hljs-meta">?&gt;</span></code></pre>

语言别名

当您已经有了一个语言命名不同于highlight.php提供的方式的现有应用时，您可以在实例化扩展类时分配一个语言别名数组

$twig->addExtension(new Brotkrueml\TwigCodeHighlight\Extension(languageAliases: ['text' => 'plaintext', 'sh' => 'shell']));

在这个例子中，我们引入了text作为plaintext的别名，以及sh作为shell的别名。

额外语言

有时您需要添加不是由scrivo/highlight.php包提供的语言。您可以添加一个或多个自定义语言

$twig->addExtension(new Brotkrueml\TwigCodeHighlight\Extension(
    additionalLanguages: [
        ['custom_language', '/path/to/the/custom_language.json'],
        ['another_language', '/path/to/the/another_language.json', true],
    ]
));

该数组包含以下值

• 语言ID（在这里：custom_language和another_language）-必需
• 语言的完整路径（在这里：/path/to/the/custom_language.json和/path/to/the/another_language.json）-必需
• 此语言是否应该覆盖提供的语言（默认：false，如果应该覆盖则设置为true）-可选

行号

默认情况下，不显示行号。您可以设置第二个参数来切换它们

在Twig模板中使用它

{{ "<?php echo 'test'; ?>" | codehighlight(language="php", showLineNumbers=true) }}

行号从1开始，但也可以使用另一个参数提供自定义起始数字

{{ "<?php echo 'test'; ?>" | codehighlight(language="php", showLineNumbers=true, startWithLineNumber=11) }}

这将在每一行添加一个<span data-line-number="x">...</span>，其中x是递增的行号。

然后您可以使用CSS规则来显示行号，例如

code [data-line-number]::before {
    content: attr(data-line-number);
    display: inline-block;
    margin-right: 1em;
    text-align: right;
    width: 2ch;
}

强调行

您可以选择强调行，以突出显示代码片段中的一行或多行。

在Twig模板中使用它

{{ code | codehighlight(language="php", emphasizeLines="1-3,5") }}

此示例强调第1、2、3和5行。

这将在应该强调的每一行添加一个<span data-emphasize-line>...</span>。

然后您可以使用自定义CSS规则来突出显示该行，例如

code [data-emphasize-line] {
    background: lightcyan;
}

类

有两种方式可以设置或更多类到<pre>标签

1. 要在应用程序中设置类，请在实例化Twig扩展时使用classes构造函数参数

   $twig->addExtension(new Brotkrueml\TwigCodeHighlight\Extension(classes: 'some-default-class'));

   这会产生以下HTML代码

   <pre class="some-default-class">...</pre>

2. 您可以为特殊代码块添加一个或多个附加类到<pre>标签

   {{ some text | codehighlight(language="plaintext", classes="some-special-class another-special-class") }}

   这会产生以下HTML代码

   <pre class="some-special-class another-special-class"><code class="hljs plaintext">some text</code></pre>

同时使用这两种变体会产生以下HTML代码

<pre class="some-default-class some-special-class another-special-class"><code class="hljs plaintext">some text</code></pre>

可用语言列表

有时候提供可用语言的列表可能很有用。可以使用函数 codehighlight_languages() 来输出这样的列表

<ul>
{% for language in codehighlight_languages() %}
    <li>{{ language }}</li>
{% endfor %}
</ul>