Search by

sat-suite / number-to-words

xaamin

Currency based number to words converter (Spanish, CFDI importe con letra)

Package info

gitlab.com/sat-suite/number-to-words

Issues

pkg:composer/sat-suite/number-to-words

Statistics

Installs: 2 792

Dependents: 0

Suggesters: 0

Stars: 0

1.0.0 2026-11-14 19:33 UTC

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 como DÓ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.

ClaveClaseSingular / plural
MXNCurrencies\PesoMexicanopeso / pesos
USDCurrencies\DolarEstadounidensedólar / dólares
EURCurrencies\Euroeuro / euros
CADCurrencies\DolarCanadiensedó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 aceptan int y float (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) lanzan SatSuite\NumberToWords\Exceptions\InvalidNumberException. Ambas excepciones extienden InvalidArgumentException.
  • 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.