amarruda/numeros-por-extenso

A package for converting numbers to their written-out form in Portuguese

v1.0.0 2025-11-04 18:30 UTC

Requires

• php: >=7.4

Requires (Dev)

• laravel/pint: ^1.2.0
• pestphp/pest: ^2.0.0
• phpstan/phpstan: ^1.8.6
• symfony/var-dumper: ^6.2.0

MIT

• Alessandro Pinto de Arruda

• package
• php
• numbers
• words

README

Converte números para sua representação por extenso em português (pt-BR). Permite que a saída seja flexionada com o gênero masculino (default) ou feminino.

Para que serve

Este pacote fornece uma classe simples que converte números inteiros e decimais para sua forma escrita por extenso em português. É útil para gerar valores por extenso em recibos, cheques (simulação), relatórios ou qualquer contexto em que seja necessário exibir números por extenso.

Principais características:

• Suporta números inteiros e decimais (aceita vírgula ou ponto como separador decimal).
• Suporte ao gênero feminino para unidades (ex.: "uma" / "duas").
• Compatível com PHP 7.4+ (veja composer.json).

Instalação

Instale via Composer:

composer require amarruda/numeros-por-extenso

Se estiver trabalhando dentro do repo (desenvolvimento local), apenas carregue o autoload do Composer:

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

Uso

Exemplo mínimo:

use Amarruda\NumerosPorExtenso\NumerosPorExtenso;

$np = new NumerosPorExtenso();

echo $np->porExtenso(1234); // "um mil, duzentos e trinta e quatro"

O pacote também aceita strings com separador decimal por vírgula:

echo $np->porExtenso('1,25'); // "um ponto dois cinco"

Gênero feminino:

echo $np->porExtenso(1, 'f'); // "uma"

API rápida

• porExtenso($numero, $genero = 'm') — converte $numero para string por extenso. Retorna string ou false se a entrada não for numérica.

Aceita números do tipo int, float ou string numérica (ex.: "1,25" ou "1.25").

Testes

Este projeto usa Pest para testes. Para rodar a suíte de testes localmente:

./vendor/bin/pest

Também existe um exemplo de uso em examples/usage.php.

Contribuição

Contribuições são bem-vindas. Sugestões:

• Adicionar mais casos de teste (números grandes, limites de PHP_INT_MAX, entrada inválida).
• Internacionalização (variações pt-BR / pt-PT ou outros idiomas).
• Tornar a API mais estrita retornando exceções em vez de false em entradas inválidas (breaking change).

Abra uma issue ou envie um PR com sua proposta.

Licença

MIT — veja o arquivo LICENSE.md.