README

Omegaalfa Utils

Utilitários PHP pequenos, tipados e sem dependências de runtime.

Um ecossistema modular para scripts, aplicações CLI e microsserviços.

Visão geral

O Omegaalfa Utils reúne componentes independentes para problemas recorrentes de infraestrutura PHP. O projeto prioriza APIs pequenas, comportamento explícito e baixo custo de adoção.

Cada módulo possui responsabilidade e documentação próprias. Você pode usar somente as APIs necessárias; nenhum framework, container ou ciclo de vida global é imposto pelo pacote.

Instalação

Todos os módulos são distribuídos atualmente pelo mesmo pacote Composer:

composer require omegaalfa/utils

Requisitos:

Módulos

Escolha rápida

flowchart TD
    A[Qual problema preciso resolver?]
    A -->|Configuração .env| B[EnvLoader]
    A -->|I/O incremental| C[Stream]
    A -->|Estado HTTP por usuário| D[Session]
    A -->|Transformação pequena| F[Helpers]
    A -->|String otimizada| G[Str]
    A -->|Evitar execução simultânea| H[Lock]
    A -->|Localizar gargalos| I[Profiler]
    A -->|Operar arquivos com segurança| J[Filesystem]
    A -->|Gerar identificadores| K[UUID e ULID]
    A -->|Repetir falhas temporárias| L[Retry]
    A -->|Criar comandos| M[CLI]
    A -->|Transportar dados tipados| N[DTO]
    A -->|Inspecionar valores| O[Debug]
    A -->|Controlar o tempo em testes| P[Clock]
    A -->|Adiar construção de objetos| Q[LazyObject]
    A -->|Executar scripts por menu| R[ScriptRunner]

Important

Os módulos permanecem no mesmo pacote Composer; instale omegaalfa/utils e importe somente as APIs desejadas.

Os requisitos de ambiente são compartilhados enquanto os módulos estiverem no mesmo pacote. Helpers globais não são registrados automaticamente.

Princípios do ecossistema

• zero dependências em produção;
• tipos estritos e PHP moderno;
• namespaces PSR-4 sob Omegaalfa\Utils;
• falhas explícitas por exceptions;
• processamento incremental quando aplicável;
• ausência de integração obrigatória com frameworks;
• testes automatizados e PHPStan no nível máximo.

Desenvolvimento

composer install
composer check
composer test:coverage
composer audit

composer check executa análise estática e testes. Mudanças de comportamento devem incluir testes e atualização do README do módulo afetado.

Contribuição

Antes de propor um novo módulo, confirme que ele:

1. resolve uma responsabilidade pequena e bem definida;
2. não duplica uma solução nativa simples sem ganho claro;
3. não introduz dependência de runtime sem justificativa;
4. possui contratos tipados, testes e documentação independente;
5. não mistura responsabilidades de outro módulo.

Abra uma issue para discutir alterações amplas. Pull requests devem passar por composer check e composer audit.

Licença

Distribuído sob a licença MIT.