esolutions/peru

Peru-specific utilities: RUC/DNI validators and number to letters

1.0.0 2026-05-13 20:04 UTC

Requires

• php: ^8.2

proprietary

• Carlos Erique Gaspar

README

Utilidades específicas para el mercado peruano: validación de documentos de identidad y conversión de números a letras para comprobantes electrónicos.

Instalación

composer require esolutions/peru

Namespace

Esolutions\Peru\

Validators — RucValidator

Valida el RUC peruano usando el algoritmo oficial del dígito verificador de SUNAT.

use Esolutions\Peru\Validators\RucValidator;

$result = RucValidator::validate('20100070970');
// → ['success' => true]

$result = RucValidator::validate('12345678901');
// → ['success' => false, 'message' => 'El RUC es incorrecto']

Validaciones aplicadas:

1. Longitud exacta de 11 dígitos
2. Solo caracteres numéricos
3. Dígito verificador correcto (algoritmo módulo 11 de SUNAT)

Validators — DniValidator

Valida el formato del DNI peruano.

use Esolutions\Peru\Validators\DniValidator;

DniValidator::validate('12345678');        // → ['success' => true]
DniValidator::validate('12345678-1234');   // → ['success' => true]
DniValidator::validate('12345678 1234');   // → ['success' => true]
DniValidator::validate('1234');            // → ['success' => false, 'message' => 'El DNI es incorrecto']

Formatos aceptados:

Formato	Ejemplo	Descripción
8 dígitos	12345678	DNI estándar
8 + guion + 4	12345678-1234	Con código de verificación
8 + espacio + 4	12345678 1234	Con código de verificación

Support — NumberToLetterHelper

Convierte valores numéricos a su representación en letras en español. Requerido por SUNAT para comprobantes electrónicos (el monto debe expresarse en letras).

use Esolutions\Peru\Support\NumberToLetterHelper;

// Formato estándar (letras)
NumberToLetterHelper::convertToLetter(1234.56, 'SOLES');
// → "Mil doscientos treinta y cuatro con 56/100 SOLES"

// Formato con número (para comprobantes)
NumberToLetterHelper::convertToLetter(1234.56, 'SOLES', format: true);
// → "1.234,56 (Mil doscientos treinta y cuatro con 56/100 SOLES)"

// Sin moneda
NumberToLetterHelper::convertToLetter(100.00);
// → "Cien con 00/100 "

// Dólares
NumberToLetterHelper::convertToLetter(999999999.99, 'DÓLARES');
// → "Novecientos noventa y nueve millones novecientos noventa y nueve mil novecientos noventa y nueve con 99/100 DÓLARES"

Parámetros:

Parámetro	Tipo	Default	Descripción
$number	float|int|string	—	Número a convertir
$currency	string	''	Texto de moneda (SOLES, DÓLARES)
$format	bool	false	true incluye el número formateado al inicio

Formatos de entrada aceptados:

Entrada	Interpretación
1234.56	Punto como decimal
"1,234.56"	Coma como miles, punto como decimal
"1.234,56"	Punto como miles, coma como decimal
"1234,56"	Coma como decimal

Rango soportado: 0 a 999,999,999.99