README

Biblioteca de utilitários PHP para documentos brasileiros, datas, textos, HTTP e operações simples com PDO.

Requisitos

PHP 8.2 ou superior;
extensões curl, iconv, json, mbstring e pdo;
Composer 2.

Instalação

composer require leomottarocha/cotidiano

Durante o desenvolvimento local:

composer install

Inicialização

<?php

require __DIR__ . '/vendor/autoload.php';

use leomottarocha\cotidiano;

$cotidiano = new cotidiano();

A entrada pública recomendada é exatamente:

use leomottarocha\cotidiano;

$cotidiano = new cotidiano();

Nomes de classes PHP não diferenciam maiúsculas de minúsculas. Portanto, Leomottarocha\Cotidiano também funciona, mas os exemplos do projeto adotam a forma solicitada acima. A fachada é carregada antecipadamente pelo Composer para preservar essa forma também em sistemas de arquivos que diferenciam maiúsculas e minúsculas. O namespace anterior Leomottarocha\Cotidiano\Models\Cotidiano permanece disponível para compatibilidade.

API

CPF

$cotidiano->limparCpf('123.456.789-09');   // "12345678909"
$cotidiano->mascararCpf('12345678909');    // "123.456.789-09"
$cotidiano->validarCpf('123.456.789-09');  // true

CPFs com tamanho incorreto, dígitos inválidos ou todos os dígitos repetidos são rejeitados.

CNPJ numérico e alfanumérico

$cotidiano->limparCnpj('11.222.333/0001-81');   // "11222333000181"
$cotidiano->mascararCnpj('11222333000181');     // "11.222.333/0001-81"
$cotidiano->validarCnpj('11.222.333/0001-81');  // true
$cotidiano->cnpjNumerico('11222333000181');     // true
$cotidiano->cnpjAlfanumerico('12ABC34501DE35'); // true

Os métodos cnpjNumerico() e cnpjAlfanumerico() estão disponíveis tanto na classe especialista Cnpj quanto na fachada Cotidiano.

Datas e tempo

$cotidiano->contarTempo('2025-01-01', '2025-01-10', 'dias', true);
// "9 dias"

$cotidiano->contarTempo(
    '2025-01-01 08:00',
    '2025-01-01 10:35',
    'horas_minutos'
);
// "2:35"

$cotidiano->retornarDiaDaSemana('2025-10-27'); // "Segunda-feira"
$cotidiano->ajustarData('2025-10-22', 3);      // "2025-10-25"
$cotidiano->ajustarData('2025-10-22', 1, 'Months');
$cotidiano->retornarDiaUtil('2025-10-24');     // "2025-10-27"
$cotidiano->formatarData('2025-10-22');        // "22/10/2025"

Unidades aceitas por contarTempo():

segundos;
minutos;
horas;
horas_minutos;
dias;
semanas;
meses;
anos.

O timezone padrão é America/Sao_Paulo. Entradas inválidas de contarTempo() mantêm o contrato histórico e retornam uma string iniciada por Erro:.

retornarDiaUtil() considera sábado e domingo, mas não consulta feriados.

Textos e senhas

$cotidiano->somenteNumeros('(21) 99999-0000'); // "21999990000"
$cotidiano->letrasMinusculas(['PHP', 'php']);  // ["php"]
$cotidiano->removerAcentos('João, ação');      // "Joao, acao"
$cotidiano->gerarSenhaRandomica(20);           // string com 20 caracteres

As senhas usam random_int(). Um tamanho menor que 1 lança InvalidArgumentException.

Consulta de CEP

$endereco = $cotidiano->consultarCEP('01001-000');

O retorno é um array associativo ou null. A chamada usa ViaCEP, timeout curto, HTTPS e validação de certificado TLS.

Validação de URL

// Valida apenas formato e protocolo, sem acesso à rede:
$resultado = $cotidiano->urlValida('https://example.com', false);

// Valida e realiza uma requisição HEAD:
$resultado = $cotidiano->urlValida('https://example.com');

Formato do retorno:

[
    'url' => 'https://example.com',
    'formato_valido' => true,
    'http_status' => 200,
    'acessivel' => true,
    'erro' => null,
]

Proteções aplicadas:

somente protocolos HTTP e HTTPS;
certificados TLS são verificados;
endereços locais, privados, reservados ou não resolvidos são bloqueados;
o IP público validado é fixado na conexão para mitigar DNS rebinding;
redirecionamentos automáticos ficam desabilitados para evitar SSRF por redirecionamento;
mensagens internas do cURL não são expostas ao consumidor.

Banco de dados

Todos os métodos recebem uma conexão PDO e retornam:

[
    'status' => true,
    'msg_erro' => '',
    'total_registros' => 1,
    'data' => [],
]

Inserção a partir de array

Esta é a forma preferida para inserções simples:

$resultado = $cotidiano->insert(
    'clientes',
    ['nome' => 'Ana', 'email' => 'ana@example.com'],
    $pdo
);

Tabela e colunas são validadas, e os valores são enviados por placeholders.

Consultas e escritas parametrizadas

$resultado = $cotidiano->selecionarDados(
    'SELECT id, nome FROM clientes WHERE email = :email',
    $pdo,
    ['email' => 'ana@example.com']
);

$resultado = $cotidiano->cadastrarDados(
    'INSERT INTO clientes (nome, email) VALUES (:nome, :email)',
    $pdo,
    ['nome' => 'Ana', 'email' => 'ana@example.com']
);

$resultado = $cotidiano->atualizarDados(
    'UPDATE clientes SET nome = :nome WHERE id = :id',
    $pdo,
    ['nome' => 'Ana Maria', 'id' => 123]
);

$resultado = $cotidiano->deletarDados(
    'DELETE FROM clientes WHERE id = :id',
    $pdo,
    ['id' => 123]
);

Regras de segurança:

sempre use placeholders para valores externos;
apenas uma instrução é aceita por chamada;
o comando precisa aparecer no início da instrução;
UPDATE e DELETE exigem WHERE fora de literais e comentários;
SQL e mensagens internas do driver não são devolvidos em erros;
consultas sem resultados são bem-sucedidas e retornam data => [].

Essas verificações são uma defesa adicional, não um substituto para permissões mínimas no banco, transações e consultas parametrizadas.

Qualidade

Instale as dependências e execute:

composer test   # PHPUnit
composer stan   # PHPStan nível 8
composer cs     # PSR-12
composer fix    # correção automática PSR-12
composer check  # testes + análise estática + estilo

A suíte cobre:

CPF e CNPJ;
fachada pública;
datas e textos;
formato/protocolo de URLs sem depender da rede;
CRUD com SQLite em memória;
bloqueio de SQL sem WHERE e múltiplas instruções.

Compatibilidade e migração

As assinaturas históricas continuam aceitas. Os métodos SQL livre agora possuem um terceiro parâmetro opcional para valores preparados:

selecionarDados(string $sql, PDO $conn, array $parametros = []): array

O mesmo vale para cadastrarDados(), atualizarDados() e deletarDados().

A fachada recomendada mudou para leomottarocha\cotidiano, sem remover a classe histórica:

// Recomendado:
use leomottarocha\cotidiano;

// Legado, ainda compatível:
use Leomottarocha\Cotidiano\Models\Cotidiano as CotidianoLegado;

Referência das classes

`Leomottarocha\Cotidiano`

Fachada principal recomendada. Pode ser importada exatamente como use leomottarocha\cotidiano; e disponibiliza todos os utilitários da biblioteca.

`Leomottarocha\Cotidiano\Models\Cotidiano`

Implementação histórica mantida para compatibilidade. Centraliza documentos, datas, textos, HTTP e operações PDO. Novos projetos devem usar a fachada principal.

`Leomottarocha\Cotidiano\Models\Cpf`

Classe especialista em limpeza, máscara e validação dos dígitos verificadores de CPF. Não realiza consultas externas.

`Leomottarocha\Cotidiano\Models\Cnpj`

Classe especialista em limpeza, máscara, classificação e validação de CNPJ numérico ou alfanumérico. Não realiza consultas externas.

As classes e todos os métodos públicos possuem PHPDoc com contratos, parâmetros, retornos, exceções e observações relevantes de segurança.

Mudanças comportamentais intencionais:

consultas vazias agora retornam sucesso com zero registros;
erros de PDO não expõem SQL ou detalhes internos;
urlValida() não ignora mais certificados inválidos;
URLs privadas e protocolos diferentes de HTTP/HTTPS são recusados;
gerarSenhaRandomica(0) lança uma exceção;
datas Y-m-d impossíveis são rejeitadas.

Política de documentação

O README.md é parte do contrato público do projeto. Toda alteração que afete API, dependências, configuração, segurança, comportamento, instalação ou comandos de qualidade deve atualizar este arquivo no mesmo conjunto de mudanças.

Checklist para contribuições:

adicionar ou atualizar testes;
executar composer check;
atualizar o README.md;
evitar expor segredos, SQL, dados pessoais ou mensagens internas;
registrar mudanças incompatíveis na seção de migração.

Histórico recente

Próxima versão

nova entrada principal disponível por use leomottarocha\cotidiano;;
autoload da fachada compatível com a forma minúscula em Windows e Linux;
namespace histórico mantido para compatibilidade;
remoção de acentos determinística em Windows e Linux;
caches das ferramentas de qualidade ignorados pelo Git;
análise estática compatível com PHPStan 2.2;
PHPDoc completo nas classes e nos métodos públicos;
fachada corrigida para expor identificação de CNPJ numérico e alfanumérico;
tipagem e contratos de retorno aprimorados;
validação estrita de datas;
HTTP com validação TLS e mitigação de SSRF;
operações PDO parametrizadas e mensagens de erro seguras;
retornos de banco padronizados;
PHPUnit, PHPStan, PHPCS e PHP-CS-Fixer configurados;
arquivo de licença MIT incluído no pacote;
documentação reescrita e alinhada à implementação.

Licença

MIT.

leomottarocha / cotidiano

Maintainers

Package info

Statistics

Security