Projeto: Criando sua própria biblioteca de funções utilitárias

1. Introdução 🚀

Olá, futuro(a) desenvolvedor(a) PHP! Nesta aula prática, vamos mergulhar no fascinante mundo da organização de código, criando nossa própria biblioteca de funções utilitárias. Você já se viu escrevendo o mesmo trecho de código repetidamente em diferentes partes do seu projeto? Ou talvez em projetos distintos? Se sim, você está no lugar certo!

Uma biblioteca de funções utilitárias é como sua caixa de ferramentas pessoal: um conjunto de funções genéricas e reutilizáveis que resolvem problemas comuns e repetitivos. Elas nos ajudam a:

Reutilizar Código: Evitar a duplicação de código (princípio DRY - Don't Repeat Yourself).
Organizar o Projeto: Manter funções relacionadas em um só lugar, facilitando a localização e manutenção.
Melhorar a Leitura: Funções bem nomeadas e com propósito único tornam seu código mais compreensível.
Aumentar a Produtividade: Você não precisa reinventar a roda a cada nova funcionalidade.

Neste projeto, você aprenderá a estruturar e implementar algumas funções utilitárias básicas, aplicando as melhores práticas de codificação que vimos até agora no curso de Fundamentos do PHP.

2. Entendendo as Funções Utilitárias ✨

Funções utilitárias são blocos de código independentes que executam uma tarefa específica e bem definida. Elas são projetadas para serem genéricas, ou seja, não estão ligadas a uma lógica de negócio específica do seu aplicativo, mas sim a operações comuns que podem ser úteis em diversos contextos.

Características Essenciais:

Puras (idealmente): Uma função pura, dada a mesma entrada, sempre produzirá a mesma saída e não causará efeitos colaterais (como modificar variáveis globais ou estados externos). Isso as torna previsíveis e fáceis de testar.
Foco Único: Cada função deve fazer "uma coisa e fazê-la bem". Isso segue o Princípio da Responsabilidade Única.
Reutilizáveis: Devem ser projetadas para serem facilmente integradas e utilizadas em diferentes partes do seu código ou em outros projetos.

Categorias Comuns de Funções Utilitárias:

Manipulação de Strings: Capitalizar, formatar, limpar, truncar textos.
Manipulação de Arrays: Buscar, filtrar, ordenar, transformar elementos em arrays.
Validação de Dados: Verificar formatos de e-mail, CPF, datas, números.
Formatação de Dados: Converter formatos de data, moeda, números.
Operações Matemáticas: Cálculos específicos não cobertos pelas funções nativas.

3. Estruturando sua Biblioteca 📁

Para o nosso nível de "Fundamentos do PHP", vamos começar com uma abordagem simples e eficaz: um único arquivo PHP que conterá todas as nossas funções utilitárias.

Nomenclatura e Boas Práticas:

Nome do Arquivo: Um nome descritivo como utils.php, helpers.php, ou funcoes_uteis.php.
Prefixo de Função: Para evitar conflitos de nomes com funções nativas do PHP ou de outras bibliotecas, é uma boa prática prefixar suas funções utilitárias. Por exemplo, util_formatarNome, app_validarEmail. Isso também as torna mais fáceis de identificar como parte da sua biblioteca.

DocBlocks: Documente cada função usando o formato PHPDoc (DocBlocks). Isso é crucial para que você e outros desenvolvedores entendam rapidamente o que a função faz, quais parâmetros espera e o que retorna.

<?php
 
/**
 * Converte uma string para o formato de Título (primeira letra de cada palavra em maiúscula).
 *
 * @param string $texto A string a ser formatada.
 * @return string A string formatada.
 */
function util_formatarTitulo(string $texto): string
{
    // ... implementação
}

Tipagem (Type Hints): Use type hints para os parâmetros e para o retorno das funções. Isso melhora a clareza do código e permite que o PHP detecte erros de tipo em tempo de execução. Disponível a partir do PHP 7.0.
```
function util_somar(int $a, int $b): int
{
    return $a + $b;
}
```
Pureza e Efeitos Colaterais: Tente manter suas funções o mais puras possível. Evite usar ou modificar variáveis globais dentro das funções utilitárias. Se uma função precisar modificar um parâmetro, use passagem por referência (&), mas documente isso claramente.

4. Desenvolvendo Funções Utilitárias: Exemplos Práticos 🛠️

Vamos criar algumas funções úteis para nossa biblioteca. Usaremos funções nativas do PHP e as encapsularemos em nossas próprias funções com um propósito mais específico.

Exemplo 1: Manipulação de Strings - Formatando Nomes Próprios

Imagine que você recebe nomes em formatos variados (todo maiúsculo, todo minúsculo) e precisa padronizá-los.

<?php
// utils.php
 
/**
 * Converte uma string para o formato de Nome Próprio (primeira letra de cada palavra em maiúscula, o restante em minúscula).
 * Ex: "JOAO DA SILVA" -> "Joao Da Silva"
 *
 * @param string $nome A string a ser formatada.
 * @return string A string formatada como nome próprio.
 * @link https://www.php.net/manual/pt_BR/function.ucwords.php
 * @link https://www.php.net/manual/pt_BR/function.strtolower.php
 */
function util_formatarNomeProprio(string $nome): string
{
    // Converte toda a string para minúsculas primeiro para garantir consistência
    $nomeMinusculo = strtolower($nome);
    // Capitaliza a primeira letra de cada palavra
    return ucwords($nomeMinusculo);
}

Explicação:

strtolower(): Converte todos os caracteres de uma string para minúsculas. Isso garante que "JOAO" e "joao" se tornem "joao" antes de capitalizar.
ucwords(): Converte para maiúscula o primeiro caractere de cada palavra em uma string.

Exemplo 2: Manipulação de Arrays - Buscando um Item por Propriedade

É comum ter um array de arrays (ou objetos) e precisar encontrar um item específico com base no valor de uma de suas propriedades.

<?php
// utils.php (adicione a função abaixo)
 
/**
 * Busca um item em um array de arrays ou objetos pela correspondência de uma propriedade.
 *
 * @param array $array O array onde a busca será realizada.
 * @param string $propriedade O nome da propriedade a ser verificada.
 * @param mixed $valor O valor a ser buscado na propriedade.
 * @return array|null O primeiro item encontrado que corresponde, ou null se nenhum for encontrado.
 * @link https://www.php.net/manual/pt_BR/function.array-filter.php
 */
function util_buscarPorPropriedade(array $array, string $propriedade, mixed $valor): ?array
{
    foreach ($array as $item) {
        // Verifica se o item é um array e se a propriedade existe
        if (is_array($item) && isset($item[$propriedade]) && $item[$propriedade] === $valor) {
            return $item;
        }
        // Verifica se o item é um objeto e se a propriedade existe (PHP 8.0+)
        if (is_object($item) && property_exists($item, $propriedade) && $item->$propriedade === $valor) {
            return (array) $item; // Retorna como array para consistência, ou você pode retornar o objeto diretamente
        }
    }
    return null; // Retorna null se nenhum item for encontrado
}

Explicação:

Usamos um foreach para iterar sobre cada item do array.
Verificamos se o item é um array ou um objeto e se a propriedade existe antes de comparar seus valores.
Retornamos o primeiro item que satisfaz a condição ou null se nada for encontrado.

Exemplo 3: Validação Simples - Verificando um Endereço de E-mail

A validação de e-mails é uma tarefa rotineira. O PHP oferece uma função nativa excelente para isso.

<?php
// utils.php (adicione a função abaixo)
 
/**
 * Verifica se uma string é um endereço de e-mail válido.
 *
 * @param string $email O endereço de e-mail a ser validado.
 * @return bool True se o e-mail for válido, false caso contrário.
 * @link https://www.php.net/manual/pt_BR/function.filter-var.php
 * @link https://www.php.net/manual/pt_BR/filter.filters.validate.php
 */
function util_ehEmailValido(string $email): bool
{
    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
}

Explicação:

filter_var(): É uma função poderosa para filtrar e validar dados.
FILTER_VALIDATE_EMAIL: Uma constante que indica que queremos validar um endereço de e-mail. Retorna o e-mail filtrado se for válido, ou false se não for.

Exemplo 4: Formatação de Datas - Convertendo para o Padrão Brasileiro

Trabalhar com datas é sempre um desafio. Converter formatos é uma tarefa comum.

<?php
// utils.php (adicione a função abaixo)
 
/**
 * Converte uma data no formato "YYYY-MM-DD" para o formato brasileiro "DD/MM/YYYY".
 *
 * @param string $data A data no formato "YYYY-MM-DD".
 * @return string|null A data formatada como "DD/MM/YYYY", ou null se a data for inválida.
 * @link https://www.php.net/manual/pt_BR/class.datetime.php
 * @link https://www.php.net/manual/pt_BR/datetime.format.php
 */
function util_formatarDataParaBR(string $data): ?string
{
    try {
        $objetoData = new DateTime($data);
        return $objetoData->format('d/m/Y');
    } catch (Exception $e) {
        // Em caso de data inválida, retorna null ou lança uma exceção, dependendo da sua necessidade
        return null;
    }
}

Explicação:

DateTime: A classe DateTime do PHP é a maneira recomendada de trabalhar com datas e horas.
new DateTime($data): Tenta criar um objeto DateTime a partir da string fornecida.
format('d/m/Y'): Formata o objeto DateTime para a string desejada (d para dia com zero à esquerda, m para mês com zero à esquerda, Y para ano com quatro dígitos).
Um bloco try-catch é usado para lidar com possíveis datas inválidas que podem gerar uma Exception.

5. O Projeto: Criando sua Biblioteca! 🚀

Agora é a sua vez de colocar a mão na massa e construir sua própria biblioteca de funções!

Objetivo:

Criar um arquivo utils.php que contenha as funções que desenvolvemos acima, além de algumas funções extras como desafio. Em seguida, crie um arquivo index.php para testar e demonstrar o uso de todas as suas funções.

Instruções:

Crie a Estrutura:
- Crie uma pasta para o seu projeto (ex: meu_projeto_php).
- Dentro dela, crie um arquivo chamado utils.php.
- Crie outro arquivo chamado index.php.
Implemente as Funções:
- No arquivo utils.php, adicione o cabeçalho <?php.
- Copie e cole as quatro funções de exemplo (util_formatarNomeProprio, util_buscarPorPropriedade, util_ehEmailValido, util_formatarDataParaBR) no seu utils.php.
- Certifique-se de incluir os DocBlocks e type hints para cada função.
Crie o Arquivo de Teste (index.php):
- No index.php, você precisará incluir seu arquivo utils.php para que as funções estejam disponíveis. Use require_once.
- Chame cada uma das funções com diferentes entradas para verificar se elas funcionam como esperado.
- Use echo ou var_dump para exibir os resultados.

Task List:

Siga esta lista de tarefas para completar seu projeto:

Desafios Extras (Opcional, mas Altamente Recomendado! 💪):

Desafio Extra 1: util_gerarSlug(string $texto)
- Crie uma função que converte um texto em um "slug" amigável para URLs (ex: "Meu Título Bonito" -> "meu-titulo-bonito").
- Considere: converter para minúsculas, substituir espaços por hifens, remover caracteres especiais.
- Dica: Use mb_strtolower(), str_replace(), trim(), preg_replace().
Desafio Extra 2: util_limitarTexto(string $texto, int $limite, string $sufixo = '...')
- Crie uma função que trunca um texto após um certo número de caracteres, adicionando um sufixo (padrão é "...").
- Ex: util_limitarTexto("Este é um texto longo", 10) -> "Este é um..."
- Certifique-se de que a contagem de caracteres seja correta, mesmo com caracteres multibyte (acentos, etc.).
- Dica: Use mb_strlen(), mb_substr().
No index.php, adicione chamadas de teste para suas funções de desafio extra.

Exemplo de `index.php`:

<?php
 
require_once 'utils.php'; // Inclui sua biblioteca de funções
 
echo "<h1>Testando Minha Biblioteca de Funções Utilitárias</h1>";
 
// --- Teste util_formatarNomeProprio ---
echo "<h2>1. Formatando Nomes Próprios</h2>";
$nome1 = "joao da silva";
$nome2 = "MARIA ALVES PEREIRA";
echo "Nome original: '{$nome1}' -> Formatado: '" . util_formatarNomeProprio($nome1) . "'<br>"; // Esperado: Joao Da Silva
echo "Nome original: '{$nome2}' -> Formatado: '" . util_formatarNomeProprio($nome2) . "'<br>"; // Esperado: Maria Alves Pereira
echo "<hr>";
 
// --- Teste util_buscarPorPropriedade ---
echo "<h2>2. Buscando por Propriedade em Array</h2>";
$usuarios = [
    ['id' => 1, 'nome' => 'Alice', 'email' => 'alice@example.com'],
    ['id' => 2, 'nome' => 'Bob', 'email' => 'bob@example.com'],
    ['id' => 3, 'nome' => 'Charlie', 'email' => 'charlie@example.com'],
];
$usuarioEncontrado = util_buscarPorPropriedade($usuarios, 'id', 2);
echo "Buscando usuário com ID 2: ";
var_dump($usuarioEncontrado); // Esperado: array com Bob
$usuarioNaoEncontrado = util_buscarPorPropriedade($usuarios, 'nome', 'David');
echo "Buscando usuário com nome David: ";
var_dump($usuarioNaoEncontrado); // Esperado: null
echo "<hr>";
 
// --- Teste util_ehEmailValido ---
echo "<h2>3. Validando Endereços de E-mail</h2>";
$emailValido = "teste@dominio.com";
$emailInvalido = "email-invalido";
echo "Email '{$emailValido}' é válido? " . (util_ehEmailValido($emailValido) ? 'Sim' : 'Não') . "<br>"; // Esperado: Sim
echo "Email '{$emailInvalido}' é válido? " . (util_ehEmailValido($emailInvalido) ? 'Sim' : 'Não') . "<br>"; // Esperado: Não
echo "<hr>";
 
// --- Teste util_formatarDataParaBR ---
echo "<h2>4. Formatando Datas para o Padrão Brasileiro</h2>";
$dataISO = "2023-10-26";
$dataInvalida = "30-02-2023"; // Fevereiro não tem 30 dias
echo "Data '{$dataISO}' formatada: " . util_formatarDataParaBR($dataISO) . "<br>"; // Esperado: 26/10/2023
echo "Data '{$dataInvalida}' formatada: " . (util_formatarDataParaBR($dataInvalida) ?? 'Data Inválida') . "<br>"; // Esperado: Data Inválida
echo "<hr>";
 
// --- Testes dos Desafios Extras (se implementados) ---
// echo "<h2>5. Gerando Slugs</h2>";
// $titulo = "Meu Artigo Incrível de PHP!";
// echo "Título: '{$titulo}' -> Slug: '" . util_gerarSlug($titulo) . "'<br>";
// echo "<hr>";
 
// echo "<h2>6. Limitando Texto</h2>";
// $textoLongo = "Este é um exemplo de texto muito longo que precisa ser truncado para caber em um espaço limitado.";
// echo "Texto original: '{$textoLongo}'<br>";
// echo "Texto limitado a 30 caracteres: '" . util_limitarTexto($textoLongo, 30) . "'<br>";
// echo "Texto limitado a 15 caracteres com sufixo '... (leia mais)': '" . util_limitarTexto($textoLongo, 15, '... (leia mais)') . "'<br>";
// echo "<hr>";

Para executar seu projeto, salve os arquivos, navegue até a pasta meu_projeto_php no seu terminal e execute:

php -S localhost:8000

Em seguida, abra seu navegador e acesse http://localhost:8000/index.php.

6. Resumo e Próximos Passos 🌟

Parabéns! Você acaba de construir sua primeira biblioteca de funções utilitárias em PHP. Este projeto é um passo fundamental para entender como manter seu código organizado, reutilizável e fácil de manter.

O que aprendemos:

A importância de funções utilitárias para a organização e reusabilidade do código.
Melhores práticas como prefixos de função, DocBlocks e type hints.
Como encapsular funções nativas do PHP para criar ferramentas mais específicas para suas necessidades.
A estruturação básica de um projeto PHP com arquivos de funções e um arquivo de teste.

Este é apenas o começo. Em projetos maiores, você aprenderá sobre:

Autoloading: Como carregar automaticamente suas funções e classes sem precisar de require_once em cada arquivo.
Namespaces: Como organizar seu código em espaços de nomes para evitar conflitos e melhorar a modularidade.
Composer: O gerenciador de dependências do PHP, que facilita o uso de bibliotecas de terceiros e o autoloading.
PSRs (PHP Standard Recommendations): Conjunto de recomendações que visam padronizar o código PHP para garantir interoperabilidade.

Continue praticando e expandindo sua biblioteca de funções. Quanto mais você automatizar tarefas comuns, mais eficiente você se tornará como desenvolvedor! Mantenha a curiosidade e o desejo de aprender! ✨

Fundamentos do PHP

Projeto: Criando sua própria biblioteca de funções utilitárias

Projeto: Criando sua própria biblioteca de funções utilitárias

1. Introdução 🚀

2. Entendendo as Funções Utilitárias ✨

Características Essenciais:

Categorias Comuns de Funções Utilitárias:

3. Estruturando sua Biblioteca 📁

Nomenclatura e Boas Práticas:

4. Desenvolvendo Funções Utilitárias: Exemplos Práticos 🛠️

Exemplo 1: Manipulação de Strings - Formatando Nomes Próprios

Exemplo 2: Manipulação de Arrays - Buscando um Item por Propriedade

Exemplo 3: Validação Simples - Verificando um Endereço de E-mail

Exemplo 4: Formatação de Datas - Convertendo para o Padrão Brasileiro

5. O Projeto: Criando sua Biblioteca! 🚀

Objetivo:

Instruções:

Task List:

Desafios Extras (Opcional, mas Altamente Recomendado! 💪):

Exemplo de index.php:

6. Resumo e Próximos Passos 🌟

Exemplo de `index.php`: