Changed namespace and added formatter

Author: raarevalo96

README.es.md

@@ -10,6 +10,8 @@ Desde el 17 de diciembre de 2021, los DUIs son NITs válidos para personas natur
 
 Las personas jurídicas no se ven afectadas por este cambio, por lo que aún debe usar la validación de NIT para ellas.
 
+También hay una opción para anular esta funcionalidad en la biblioteca cuando sea necesario.
+
 ## Instalación
 Puedes usar composer para instalar idSV en ty proyecto:
 
@@ -19,44 +21,78 @@ composer require avalontechsv/idSV
 
 ## Uso
 ```php
-use avalontechsv\idSV;
+use avalontechsv\idSV\idSV;
 
-$validator = new idSV;
+$validator = new idSV();
 
 // Validación de DUI
-// Validar DUI en el formato 00000000-0
-$validator->isValidDUI('00000000-0'); // true
-$validator->isValidDUI('00000000-1'); // false
+// Validar DUI en formato 00000000-0
+var_dump($validator->isValidDUI('00000000-0')); // true
+var_dump($validator->isValidDUI('00000000-1')); // false
 
-// Validar DUI en el formato 000000000
-$validator->isValidDUI('000000000'); // true
-$validator->isValidDUI('000000001'); // false
+// Validar DUI en formato 000000000
+var_dump($validator->isValidDUI('000000000')); // true
+var_dump($validator->isValidDUI('000000001')); // false
 
-// La biblioteca eliminará automáticamente los espacios en blanco.
-// Esto es útil cuando está validando entradas de un usuario.
-$validator->isValidDUI(' 000000000 '); // true
+// Esta libraría automáticamente elimina los espacios en blanco.
+// Esto es útil cuando estás validando la entrada del usuario.
+var_dump($validator->isValidDUI(' 000000000 ')); // true
 
 // Validación de NIT
-// Validar NIT en el formato 0000-000000-000-0
-$validator->isValidNIT('0000-000000-000-0'); // true
-$validator->isValidNIT('0000-000000-000-1'); // false
-
-// Validar NIT en el formato 0000000000000
-$validator->isValidNIT('0000000000000'); // true
-$validator->isValidNIT('0000000000001'); // false
-
-// También puede validar NITs para personas naturales
-// en el formato DUI.
-$validator->isValidNIT('00000000-0'); // true
-$validator->isValidNIT('00000000-1'); // false
-
-// La biblioteca eliminará automáticamente los espacios en blanco.
-// Esto es útil cuando está validando entradas de un usuario.
-$validator->isValidNIT(' 0000000000000 '); // true
-
-// DUI y NIT también pueden ser nulos
-$validator->isValidDUI(null); // false
-$validator->isValidNIT(null); // false
+// Validar NIT en formato 0000-000000-000-0
+var_dump($validator->isValidNIT('0000-000000-000-0')); // true
+var_dump($validator->isValidNIT('0000-000000-000-1')); // false
+
+// Validar NIT en formato 0000000000000
+var_dump($validator->isValidNIT('0000000000000')); // true
+var_dump($validator->isValidNIT('0000000000001')); // false
+
+// También se puede validar un DUI como NIT para personas naturales
+var_dump($validator->isValidNIT('00000000-0')); // true
+var_dump($validator->isValidNIT('00000000-1')); // false
+
+// Esta libraría automáticamente elimina los espacios en blanco.
+// Esto es útil cuando estás validando la entrada del usuario.
+var_dump($validator->isValidNIT(' 0000000000000 ')); // true
+
+// Los DUI y NIT también pueden ser nulos
+var_dump($validator->isValidDUI(null)); // false
+var_dump($validator->isValidNIT(null)); // false
+
+// Formateo de DUI y NIT
+
+// Formatear DUI en el formato 00000000-0
+var_dump($validator->formatDUI('000000000')); // 00000000-0
+
+// Cadenas más cortas se rellenan con ceros
+var_dump($validator->formatDUI('00')); // 00000000-0
+
+// Si un DUI ya está formateado, se devolverá como está
+var_dump($validator->formatDUI('00000000-0')); // 00000000-0
+
+// Si se intenta formatear un DUI inválido, se genera una excepción
+try { $validator->formatDUI('000000001'); } catch (\Exception $e) { echo 'Exception: ' . $e->getMessage(); } // Exception: Invalid DUI
+
+// Formatear NIT en el formato 0000-000000-000-0
+var_dump($validator->formatNIT('00000000000000')); // 0000-000000-000-0
+
+// Cadenas más cortas se rellenan con ceros
+var_dump($validator->formatNIT('00')); // 0000-000000-000-0
+
+// Si un NIT ya está formateado, se devolverá como está
+var_dump($validator->formatNIT('0000-000000-000-0')); // 0000-000000-000-0
+
+// Los DUIs válidos se formatearán como DUIs en el formateador de NIT por defecto
+var_dump($validator->formatNIT('000000000')); // 00000000-0
+
+// Se puede desactivar el formateo de DUIs como NITs
+var_dump($validator->formatNIT('000000000', false)); // 0000-000000-000-0
+
+// El rellenado de ceros también se aplica a los NIT con formateo de DUI desactivado
+var_dump($validator->formatNIT('00', false)); // 0000-000000-000-0
+
+// Si se intenta formatear un NIT inválido, se genera una excepción
+try { $validator->formatNIT('0000000000001'); } catch (\Exception $e) { echo 'Exception: ' . $e->getMessage() . '\n';  } // Exception: Invalid NIT
 ```
 ## Pruebas
 Puedes ejecutar las pruebas con PHPUnit:

README.md

@@ -10,6 +10,8 @@ Since December 17th, 2021, DUIs are valid NITs for natural persons, so any DUI i
 
 Legal entities are not affected by this change, so you should still use the NIT validation for them.
 
+There is also an option to override this functionality in the library when required.
+
 ## Installation
 You can use composer to install idSV in your project:
 
@@ -19,44 +21,79 @@ composer require avalontechsv/idSV
 
 ## Usage
 ```php
-use avalontechsv\idSV;
+use avalontechsv\idSV\idSV;
 
-$validator = new idSV;
+$validator = new idSV();
 
 // DUI validation
 // Validate DUI in the format 00000000-0
-$validator->isValidDUI('00000000-0'); // true
-$validator->isValidDUI('00000000-1'); // false
+var_dump($validator->isValidDUI('00000000-0')); // true
+var_dump($validator->isValidDUI('00000000-1')); // false
 
 // Validate DUI in the format 000000000
-$validator->isValidDUI('000000000'); // true
-$validator->isValidDUI('000000001'); // false
+var_dump($validator->isValidDUI('000000000')); // true
+var_dump($validator->isValidDUI('000000001')); // false
 
 // The library will automatically trim the input.
 // This is useful when you are validating user input.
-$validator->isValidDUI(' 000000000 '); // true
+var_dump($validator->isValidDUI(' 000000000 ')); // true
 
 // NIT validation
 // Validate NIT in the format 0000-000000-000-0
-$validator->isValidNIT('0000-000000-000-0'); // true
-$validator->isValidNIT('0000-000000-000-1'); // false
+var_dump($validator->isValidNIT('0000-000000-000-0')); // true
+var_dump($validator->isValidNIT('0000-000000-000-1')); // false
 
 // Validate NIT in the format 0000000000000
-$validator->isValidNIT('0000000000000'); // true
-$validator->isValidNIT('0000000000001'); // false
+var_dump($validator->isValidNIT('0000000000000')); // true
+var_dump($validator->isValidNIT('0000000000001')); // false
 
 // Also, you can validate NITs for natural persons
 // in the DUI format.
-$validator->isValidNIT('00000000-0'); // true
-$validator->isValidNIT('00000000-1'); // false
+var_dump($validator->isValidNIT('00000000-0')); // true
+var_dump($validator->isValidNIT('00000000-1')); // false
 
 // The library will automatically trim the input.
 // This is useful when you are validating user input.
-$validator->isValidNIT(' 0000000000000 '); // true
+var_dump($validator->isValidNIT(' 0000000000000 ')); // true
 
 // DUI and NIT can also be null
-$validator->isValidDUI(null); // false
-$validator->isValidNIT(null); // false
+var_dump($validator->isValidDUI(null)); // false
+var_dump($validator->isValidNIT(null)); // false
+
+// DUI and NIT formatting
+
+// Format DUI in the format 000000000
+var_dump($validator->formatDUI('000000000')); // 00000000-0
+
+// Shorter strings will be padded with zeros
+var_dump($validator->formatDUI('00')); // 00000000-0
+
+// If a DUI was already formatted, it will be returned as is
+var_dump($validator->formatDUI('00000000-0')); // 00000000-0
+
+// Invalid DUIs generate an exception
+try { $validator->formatDUI('000000001'); } catch (\Exception $e) { echo 'Exception: ' . $e->getMessage(); } // Exception: Invalid DUI
+
+// Format NIT in the format 0000000000000
+var_dump($validator->formatNIT('00000000000000')); // 0000-000000-000-0
+
+// Shorter strings will be padded with zeros
+var_dump($validator->formatNIT('00')); // 0000-000000-000-0
+
+// If a NIT was already formatted, it will be returned as is
+var_dump($validator->formatNIT('0000-000000-000-0')); // 0000-000000-000-0
+
+// Valid DUIs will be formatted as DUI in the NIT formatter by default
+var_dump($validator->formatNIT('000000000')); // 00000000-0
+
+// You can force the NIT formatter to disallow DUIs too
+var_dump($validator->formatNIT('000000000', false)); // 0000-000000-000-0
+
+// Padding is also applied to NITs
+var_dump($validator->formatNIT('00', false)); // 0000-000000-000-0
+
+// Invalid NITs generate an exception
+try { $validator->formatNIT('0000000000001'); } catch (\Exception $e) { echo 'Exception: ' . $e->getMessage() . '\n';  } // Exception: Invalid NIT
 ```
 ```
 ## Testing

composer.json

@@ -1,19 +1,20 @@
 {
     "name": "avalontechsv/idsv",
-    "description": "Validate common identity numbers in El Salvador",
+    "description": "Validate and format common identity numbers in El Salvador",
     "type": "library",
     "license": "GPL-3.0-or-later",
     "require": {
         "php": ">=7.2"
     },
     "autoload": {
         "psr-4": {
-            "avalontechsv\\": "src/"
+            "avalontechsv\\idSV\\": "src/",
+            "avalontechsv\\idSV\\Exceptions\\": "src/Exceptions/"
         }
     },
     "autoload-dev": {
         "psr-4": {
-            "avalontechsv\\Tests\\": "tests/"
+            "avalontechsv\\idSV\\Tests\\": "tests/"
         }
     },
     "authors": [

index.php

@@ -1,6 +1,6 @@
 <?php
 
-use avalontechsv\idSV;
+use avalontechsv\idSV\idSV;
 
 require_once 'vendor/autoload.php';
 
@@ -39,4 +39,32 @@
 
 // DUI and NIT can also be null
 echo '$validator->isValidDUI(null) -> '; var_dump($validator->isValidDUI(null)); // false
-echo '$validator->isValidNIT(null) -> '; var_dump($validator->isValidNIT(null)); // false
+echo '$validator->isValidNIT(null) -> '; var_dump($validator->isValidNIT(null)); // false
+
+// DUI and NIT formatting
+
+// Format DUI in the format 000000000
+echo '$validator->formatDUI(\'000000000\') -> '; var_dump($validator->formatDUI('000000000')); // 00000000-0
+
+// If a DUI was already formatted, it will be returned as is
+echo '$validator->formatDUI(\'00000000-0\') -> '; var_dump($validator->formatDUI('00000000-0')); // 00000000-0
+
+// Invalid DUIs generate an exception
+echo '$validator->formatDUI(\'000000001\') -> ';
+try { $validator->formatDUI('000000001'); } catch (\Exception $e) { echo 'Exception: ' . $e->getMessage() . '\n'; } // Exception: Invalid DUI
+
+// Format NIT in the format 0000000000000
+echo '$validator->formatNIT(\'00000000000000\') -> '; var_dump($validator->formatNIT('00000000000000')); // 0000-000000-000-0
+
+// If a NIT was already formatted, it will be returned as is
+echo '$validator->formatNIT(\'0000-000000-000-0\') -> '; var_dump($validator->formatNIT('0000-000000-000-0')); // 0000-000000-000-0
+
+// Valid DUIs will be formatted as DUI in the NIT formatter by default
+echo '$validator->formatNIT(\'000000000\') -> '; var_dump($validator->formatNIT('000000000')); // 00000000-0
+
+// You can force the NIT formatter to disallow DUIs too
+echo '$validator->formatNIT(\'000000000\', false) -> '; var_dump($validator->formatNIT('000000000'), false); // 0000-000000-000-0
+
+// Invalid NITs generate an exception
+echo '$validator->formatNIT(\'0000000000001\') -> ';
+try { $validator->formatNIT('0000000000001'); } catch (\Exception $e) { echo 'Exception: ' . $e->getMessage() . '\n';  } // Exception: Invalid NIT

src/Exceptions/InvalidDUIException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace avalontechsv\idSV\Exceptions;
+
+use Exception;
+
+class InvalidDUIException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('The provided DUI is invalid. DUI must be numeric and have a valid check digit.');
+    }
+
+    public function __toString()
+    {
+        return __CLASS__ . ": [{$this->code}]: {$this->message}";
+    }
+
+}

src/Exceptions/InvalidNITException.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace avalontechsv\idSV\Exceptions;
+
+use Exception;
+
+class InvalidNITException extends Exception
+{
+    public function __construct()
+    {
+        parent::__construct('The provided NIT is invalid. NIT must be numeric and have a valid check digit.');
+    }
+
+    public function __toString()
+    {
+        return __CLASS__ . ": [{$this->code}]: {$this->message}";
+    }
+
+}