highlight_file()

Neste artigo, vamos focar na função PHP highlight_file(). Forneceremos uma visão geral da função, como ela funciona e exemplos do seu uso.

Introdução à função highlight_file()

A função highlight_file() é uma função PHP nativa que imprime um arquivo-fonte PHP com sua sintaxe colorida como HTML. É bastante útil quando você deseja mostrar o conteúdo de um script numa página web — por exemplo, em um tutorial, uma galeria de trechos de código ou documentação simples — sem precisar escrever seu próprio realçador.

Sintaxe

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

• $filename — o caminho para o arquivo PHP que você deseja exibir.
• $return — quando false (o padrão), o HTML realçado é enviado diretamente para o buffer de saída e a função retorna true. Quando true, o HTML é retornado como string em vez de ser impresso.

Internamente, o PHP tokeniza o arquivo e envolve cada token (palavras-chave, strings, comentários, etc.) em elementos <span> com cores inline obtidas das diretivas highlight.* no php.ini.

Nota de segurança: highlight_file() revela o código-fonte bruto de um arquivo, incluindo quaisquer credenciais, chaves de API ou senhas de banco de dados nele escritas. Nunca aponte para um arquivo com base em entradas de usuário não validadas, e nunca o exponha para arquivos que contenham segredos.

Como usar a função highlight_file()

Usar a função highlight_file() é muito simples. Basta chamar a função e passar o nome do arquivo PHP que você deseja realçar. Veja um exemplo:

Como usar a função highlight_file()?

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

Neste exemplo, $file contém o caminho do script que queremos exibir. Se example.php contiver:

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

chamar highlight_file($file) imprime HTML semelhante a este (as cores vêm de atributos style inline, simplificados aqui para legibilidade):

<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>

A função já envolve tudo em um bloco <pre><code>, portanto as quebras de linha e a indentação originais são preservadas no navegador sem nenhuma marcação adicional da sua parte.

Personalizando a saída

A função highlight_file() tem opções limitadas de personalização nativas. Ela aceita apenas um segundo parâmetro booleano $return. Quando definido como true, a função retorna o HTML realçado como string em vez de enviá-lo diretamente ao navegador.

Isso é útil quando você deseja pós-processar a marcação, armazená-la em cache ou incorporá-la em um template maior em vez de imprimi-la imediatamente. Veja um exemplo de como capturar a saída:

Exemplo de captura da saída

<?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;
?>

Você pode alterar as cores globalmente definindo as diretivas highlight.comment, highlight.default, highlight.html, highlight.keyword e highlight.string no php.ini (ou em tempo de execução com ini_set()), mas a função sempre emite estilos inline — não há como fazê-la gerar classes CSS.

Se você precisar de personalização avançada (classes CSS personalizadas, numeração de linhas ou esquemas de cores diferentes), highlight_file() não é a ferramenta certa:

• Para realçar código que está em uma variável string em vez de um arquivo, use highlight_string().
• Para ler o conteúdo de um arquivo sem realce, use readfile() ou file_get_contents().
• Para controle total sobre a saída, construa um realçador personalizado sobre o token_get_all() do PHP, ou use uma biblioteca de terceiros como highlight.js ou Prism no front end.

Conclusão

Em conclusão, a função highlight_file() é uma ferramenta direta para gerar código PHP formatado com realce de sintaxe. Ao compreender seus parâmetros reais e limitações, você pode utilizá-la efetivamente para exibição básica de sintaxe ou integrá-la com ferramentas externas para necessidades de formatação mais avançadas.

Prática