mnavarrocarter/php-lib-chilean-rut
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: new v4 version (#5)

Browse Source
This commit is contained in:
Matias Navarro-Carter
2024-03-04 22:02:49 +00:00
committed by GitHub
parent f1b14d4d40
commit 8d5b060acf
28 changed files with 5385 additions and 522 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
README.md
View File

@@ -7,7 +7,7 @@ Además, posee dos *types* para `doctrine/dbal`.
## Instalación
Esta libería funciona con composer:
Esta puede ser instalada mediante composer:
```
composer require mnavarrocarter/chilean-rut
@@ -18,8 +18,11 @@ composer require mnavarrocarter/chilean-rut
### Parseando un Rut
La clase Rut es capaz de parsear cualquier tipo de rut sin importar el formato usando
el método `Rut::parse()`. Confiadamente puedes poner el valor directamente de un
formulario web y `parse` se encargara de sanitizar el string y ver si el RUT es valido.
el método `Rut::parse()`. Confiadamente, puedes poner el valor directamente de un
formulario web y `parse` se encargará de sanitizar el string y ver si el RUT es válido.
> NOTA: Un Rut se considera válido cuando su dígito verificador es algorítmicamente válido
> para el número. Esta libreria no puede validar que el Rut existe realmente.
```php
<?php
@@ -29,50 +32,53 @@ use MNC\ChileanRut\Rut;
$rut = Rut::parse('23.546.565-4');
```
### Validando el Rut
### Validando el RUT
> TLDR: Un objeto `Rut` siempre será valido.
Si tu RUT no es valido, el método `parse` lanzara una excepción de tipo
`MNC\ChileanRut\InvalidRut`. Esto es para seguir buenos principios de *objects
calisthenics*: un objeto de valor siempre se crea en un estado valido, y se mantiene
valido a través de todo su ciclo de vida. No se permiten mutaciones que dejen el
objeto en un estado invalido.
Si tu RUT no es válido, el método `parse` lanzara una excepción de tipo
`MNC\Rut\IsInvalid`. Esto es para seguir buenos principios de *objects
calisthenics*: un objeto de valor siempre se crea en un estado válido, y se mantiene
válido a través de todo su ciclo de vida. No se permiten mutaciones que dejen el
objeto en un estado inválido.
Por esta razón el objecto `$rut` es completamente inmutable. Esto quiere decir
Por esta razón el objeto `MNC\Rut\IsInvalid` es completamente inmutable. Esto quiere decir
que una vez creado no puedes cambiar su estado interno: solo puedes leer información.
Estos son los unicos métodos que puedes usar:
```php
<?php
use MNC\ChileanRut\Rut;
use MNC\Rut;
$rut = Rut::parse('23.546.565-4');
$rut->getNumber(); // (int) 23546565
$rut->getVerifier(); // (string) 4
$rut->number; // (int) 23546565
$rut->verifier; // (MNC\Rut\Verifier::Four) 4
```
### Formateando el Rut
Existen muchas formas distintas de formatear un rut y esta librería soporta muchas
Existen muchas formas distintas de formatear un RUT y esta librería soporta muchas
de ellas. El método format devuelve un objeto al cual puedes encadenar llamadas para
formatear el rut y luego castearlo a un string. La interfaz es encadenable para que
puedas combinar las opciones de formato como quieras.
formatear el RUT y extraer su información de diversas maneras.
He aquí algunos ejemplos:
```php
<?php
use MNC\ChileanRut\Rut;
use MNC\Rut;
$rut = Rut::parse('23.546.565-4');
echo $rut->format()->hyphened(); // 23546565-4
echo $rut->format()->dotted()->hyphened(); // 23.546.565-2
echo $rut->format()->dotted()->hyphened()->obfuscated(); // **.***.565-2
echo $rut->format()->obfuscated()->hyphened(); // *****565-2
echo $rut->format()->obfuscated(); // *****5652
echo $rut->toString(); // 235465654
echo $rut->toSimple(); // 23546565-4
echo $rut->toHuman(); // 23.546.565-4
echo $rut->last(4); // 6565
echo $rut->last(4, pad: '*'); // ****6565
echo $rut->first(4); // 2354
echo $rut->first(4, pad: '*'); // 2354****
```
## Integraciones con Librerías de Terceros
@@ -82,13 +88,13 @@ Esta librería provee dos [*Custom Types*](https://www.doctrine-project.org/proj
para Doctrine, con el objetivo de que puedas mapear tus objetos `Rut` fácilmente
a una base de datos relacional.
El `MNC\ChileanRut\Doctrine\RutType` mapeara tu RUT a una columna VARCHAR.
`MNC\Rut\Doctrine\RutType` mapea tu RUT a una columna VARCHAR.
El string se guarda con puntos y guion. Ex: `16.894.365-2`. Es una forma no tan
eficiente de guardar los RUTS (en términos de espacio), pero ayuda mucho cuando
se visualiza o exporta la base de datos a otras fuentes.
El `MNC\ChileanRut\Doctrine\NumericRutType` mapeara tu RUT a una columna INTEGER.
El numero se guarda sin digito verificador y es recalculado cuando la columna
`MNC\Rut\Doctrine\NumericRutType` mapea tu RUT a una columna INTEGER.
El número se guarda sin dígito verificador y es recalculado cuando la columna
es transformada a un valor PHP. Esta forma de guardar ruts es muy eficiente (en
términos de espacio), pero cuesta comparar y leer los números si visualizas o
exportas los registros en la base de datos.
@@ -97,18 +103,15 @@ Por supuesto, puedes elegir el `Type` que más se ajuste a tus necesidades.
## FAQ
### ¿Cómo nació y por qué esta librería?
### ¿Por qué esta librería?
Esta librería nace de la necesidad de estandarizar una clase Rut común para todos
mis proyectos PHP.
Si bien es cierto, hay muchas librerías con implementaciones de Rut chilenos en PHP,
muchas de ellas tienen notorias deficiencias:
1. No están testeadas unitariamente,
2. No tienen un buen diseño y sus apis tienen efectos secundarios.
3. Están acopladas a un framework (Laravel Rut y otras hierbas)
4. No proveen herramientas ni integraciones con librerías de terceros.
### ¿Por qué PHP 7.4?
PHP 7.3 ya no tiene mucho tiempo de soporte y 8.0 esta ad portas de ser lanzado. Hay que
empujar el ecosistema hacia adelante.
1. No están testeadas unitariamente.
2. No estan tipadas apropiadamente
3. No tienen un buen diseño y sus apis tienen efectos secundarios.
4. Están acopladas a un framework (Laravel Rut y otras hierbas)
5. No proveen herramientas ni integraciones con librerías de terceros, como Doctrine.