[Introdução ao PHP] A Mágica Reutilizável! Como Gerar Resumos com Funções (function)

Você já quis exibir apenas uma pequena parte introdutória de cada artigo na página de índice de um blog? Um "resumo" que diz aos leitores "é sobre isso que o artigo trata" é muito importante para incentivá-los a navegar pelo seu site. No entanto, criar resumos manualmente toda vez que você adiciona um artigo é muito trabalho, não é?

Este artigo apresenta uma ferramenta mágica em PHP chamada função (function) que resolve esse problema. Vamos tentar criar nossa própria ferramenta prática de "geração de resumos" como uma função PHP que pega um texto longo, corta-o para um número específico de caracteres e anexa "...leia mais" no final. Também abordaremos o `htmlspecialchars()`, que é essencial para a segurança, para que você obtenha um código seguro e prático. É amigável para copiar e colar, mesmo para iniciantes!

Para preparar seu ambiente para rodar o PHP (ambiente de desenvolvimento), se você ainda não configurou o XAMPP, por favor, consulte [Introdução ao PHP] Um Guia Completo para Baixar e Instalar o XAMPP!. Após a instalação, basta colocar seu arquivo PHP na pasta especificada (como `htdocs`), e você estará pronto!

1. O que é a Magia Organizadora de Código "Função"?

Primeiro, o que é uma "função"? Simplificando, é como uma "ferramenta personalizada" onde você agrupa um processo específico, dá um nome e pode chamá-lo para usar a qualquer momento.

Por exemplo, se você criar uma função para a série de etapas "receber texto, cortá-lo para 100 caracteres e adicionar '...' no final", então você só precisa chamar essa função sempre que precisar de um resumo. Você não precisa escrever o mesmo código várias vezes, o que torna toda a sua base de código mais limpa e fácil de gerenciar. Esta é a maior vantagem das funções.

A sintaxe básica é a seguinte:

<?php
function nome_da_funcao(argumento1, argumento2, ...) {
  // Escreva o processo que você quer executar aqui

  return valor_de_retorno; // Retorna o resultado do processo
}
?>

É fácil de entender se você pensar nos argumentos como os "ingredientes" que você passa para a função, e o valor de retorno como o "produto final" que a função devolve. Agora, vamos usar esta sintaxe para criar nossa função de geração de resumos.

2. Na prática! Vamos criar uma função para gerar resumos

Esta é a parte principal deste artigo. Criaremos uma função chamada `make_excerpt()` à qual você pode dar um texto longo e um número de caracteres, e ela retornará um resumo bem abreviado. O código abaixo é um exemplo HTML completo que você pode copiar e colar em um arquivo para ver imediatamente como funciona no seu navegador.

<!DOCTYPE html>
<html lang="pt">
<head>
    <meta charset="UTF-8">
    <title>Ferramenta de Geração de Resumos</title>
    <style>
        body { font-family: sans-serif; line-height: 1.6; padding: 20px; }
        .original-text { background: #f4f7f6; border-left: 5px solid #ccc; padding: 10px; margin-bottom: 20px; }
        .excerpt { background: #e8f4f8; border-left: 5px solid #007bff; padding: 10px; }
    </style>
</head>
<body>

    <h1>Teste de Geração de Resumos</h1>

    <?php
    /**
     * Gera um resumo.
     * @param string $text O texto original.
     * @param int $length O limite de caracteres.
     * @return string O resumo gerado.
     */
    function make_excerpt(string $text, int $length): string {
        // Verifica a contagem de caracteres do texto original
        if (mb_strlen($text) > $length) {
            // Corta para a contagem de caracteres especificada e anexa "...leia mais"
            return mb_substr($text, 0, $length) . '...leia mais';
        } else {
            // Se a contagem de caracteres for menor que o limite, retorna como está
            return $text;
        }
    }

    // Um texto original longo
    $long_text = 'Este é um texto muito longo. Este artigo explica em detalhes como usar funções PHP para cortar texto para uma contagem específica de caracteres e gerar um resumo. Esta é uma técnica prática útil para páginas de índice de blogs e muito mais.';

    // Chama a função para gerar um resumo de 50 caracteres
    $excerpt_text = make_excerpt($long_text, 50);
    ?>

    <h2>Texto Original</h2>
    <div class="original-text">
        <?php echo $long_text; ?>
    </div>

    <h2>Resumo Gerado (limite de 50 caracteres)</h2>
    <div class="excerpt">
        <?php echo $excerpt_text; ?>
    </div>

</body>
</html>

Os pontos-chave neste código são `mb_strlen()` e `mb_substr()`. Para lidar corretamente com caracteres multibyte como o japonês, você precisa usar funções que começam com `mb_` em vez de `strlen()` ou `substr()`. Isso evita texto corrompido e garante que você possa cortar o texto na contagem de caracteres pretendida.

3. Importante! Exibição Segura com htmlspecialchars

Ao exibir texto em uma página da web, uma coisa que você nunca deve esquecer é a segurança. Se o texto a ser exibido contiver tags HTML como `<script>`, exibi-lo como está pode causar comportamento indesejado (um ataque de Cross-Site Scripting).

É aqui que entra a função `htmlspecialchars()`. Esta função converte caracteres que têm um significado especial em HTML (por exemplo, `<`, `>`, `&`, `"`) em strings inofensivas (por exemplo, `<`, `>`, `&`, `"`).

Vamos melhorar nossa função de geração de resumos incorporando este processo para torná-la mais segura.

<?php
/**
 * Uma função aprimorada para gerar um resumo seguro.
 */
function make_safe_excerpt(string $text, int $length): string {
    // 1. Primeiro, escape com htmlspecialchars
    $safe_text = htmlspecialchars($text, ENT_QUOTES, 'UTF-8');

    // 2. Realize a verificação da contagem de caracteres e o corte no texto escapado
    if (mb_strlen($safe_text) > $length) {
        return mb_substr($safe_text, 0, $length) . '...leia mais';
    } else {
        return $safe_text;
    }
}

// Texto que pode conter tags HTML
$dangerous_text = '<strong>Texto enfatizado</strong> e código malicioso como <script>alert("danger!");</script>.';

// Use a função aprimorada para gerar um resumo seguro
$safe_excerpt = make_safe_excerpt($dangerous_text, 30);

echo $safe_excerpt;
?>

Ao usar esta função `make_safe_excerpt()`, mesmo que o texto original contenha tags HTML, elas serão exibidas com segurança como meras strings, então você не precisa se preocupar com elas quebrando o layout da página ou executando scripts.

4. Exemplo Aplicado: Usando com um loop foreach

Agora, vamos combinar esta prática função de geração de resumos com o loop `foreach` que aprendemos no artigo anterior. Geraremos dinamicamente uma lista de títulos e resumos a partir de um array de postagens de blog.

<?php
// Função de geração de resumo seguro (presume-se definida no exemplo anterior)
function make_safe_excerpt(string $text, int $length): string {
    $safe_text = htmlspecialchars($text, ENT_QUOTES, 'UTF-8');
    if (mb_strlen($safe_text) > $length) {
        return mb_substr($safe_text, 0, $length) . '...leia mais';
    }
    return $safe_text;
}

// Array de dados de postagens de blog
$blog_posts = [
    [
        "title" => "Domine o Básico do PHP",
        "content" => "Este artigo explica a sintaxe básica e as variáveis do PHP. Ele é projetado para aqueles que são novos na programação, então sinta-se à vontade para continuar a leitura."
    ],
    [
        "title" => "O Segredo das Conexões com Banco de Dados",
        "content" => "Bancos de dados são essenciais para o desenvolvimento web. Ao ler este artigo, você entenderá como se conectar a um banco de dados MySQL a partir do PHP e recuperar/manipular dados em 5 minutos. Muitos códigos de exemplo estão incluídos."
    ]
];
?>

<div class="post-list">
    <?php foreach ($blog_posts as $post): ?>
        <article>
            <h3><?php echo htmlspecialchars($post['title']); ?></h3>
            <p><?php echo make_safe_excerpt($post['content'], 60); ?></p>
        </article>
    <?php endforeach; ?>
</div>

Como você pode ver, uma função, uma vez criada, pode ser chamada e usada repetidamente em várias partes do seu site, como dentro de loops. A alta reutilização do código e a manutenção mais fácil são os maiores atrativos das funções.

5. Resumo e Introdução a Códigos Relacionados

Neste artigo, aprendemos a usar as "funções" do PHP para cortar texto para uma contagem específica de caracteres e gerar um resumo seguro. Os benefícios de usar funções são a organização do código e a melhoria da reutilização. A função `make_safe_excerpt` que criamos hoje certamente será uma ferramenta útil que lhe servirá bem muitas vezes em seus projetos de criação de sites.