Download the PHP package omegaalfa/query-builder without Composer

🚀 Sobre o Projeto

Omegaalfa Query Builder é uma biblioteca moderna, leve e fortemente tipada em PHP 8.4+ para construção fluente de queries SQL com PDO.

🎯 Principais Características

• 🔒 100% Prepared Statements - Segurança contra SQL Injection por design
• 🎨 Fluent API - Interface intuitiva e encadeável
• 📦 Zero Dependências - Apenas PHP 8.4+ e PDO
• 🧪 Testado - 73 testes, 145 assertions
• ⚡ Performance - Cache inteligente e streaming de resultados
• 🔄 Transações - Suporte completo com savepoints
• 🌐 Multi-driver - MySQL, PostgreSQL, SQLite, SQL Server
• 📝 Type-Safe - Enums tipadas e strict_types
• 📚 Documentado - PHPDoc completo em todos os métodos

Inspirado em: Eloquent, Doctrine DBAL, Laravel Query Builder

📦 Instalação

Requisitos

• PHP >= 8.4 com strict_types habilitado
• Extensão PDO habilitada
• Driver PDO correspondente ao seu banco de dados
• Bancos suportados: MySQL 5.7+, MariaDB 10.2+, PostgreSQL 9.6+, SQLite 3.x+, SQL Server, Oracle

🚀 Início Rápido

Configuração Básica

⚡ Performance & Benchmarks

Streaming de Grandes Volumes

Benchmark comparativo entre Omegaalfa Query Builder (execute(false)) e Laravel Eloquent (cursor()) para processamento de grandes datasets com unbuffered queries (streaming real).

🏆 Conclusões

• ✅ Até 4.6x mais rápido que Laravel Eloquent para volumes acima de 1M de registros
• ✅ Consumo de memória previsível - ~32MB constantes para streaming de 1M de registros
• ✅ Escalabilidade linear - performance proporcional ao volume de dados
• ✅ Ideal para: ETL, relatórios, exports, processamento batch, big data

📌 Condições do Teste

• PHP: 8.4.1
• Banco: MySQL 8.0 com big.csv (1M registros)
• Ambiente: WSL2 Ubuntu
• Método Omega: execute(false) - unbuffered query com Generator
• Método Laravel: DB::cursor() - lazy collection streaming
• Hardware: Ambiente de desenvolvimento padrão

⚠️ Nota: Resultados podem variar conforme hardware, configuração do PHP/MySQL e características dos dados. Benchmark disponível em teste.php para validação independente.

📖 Documentação Completa

📋 Índice de Métodos

Operações Básicas:

• select() - Consulta SELECT
• insert() - Inserir registro
• insertBatch() - Inserir múltiplos registros
• update() - Atualizar registros
• delete() - Deletar registros

Cláusulas WHERE:

• where() - Condição AND
• orWhere() - Condição OR
• whereIn() - Verificar se está na lista
• whereNotIn() - Verificar se NÃO está na lista
• whereBetween() - Entre dois valores
• whereNotBetween() - Fora de intervalo
• whereNull() - Verificar NULL
• whereNotNull() - Verificar NOT NULL

JOINs:

• join() - Junção entre tabelas

Agrupamento e Ordenação:

• groupBy() - Agrupar resultados
• having() - Filtrar grupos
• havingRaw() - HAVING com SQL bruto
• orderBy() - Ordenar resultados
• limit() - Limitar resultados

Funções de Agregação:

• count() - Contar registros
• sum() - Somar valores
• avg() - Calcular média
• min() - Valor mínimo
• max() - Valor máximo
• exists() - Verificar existência

Avançado:

• raw() - Query SQL customizada
• alias() - Definir alias para tabela
• transactional() - Executar em transação
• cache() - Habilitar cache de query
• execute() - Executar query
• getQuerySql() - Obter SQL gerado
• toSql() - SQL formatado para debug
• explain() - Análise de performance

🔨 Referência de Métodos

SELECT

select()

Inicia uma consulta SELECT.

Parâmetros:

• $table - Nome da tabela
• $fields - Array de colunas (default: ['*'])

Exemplo:

⚠️ Segurança: Para campos dinâmicos vindos de usuário, sempre use whitelist:

INSERT

insert()

Insere um único registro.

Parâmetros:

• $table - Nome da tabela
• $data - Array associativo [coluna => valor]

Exemplo:

insertBatch()

Insere múltiplos registros de uma vez.

Parâmetros:

• $table - Nome da tabela
• $data - Array de arrays associativos

Exemplo:

⚠️ Importante: Todos os registros devem ter as mesmas colunas.

UPDATE

update()

Atualiza registros existentes.

Parâmetros:

• $table - Nome da tabela
• $data - Array associativo [coluna => novo valor]

Exemplo:

⚠️ Sempre use WHERE para evitar atualizar toda a tabela!

DELETE

delete()

Remove registros.

Parâmetros:

• $table - Nome da tabela

Exemplo:

⚠️ Sempre use WHERE para evitar deletar toda a tabela!

WHERE

where()

Adiciona condição WHERE (AND).

Parâmetros:

• $column - Nome da coluna
• $operator - Operador SQL (use enum SqlOperator)
• $value - Valor para comparação

Operadores disponíveis:

• SqlOperator::EQUALS - =
• SqlOperator::NOT_EQUALS - <>
• SqlOperator::GREATER_THAN - >
• SqlOperator::LESS_THAN - <
• SqlOperator::GREATER_THAN_OR_EQUALS - >=
• SqlOperator::LESS_THAN_OR_EQUALS - <=
• SqlOperator::LIKE - LIKE
• SqlOperator::NOT_LIKE - NOT LIKE

Exemplo:

orWhere()

Adiciona condição WHERE (OR).

Exemplo:

whereIn()

Verifica se valor está na lista.

Exemplo:

whereNotIn()

Verifica se valor NÃO está na lista.

Exemplo:

whereBetween()

Verifica se valor está entre dois valores.

Parâmetros:

• $range - Array com 2 elementos: [min, max]

Exemplo:

whereNotBetween()

Verifica se valor NÃO está entre dois valores.

whereNull()

Verifica se coluna é NULL.

Exemplo:

whereNotNull()

Verifica se coluna NÃO é NULL.

Exemplo:

JOIN

join()

Cria junção (JOIN) entre tabelas.

Parâmetros:

• $table - Tabela a ser unida
• $key - Coluna da primeira tabela
• $operator - Operador de comparação (=, <>, >, <, >=, <=)
• $refer - Coluna da segunda tabela
• $type - Tipo de JOIN (enum JoinType)

Tipos de JOIN:

• JoinType::INNER - INNER JOIN (padrão)
• JoinType::LEFT - LEFT JOIN
• JoinType::RIGHT - RIGHT JOIN
• JoinType::FULL - FULL JOIN (não suportado no MySQL)

Exemplo:

AGRUPAMENTO E ORDENAÇÃO

groupBy()

Agrupa resultados por coluna.

Exemplo:

having()

Filtra grupos (após GROUP BY).

Exemplo:

havingRaw()

HAVING com SQL customizado (use com cuidado).

Exemplo:

⚠️ ADVANCED API: Use apenas com SQL confiável, nunca com input de usuário!

orderBy()

Ordena resultados.

Parâmetros:

• $column - Coluna para ordenar
• $direction - Direção: OrderDirection::ASC ou OrderDirection::DESC

Exemplo:

limit()

Limita número de resultados (paginação).

Parâmetros:

• $limit - Quantidade de registros (1-10000)
• $offset - Posição inicial (0-1000000)

Exemplo:

FUNÇÕES DE AGREGAÇÃO

count()

Conta registros.

Exemplo:

sum()

Soma valores de uma coluna.

Exemplo:

avg()

Calcula média.

Exemplo:

min()

Retorna valor mínimo.

Exemplo:

max()

Retorna valor máximo.

Exemplo:

exists()

Verifica se existe algum registro.

Exemplo:

MÉTODOS AVANÇADOS

raw()

Executa query SQL customizada.

Exemplo:

⚠️ ADVANCED API: Use apenas com SQL estático confiável!

alias()

Define alias para a tabela principal.

Exemplo:

transactional()

Executa código dentro de transação com rollback automático.

Exemplo:

cache()

Habilita cache de query.

Parâmetros:

• $ttl - Tempo de vida em segundos (default: 1 hora)

Exemplo:

⚠️ Importante: O cache não isola por usuário. Para dados sensíveis, sempre filtre por usuario_id:

execute()

Executa a query e retorna resultados.

Retorno:

Exemplo:

getQuerySql()

Retorna SQL gerado (sem substituir parâmetros).

Exemplo:

toSql()

SQL formatado para debug (com valores substituídos).

Exemplo:

⚠️ Apenas para debug! Nunca use toSql(true) em produção.

explain()

Analisa performance da query (EXPLAIN).

Exemplo:

📝 Exemplos Completos

Exemplo 1: CRUD Completo

Exemplo 2: Relatório com JOINs e Agregações

Exemplo 3: Paginação Completa

Exemplo 4: Transação Complexa

Exemplo 5: Query Complexa com Subqueries

🧪 Testes

O projeto possui cobertura completa de testes com PHPUnit.

Executar Testes

Suítes de Teste

• ✅ QueryBuilderUnitTest - Testes unitários básicos
• ✅ QueryBuilderIntegrationTest - Testes de integração
• ✅ QueryBuilderSecurityTest - Testes de segurança
• ✅ QueryBuilderBindingTest - Testes de parameter binding
• ✅ QueryBuilderCacheTest - Testes de cache
• ✅ QueryBuilderOperationsTest - Testes de operações SQL
• ✅ QueryBuilderExecutionTest - Testes de execução
• ✅ QueryBuilderFullTest - Testes end-to-end

Status: 73 testes, 145 assertions, 0 failures

🔒 Segurança

Arquitetura Segura

Este Query Builder foi desenvolvido com segurança por design:

✅ 100% Prepared Statements para valores
✅ Type-safe binding (PDO::PARAM_INT, PDO::PARAM_NULL, etc)
✅ Strict types habilitado em todos os arquivos
✅ Validação de operadores em JOINs
✅ Enums tipadas para operadores SQL
✅ Quote automático de identificadores (Identifier Injection Protection) ✅ Isolamento de Cache por contexto de conexão (Multi-tenant safe)

Documentação de Segurança

• 📄 SECURITY.md - Política de segurança
• 📄 SECURITY_AUDIT_REVISED.md - Análise de segurança completa

Uso Seguro

Reportar Vulnerabilidades

🔒 Não reporte vulnerabilidades via issues públicas!

• 📧 Email: [email protected]
• 🔐 GitHub Security Advisory: Criar advisory

Resposta garantida em 24-48 horas.

🗺️ Roadmap

✅ v1.0 (Atual)

• [x] Query Builder completo
• [x] Prepared statements obrigatórios
• [x] Enums tipadas
• [x] Cache integrado
• [x] Transações com savepoints
• [x] Multi-driver
• [x] 73 testes automatizados
• [x] Auditoria de segurança

🚧 v1.1 (Planejado)

• [ ] Query Builder para migrations
• [ ] Soft deletes
• [ ] Events/Observers
• [ ] Connection pooling
• [ ] Context-aware cache

💡 v2.0 (Futuro)

• [ ] Query caching com Redis/Memcached
• [ ] Read replicas
• [ ] Sharding support
• [ ] GraphQL query builder
• [ ] Performance profiler visual

🐛 Reportando Bugs

Encontrou um bug? Ajude-nos a melhorar!

Como Reportar

1. Verifique se já não foi reportado nas Issues
2. Abra uma nova issue com:

🤝 Contribuindo

Contribuições são muito bem-vindas!

Como Contribuir

1. Fork o repositório
2. Crie uma branch: git checkout -b feature/MinhaFeature
3. Commit: git commit -m 'Adiciona MinhaFeature'
4. Push: git push origin feature/MinhaFeature
5. Abra um Pull Request

Diretrizes

• ✅ Siga PSR-12
• ✅ Adicione testes para novas features
• ✅ Mantenha strict_types
• ✅ Documente com PHPDoc
• ✅ Execute composer phpstan antes de commitar
• ✅ Atualize README se necessário

📄 Licença

Distribuído sob a Licença MIT. Veja LICENSE para detalhes.

💬 Contato e Suporte

Autor

Omegaalfa

• 🌐 GitHub: @omegaalfa
• 📧 Email: [email protected]
• 💼 Website: omegaalfa.dev

Comunidade

• 💬 Discussions - Dúvidas e discussões
• 🐛 Issues - Reportar bugs
• 📚 Wiki - Documentação adicional
• 📋 Changelog - Histórico de versões

⭐ Mostre seu Apoio

Se este projeto foi útil:

• ⭐ Dê uma estrela no GitHub
• 🐦 Compartilhe com a comunidade
• 🤝 Contribua com código ou documentação
• ☕ Apoie via GitHub Sponsors

💬 Contato

Criado por Omegaalfa.
Para dúvidas ou sugestões: github.com/omegaalfa