Contribuindo

Recebemos contribuições de todos os tipos — relatórios de bugs, melhorias na documentação, propostas de funcionalidades e código. Esta página resume o processo. Para o acordo completo do contribuidor e diretrizes detalhadas, veja CONTRIBUTING.md no GitHub.

Configuração do Ambiente de Desenvolvimento

Pré-requisitos

Requisito	Versão Mínima
PHP	8.5+
Composer	2.x
PHPUnit	12.x
PHPStan	2.x

Começando

# Clonar o repositório
git clone https://github.com/yeeefang/tcpdf-next.git
cd tcpdf-next

# Instalar dependências
composer install

# Verificar se tudo funciona
composer test

Executando Testes

O TCPDF-Next usa PHPUnit 12 com suítes separadas para testes unitários e de integração.

# Executar a suíte de testes completa
composer test

# Executar apenas testes unitários (rápido, sem I/O)
composer test:unit

# Executar apenas testes de integração (saída de arquivo, carregamento de fontes, etc.)
composer test:integration

Todos os testes devem passar antes que um pull request possa ser mergeado. O pipeline de CI executa a suíte completa em cada push.

Análise Estática

O código é analisado com PHPStan no Level 10 (o nível mais rigoroso):

composer analyse

Zero erros são tolerados. Se sua alteração introduzir um erro do PHPStan, o build de CI falhará.

Requisitos de Estilo de Código

• declare(strict_types=1) no topo de cada arquivo PHP.
• Conformidade com PHPStan Level 10 — sem exceções de baseline para código novo.
• Classes readonly preferidas onde estado mutável não é necessário.
• Backed enums para todos os conjuntos finitos de valores (sem strings mágicas ou constantes inteiras).
• Parâmetros nomeados em métodos de API pública para clareza.
• Sem tipos mixed — cada parâmetro, tipo de retorno e propriedade deve ser explicitamente tipado.
• Final por padrão — classes são final a menos que projetadas para extensão.

Processo de Pull Request

1. Fork o repositório e crie uma branch de funcionalidade a partir de main.

2. Escreva testes primeiro — o TCPDF-Next segue um fluxo de trabalho orientado a TDD. Novas funcionalidades e correções de bugs devem incluir testes correspondentes.

3. Mantenha commits focados — uma mudança lógica por commit. Escreva mensagens de commit claras.

4. Execute a suíte de verificação completa antes de fazer push:

   composer analyse && composer test

5. Abra um pull request contra main. Preencha o template do PR com:

   • Uma descrição da mudança e sua motivação.
   • Links para issues relacionadas (use a sintaxe Closes #123).
   • Quaisquer mudanças que quebrem compatibilidade ou notas de migração.

6. Responda ao feedback da revisão — os mantenedores podem solicitar alterações. Por favor, aborde ou discuta cada comentário.

Reportando Bugs

Abra uma GitHub Issue com:

• Versão do PHP e SO.
• Versão do TCPDF-Next (composer show yeeefang/tcpdf-next).
• Código de reprodução mínimo.
• Comportamento esperado vs. real.

Vulnerabilidades de Segurança

Não reporte problemas de segurança via GitHub Issues públicas. Use os GitHub Security Advisories em vez disso. Veja o FAQ para detalhes.

Obrigado

Cada contribuição torna o TCPDF-Next melhor. Seja corrigindo um erro de digitação na documentação ou implementando uma funcionalidade importante, seu tempo e esforço são genuinamente apreciados.