sat-suite / number-to-words
Currency based number to words converter (Spanish, CFDI importe con letra)
Requires
- php: ^8.3
- ext-mbstring: *
Requires (Dev)
- pestphp/pest: ^3.0
- phpstan/phpstan: ^2.1
- squizlabs/php_codesniffer: ^3.8
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-20 17:17:36 UTC
README
Convierte un importe numérico a letras en español, con el formato usual de las facturas mexicanas:
Mil doscientos treinta y cuatro pesos con 50/100 MXN.
Dentro de sat-suite sirve para el "importe con letra" de la representación impresa (PDF) del CFDI,
después del timbrado. No es un requisito del Anexo 20 ni modifica el XML: el XML se construye con
sat-suite/cfdi-builder. Trae predefinidas las monedas MXN, USD, EUR y CAD (claves del catálogo
c_Moneda) y permite registrar otras. Es independiente del resto de los paquetes.
Requisitos
- PHP
^8.3 ext-mbstring(para pasar a minúsculas letras acentuadas comoDÓLARES)
Sin dependencias de Composer.
Instalación
composer require sat-suite/number-to-words
Uso
use SatSuite\NumberToWords\Words;
$words = new Words(); // moneda por defecto: MXN
$words->from('1234567.89'); // "Un millón doscientos treinta y cuatro mil quinientos sesenta y siete pesos con 89/100 MXN"
$words->from('1,234.5'); // "Mil doscientos treinta y cuatro pesos con 50/100 MXN"
$words->from('1'); // "Un peso con 00/100 MXN"
$words->from('21'); // "Veintiún pesos con 00/100 MXN"
$words->from('0.5'); // "Cero pesos con 50/100 MXN"
$words->from('1000000000.00'); // "Mil millones de pesos con 00/100 MXN"
$words->from('1000000000000'); // "Un billón de pesos con 00/100 MXN"
$words->from(1500); // "Mil quinientos pesos con 00/100 MXN"
Monedas
from($number, $currency = null) acepta la clave de la moneda; using($currency) la fija (devuelve
$this).
$words->from('25.50', 'USD'); // "Veinticinco dólares con 50/100 USD"
$words->from('100.01', 'CAD'); // "Cien dólares con 01/100 CAD"
$words->using('EUR')->from('1'); // "Un euro con 00/100 EUR"
Ojo: la moneda es estado de la instancia. Después de from($n, 'USD'), las llamadas sin moneda
siguen en USD. Usa una instancia por moneda o pasa siempre la clave.
| Clave | Clase | Singular / plural |
|---|---|---|
MXN | Currencies\PesoMexicano | peso / pesos |
USD | Currencies\DolarEstadounidense | dólar / dólares |
EUR | Currencies\Euro | euro / euros |
CAD | Currencies\DolarCanadiense | dólar / dólares |
Una clave no registrada lanza SatSuite\NumberToWords\Exceptions\UnsupportedCurrencyException
(Currency JPY is not supported).
Registrar otras monedas
Extiende Currencies\Currency (implementa getName() con la clave y getMeta() con las llaves
singular, plural, prefix, sufix y symbol) y regístrala en un CurrencyManager:
use SatSuite\NumberToWords\Words;
use SatSuite\NumberToWords\CurrencyManager;
use SatSuite\NumberToWords\Currencies\Currency;
class LibraEsterlina extends Currency
{
public function getName()
{
return 'GBP';
}
public function getMeta()
{
return [
'singular' => 'LIBRA ESTERLINA',
'plural' => 'LIBRAS ESTERLINAS',
'prefix' => 'GBP',
'sufix' => 'GBP', // se agrega al final del texto
'symbol' => '£',
];
}
}
$manager = (new CurrencyManager())->register(new LibraEsterlina());
$words = new Words($manager);
$words->from('3.10', 'GBP'); // "Tres libras esterlinas con 10/100 GBP"
CurrencyManager también ofrece get($clave) (devuelve la moneda o lanza
UnsupportedCurrencyException) y all(). Registrar una moneda con una clave existente la
reemplaza (p. ej. otra 'MXN' sustituye a PesoMexicano). Las monedas se pueden leer como
arreglo de sólo lectura sobre getMeta(): $manager->get('USD')['symbol'] → '$'.
Notas de comportamiento
- Entrada. Se recomienda pasar el número como string (
'1234.5','1,234.50'); también se aceptanintyfloat(los floats se formatean con 2 decimales). Las comas de miles se eliminan y el resto debe cumplir^\d+(\.\d+)?$. - Entrada inválida. Negativos, notación científica (
'1e3'), texto o más de 15 dígitos enteros (Words::MAX_DIGITS, hasta 999,999,999,999,999) lanzanSatSuite\NumberToWords\Exceptions\InvalidNumberException. Ambas excepciones extiendenInvalidArgumentException. - Centavos. Se rellenan a 2 dígitos (
'1.5'→50/100) y, con más de 2 decimales, se redondean hacia arriba desde 5 ('100.019'→Cien pesos con 02/100 MXN;'0.999'→Un peso con 00/100 MXN). - Escala. El cuarto grupo de tres cifras es "mil millones"; "billón" es 10^12.
- Ortografía. Se usan acentos ("millón", "billón", "dieciséis", "veintidós", "veintitrés",
"veintiséis") y la apócope ante sustantivo ("Veintiún pesos"). El texto se pasa a minúsculas con
la primera letra en mayúscula; el sufijo de la moneda (
MXN) queda en mayúsculas. - Limitación. Los numerales son siempre masculinos ("Un", "Veintiún", "Doscientos"), así que monedas femeninas producen, por ejemplo, "Un libra" o "Doscientos libras".
Desarrollo
composer install && npm install # npm install instala el hook commit-msg (commitlint) con husky
npm test # Pest (o: composer test)
npm run lint:check # phpcs PSR12 sobre src/ (npm run lint:fix para corregir)
npm run code:scan # phpstan nivel 5
Las versiones se publican con release-it: npm run release[:patch|:minor|:major] sube la versión
de package.json y composer.json, actualiza CHANGELOG.md, hace commit y crea la etiqueta
vX.Y.Z (sin push); después, git push --follow-tags. Los mensajes de commit siguen Conventional
Commits.
Licencia
MIT. Ver LICENSE.