Download the PHP package irwinlopez1023/mex-core without Composer

MexCore

Librería PHP para la normalización y conversión de los 32 estados de la República Mexicana más Nacido en el Extranjero, procesamiento inteligente de nombres de personas mexicanas a partir de datos crudos del INE, y validación de CURP según el Instructivo Normativo de RENAPO.

API intuitiva con dos puntos de entrada: MexCore::Estado() y MexCore::Persona().

Requisitos

• PHP >= 8.0
• ext-mbstring

Instalación

MexCore::Estado()

Acepta identificadores de estado en cualquier formato y los convierte a cualquier otro formato.

Named constructors

Salida

Abreviatura contra código ISO

Son dos catálogos distintos y es importante no confundirlos.

toAbreviatura() devuelve la abreviatura de uso común, y tiene largo variable: de dos letras (BC, NL, QR) a cinco (TAMPS). Sólo 22 de las 33 entidades tienen tres.

toIso() devuelve el código ISO 3166-2:MX, siempre de tres letras: BCN, NLE, ROO, TAM, CMX. Es el que piden las APIs con un catálogo cerrado.

Las 16 entidades donde los dos difieren:

La norma ISO sólo cubre las 32 entidades federativas. Para Nacido en el Extranjero se devuelve NE, que es el código que ya usa la CURP.

El código ISO también sirve de entrada. fromIso() es estricto y sólo acepta el catálogo ISO; fromAbreviatura() y desde() aceptan las dos formas:

Fluent Interface

desde(): detección automática del formato

Cuando la columna de origen es mixta y una misma celda puede traer 24, 'SP', 'SLP' o 'San Luis Potosi', desde() detecta el formato y resuelve. intentarDesde() es la variante que devuelve null en lugar de lanzar, para no envolver cada renglón de una carga masiva en un try/catch.

El orden de resolución es número, CURP, abreviatura, nombre. BC, NL y QR son a la vez código de CURP y abreviatura, pero apuntan a la misma entidad en los dos catálogos, así que la precedencia no cambia el resultado.

Resiliencia

Las tres normalizaciones colapsan cualquier separador Unicode, incluido el espacio duro U+00A0 que llega al copiar de un PDF. Los nombres además pierden acentos, y las abreviaturas pierden puntos, espacios y guiones.

Una CURP no lleva espacios, así que en lugar de colapsarlos se eliminan todos: 'SOSR650222 MPLSNC03' vuelve a alinear sus posiciones 11 y 12 y resuelve Puebla. El mismo criterio rige en Curp y en PersonaQuery, de modo que una entrada que resuelve el estado también pasa Curp::esValida() y deriva correctamente.

fromNumero() en cambio es estricto: solo acepta dígitos. '24abc' y '24.9' lanzan InvalidStateException en vez de devolver San Luis Potosí en silencio.

Nombres oficiales

Los nombres constitucionales completos, que son los que trae el acta de nacimiento, resuelven igual que los cortos.

Value object

Listar todos los estados

Alias en inglés

La API principal está en español, igual que Persona. Los nombres en inglés siguen disponibles como alias delegados, así que el código existente no se rompe:

MexCore::Persona()

Procesa datos crudos (CURP, nombres, apellidos) y estructura los nombres aplicando la lógica de pegamento para nombres compuestos con conectores.

Named constructors

fromData() recibe los dos apellidos como parámetros posicionales contiguos, así que invertir paterno y materno no produce ningún error: solo datos incorrectos silenciosos. Para cargas masivas conviene fromArray(), que obliga a nombrar cada campo:

Salida

Formatos adicionales:

toNombres() devuelve los bloques de nombre tal como los detectó la lógica de pegamento, sin colapsarlos. Es la única forma de recuperar el tercer nombre y siguientes, porque toSegundoNombre() los junta en una sola cadena:

Lógica de pegamento (conectores)

En México los nombres de pila compuestos por preposiciones o artículos no deben separarse de forma tradicional. La librería usa un diccionario de conectores (DE, DEL, LA, LAS, LOS, Y, MAC, MC, VAN, VON) que se pegan hacia atrás y hacia adelante, agrupando el bloque completo.

Un segundo grupo de conectores cierra el bloque anterior y abre uno nuevo, en lugar de seguir absorbiendo palabras indefinidamente:

Si los datos vienen truncados y el bloque termina en un conector colgante, el conector se descarta antes que devolver un nombre que no existe:

Abreviaturas

Las abreviaturas típicas del INE (MA., J., GPE.) se tratan como pegamento, pero solo hacia adelante: nunca se pegan a la palabra anterior. Se reconocen por el punto final, por tener una sola letra, o por estar en el diccionario MA, M, J, GPE, FCO, FCA, ANT.

El último caso es el motivo de que las abreviaturas no peguen hacia atrás: JOSE MA. DEL CARMEN da el mismo resultado que JOSE MARIA DEL CARMEN.

El parámetro mantenerPunto decide si el punto sobrevive a la normalización. Solo aplica a los nombres, no a los apellidos:

separarNombres()

Aplica la lógica de pegamento a una cadena sin construir una Persona. Útil para inspeccionar la segmentación o para partir una cadena de apellidos completa:

Diccionarios configurables

withConectores() y withAbreviaturas() devuelven copias inmutables, así que se puede ajustar el comportamiento sin editar la librería ni contaminar la instancia compartida por MexCore::Persona():

combinar() y separar()

Cuando el origen trae dos nombres reales que se quieren tratar como uno, combinar() los fusiona. La operación es reversible, porque la Persona conserva internamente los bloques originales:

Datos derivados de la CURP

toEdad() acepta una fecha de referencia para que el resultado sea determinista en pruebas. toFechaNacimiento() deduce el siglo del homoclave (posición 17): dígito para nacidos antes del 2000, letra a partir del 2000. Devuelve null si la fecha no existe, por ejemplo un 050231.

Validación cruzada: coincideConCurp()

Las primeras cuatro letras de la CURP y las tres consonantes internas se derivan del primer apellido, el segundo apellido y el nombre. Eso permite confirmar que los campos capturados corresponden entre sí, y detectar registros con apellidos invertidos o mal transcritos:

Es una heurística, no una validación estricta. Puede dar falso negativo en casos exóticos (apellidos compuestos con guion, homonimias resueltas a mano por RENAPO) y no detecta la inversión cuando ambos apellidos son idénticos. Conviene usarla para marcar registros a revisar, no para rechazarlos.

Integración con Estado

Normalización de entrada

Toda la entrada pasa a mayúsculas y colapsa cualquier separador unicode a un espacio simple, incluido el espacio duro U+00A0 que llega al copiar texto de un PDF o de una credencial digitalizada. Los apellidos reciben el mismo tratamiento que los nombres, así que DE LA CRUZ no conserva los espacios dobles.

Curp

Las reglas del Instructivo Normativo de RENAPO viven en una clase estática aparte, para poder validar una cadena de 18 caracteres sin construir una Persona.

esValida() comprueba estructura, fecha real, entidad existente y dígito verificador. La derivación de letras también es pública:

Las tres reglas del instructivo están implementadas: se descartan las partículas del apellido (DE LA LUZ deriva de LUZ), se omite MARIA o JOSE cuando hay un nombre posterior (MARIA DEL ROCIO deriva de ROCIO, y MA. TERESA de TERESA), y si las cuatro primeras letras forman una de las 78 palabras inconvenientes la segunda se sustituye por X (ANA BACA CRUZ da BXCA).

Listado completo de estados

La clave es la del INEGI. El código de la CURP de la capital sigue siendo DF, aunque la entidad se llame Ciudad de México desde 2016. La columna ISO es ISO 3166-2:MX, sin el prefijo MX-.

Cuidado con las tres claves que empiezan con M: no siguen ningún patrón mnemotécnico y es fácil rotarlas. MC es México, MN es Michoacán y MS es Morelos.

Querétaro es QT en las CURP reales; varios catálogos públicos la listan como QO, que se acepta de entrada pero no es la que devuelve toCurp().

Excepciones

Todos los from*() y desde() lanzan InvalidStateException cuando el valor no resuelve.

Para procesar cargas masivas sin un try/catch por renglón, intentarDesde() devuelve null y existe() devuelve bool.

API completa

MexCore::Estado()

Alias en inglés: fromNumber(), fromAbbr(), fromName().

Estado (value object)

Estado implementa JsonSerializable, igual que Persona, así que json_encode() produce las mismas llaves que toArray(). Alias en inglés: toNumber(), toAbbr(), toName().

MexCore::Persona()

Persona (value object)

Persona implementa JsonSerializable, así que json_encode() produce las mismas llaves que toArray().

Curp (estática)

Pruebas

Las dos suites comparten el harness de tests/harness.php, así que se pueden correr por separado o juntas:

test_persona.php trae unas 145 aserciones sobre la lógica de pegamento, la normalización, los formatos de salida y la derivación de CURP, incluidas nueve CURP reales verificadas contra prefijo, consonantes internas y dígito verificador.

test_estados.php trae unas 290 sobre el catálogo completo (las 33 entidades resueltas por sus cinco identificadores, en ida y vuelta), los alias, los nombres oficiales, los códigos ISO, la resiliencia de entrada, la detección de CURP por forma y la congruencia del value object con Persona.

Cualquiera de los tres sale con código 1 si algo falla, así que sirven tal cual en CI.

Licencia

MIT License — Copyright (c) 2024 Irwin Lopez