kuasarx / separador-silabas-rae
Implementación en PHP de las reglas de división silábica del español según la RAE, con manejo de variantes y estrategias de prefijos.
Requires
- php: >=7.4 || ^8.0
- ext-mbstring: *
Requires (Dev)
- phpunit/phpunit: ^9.5
This package is auto-updated.
Last update: 2025-03-26 20:23:46 UTC
README
SeparadorSilabasRAE es una librería PHP diseñada para dividir palabras del idioma español en sus sílabas constituyentes, siguiendo estrictamente las reglas oficiales publicadas por la Real Academia Española (RAE) en su Ortografía de 2010.
Características Principales:
- ✅ Cumplimiento RAE: Implementa las reglas fundamentales de división silábica, incluyendo:
- Consonantes entre vocales (
ca-sa
). - Grupos consonánticos inseparables (
bl
,pr
,fl
... ->ha-blar
). - Grupos consonánticos separables (
st
,ct
,gn
... ->cos-ta
). - Secuencias de 3 y 4 consonantes (
ins-pi-rar
,abs-trac-to
).
- Consonantes entre vocales (
- 🗣️ Fonética Avanzada:
- Diptongos: Reconoce y mantiene unidos los diptongos (
ciu-dad
,pei-ne
,vein-tiún
). - Triptongos: Reconoce y mantiene unidos los triptongos (
lim-piáis
,U-ru-guay
). - Hiatos: Separa correctamente los hiatos, tanto por vocales fuertes como por débiles acentuadas y vocales idénticas (
le-er
,pa-ís
,chi-i-ta
,Ra-úl
). Opción para no separar hiatos (uso no estándar). - Letra H: Maneja la 'h' intercalada correctamente, tanto en diptongos/hiatos (
ahu-mar
,pro-hí-be
) como entre consonantes (des-ha-cer
,in-há-bil
,su-per-hom-bre
). - Letra Y: Trata la 'y' final como vocal 'i' (
rey
,ley
). - Dígrafos: Considera
ch
,ll
,rr
como unidades inseparables (co-che
,ca-lle
,pe-rro
). - Grupos
qu
/gu
: Manejaque
/qui
ygue
/gui
fonéticamente. - Letra X: Gestiona la
x
intervocálica (e-xa-men
) y en otras posiciones (ex-tra-ño
).
- Diptongos: Reconoce y mantiene unidos los diptongos (
- 🌎 Variantes Regionales: Soporte inicial para variantes dialectales como el grupo
tl
:es_ES
(España, default):at-le-ta
es_MX
(México y zonas de América):a-tle-ta
- 🧩 Estrategias de Prefijos: Ofrece flexibilidad al dividir palabras con prefijos:
fonetica
(default): Prioriza la división fonética estándar (su-bra-yar
,in-há-bil
,e-xa-lum-no
).morfologica
: Intenta separar el prefijo del resto de la palabra (sub-ra-yar
,in-há-bil
,ex-a-lum-no
).adaptativa
: Usa heurísticas para decidir entre fonética y morfológica según el contexto (su-bra-yar
vssub-lu-nar
).
- ⚡ Optimización: Incluye una caché LRU (Least Recently Used) interna para acelerar la separación de palabras frecuentes.
- 🐛 Depuración: Ofrece un modo de rastreo opcional (
enableTracing()
) para visualizar el proceso lógico paso a paso. - 📦 Instalación Fácil: Disponible vía Composer.
- ✨ Código Moderno: Escrito en PHP moderno con tipado estricto (
declare(strict_types=1)
).
Instalación
La forma recomendada de instalar la librería es a través de Composer:
composer require kuasarx/separador-silabas-rae
Asegúrate de tener la extensión mbstring
de PHP habilitada, ya que es necesaria para el manejo correcto de caracteres multibyte.
Uso Básico
<?php require 'vendor/autoload.php'; // Si usas Composer use Kuasarx\Linguistica\SeparadorSilabasRAE; use Kuasarx\Linguistica\InvalidWordException; $separador = new SeparadorSilabasRAE(); try { // --- Ejemplo Simple --- $palabra = "constitucionalidad"; $resultado = $separador->separar($palabra); echo "Palabra: " . $palabra . "\n"; echo "Sílabas: " . implode('-', $resultado['silabas']) . "\n"; // Salida: Sílabas: cons-ti-tu-cio-na-li-dad // --- Ejemplo con Hiato --- $palabraHiato = "aéreo"; $resultadoHiato = $separador->separar($palabraHiato); echo "\nPalabra: " . $palabraHiato . "\n"; echo "Sílabas: " . implode('-', $resultadoHiato['silabas']) . "\n"; // Salida: Sílabas: a-é-re-o // --- Ejemplo con H --- $palabraH = "deshacer"; $resultadoH = $separador->separar($palabraH); echo "\nPalabra: " . $palabraH . "\n"; echo "Sílabas: " . implode('-', $resultadoH['silabas']) . "\n"; // Salida: Sílabas: des-ha-cer // --- Variante Regional (México) --- $palabraTL = "atleta"; $resultadoTL_MX = $separador->separar($palabraTL, true, 'es_MX'); echo "\nPalabra: " . $palabraTL . " (Región MX)\n"; echo "Sílabas: " . implode('-', $resultadoTL_MX['silabas']) . "\n"; // Salida: Sílabas: a-tle-ta // --- Estrategia Morfológica --- $palabraPrefijo = "subrayar"; $resultadoPrefijoMorf = $separador->separar($palabraPrefijo, true, 'es_ES', 'morfologica'); echo "\nPalabra: " . $palabraPrefijo . " (Estrategia Morfológica)\n"; echo "Sílabas: " . implode('-', $resultadoPrefijoMorf['silabas']) . "\n"; // Salida: Sílabas: sub-ra-yar // --- Estrategia Adaptativa --- $palabraPrefijoAdapt = "sublunar"; $resultadoPrefijoAdapt = $separador->separar($palabraPrefijoAdapt, true, 'es_ES', 'adaptativa'); echo "\nPalabra: " . $palabraPrefijoAdapt . " (Estrategia Adaptativa)\n"; echo "Sílabas: " . implode('-', $resultadoPrefijoAdapt['silabas']) . "\n"; // Salida: Sílabas: sub-lu-nar // --- Ignorar Hiatos --- $palabraPais = "país"; $resultadoPaisNoHiato = $separador->separar($palabraPais, false); // hiatos = false echo "\nPalabra: " . $palabraPais . " (Sin Hiatos)\n"; echo "Sílabas: " . implode('-', $resultadoPaisNoHiato['silabas']) . "\n"; // Salida: Sílabas: pais // --- Generar HTML --- $resultadoHTML = $separador->separar("programación"); echo "\nHTML para 'programación':\n"; echo $separador->generarHtml($resultadoHTML['silabas']) . "\n"; // Salida: <span class="silaba">pro</span><span class="silaba">gra</span><span class="silaba">ma</span><span class="silaba">ción</span> } catch (InvalidWordException $e) { echo "Error: " . $e->getMessage() . "\n"; } ?>
Documentación de la Clase
SeparadorSilabasRAE
Métodos Públicos
__construct()
: Constructor (no requiere parámetros).separar(string $palabra, bool $incluirHiatos = true, string $regionalismo = 'es_ES', string $estrategiaPrefijos = 'fonetica'): array
:- Método principal para realizar la separación.
- Parámetros:
$palabra
(string): La palabra a separar.$incluirHiatos
(bool, opcional, default:true
): Sitrue
, separa los hiatos; sifalse
, los trata como diptongos.$regionalismo
(string, opcional, default:'es_ES'
): Código regional ('es_ES'
o'es_MX'
) para variantes comotl
.$estrategiaPrefijos
(string, opcional, default:'fonetica'
): Estrategia para prefijos ('fonetica'
,'morfologica'
,'adaptativa'
).
- Retorna: Un array asociativo con:
silabas
(array): Las sílabas resultantes.puntos_division
(array): Índices donde se puede dividir con guion.excepciones_aplicadas
(array): Log de reglas especiales usadas.tiempo_ms
(float): Tiempo de ejecución en milisegundos.fuente
(string):'cache'
o'calculado'
.trace
(array, opcional): Log de rastreo si está habilitado.
- Lanza:
InvalidWordException
si la palabra es inválida.
generarHtml(array $silabas): string
:- Convierte un array de sílabas en una cadena HTML con
<span class="silaba">
. - Parámetro:
$silabas
(array): El array de sílabas. - Retorna: (string) La cadena HTML.
- Convierte un array de sílabas en una cadena HTML con
enableTracing(bool $enable = true): void
:- Habilita (
true
) o deshabilita (false
) el log de rastreo detallado. Útil para depuración.
- Habilita (
static limpiarCache(): void
:- Vacía la caché interna de resultados.
static getCacheSize(): int
:- Retorna el número actual de elementos almacenados en la caché.
Excepciones
InvalidWordException
: Se lanza si la palabra proporcionada aseparar()
está vacía o contiene caracteres no permitidos (diferentes a letras del alfabeto español, incluyendo ñ, ü y tildes).
Detalles de Implementación y Reglas RAE
La clase implementa las reglas descritas en la Ortografía de la RAE (2010), § 4.1.1.1.1.2:
- Núcleo Vocálico: Identifica diptongos (incl.
iú
,uí
), triptongos e hiatos (incl.F+F
,F+Da
,Da+F
,Da+Da
,VV idénticas
). - Combinaciones Consonánticas:
- V C V:
V.CV
(ca-sa) - V CC V:
- Grupo inseparable (pr, bl...):
V.CCV
(a-brir) - Grupo
tl
:Vt.lV
(at-las) enes_ES
,V.tlV
(a-tlas) enes_MX
. - Otros:
VC.CV
(ac-to, ap-to, cons-ta, des-ha-cer)
- Grupo inseparable (pr, bl...):
- V CCC V:
- Si últimas dos son inseparables:
VC.CCV
(des-pre-cio) - Otros:
VCC.CV
(ins-tan-te, pers-pi-caz)
- Si últimas dos son inseparables:
- V CCCC V:
VCC.CCV
(abs-trac-to, cons-tre-ñir)
- V C V:
- Letra H:
- No impide diptongos/hiatos (ahu-mar, pro-hí-be, a-ho-ra).
- Si está entre consonante y vocal, va con la vocal siguiente (des-ha-cer, in-há-bil, su-per-hom-bre).
- Letra X:
- Entre vocales:
V.xV
(e-xa-men). - Inicio de palabra:
X=V
(xe-no-fo-bia). - Fin de sílaba:
VC.CV
(ex-tra-ño).
- Entre vocales:
- Prefijos: Las estrategias
morfologica
yadaptativa
intentan respetar los límites morfológicos basándose en una lista de prefijos comunes y heurísticas sobre las consonantes/vocales en el punto de unión y la fuerza de los grupos consonánticos formados.
Pruebas
La librería incluye un extenso conjunto de pruebas unitarias utilizando PHPUnit. Puedes ejecutarlas con:
composer test
O para ver la cobertura de código:
composer test-coverage
(Esto generará un informe en el directorio coverage/
).
Contribuciones
Las contribuciones son bienvenidas. Por favor, si encuentras un error o tienes una sugerencia:
- Verifica si ya existe un issue similar.
- Si no, crea un nuevo issue detallando el problema o la propuesta.
- Para pull requests, asegúrate de que las pruebas unitarias sigan pasando y, si es posible, añade nuevas pruebas para cubrir tu cambio.
Licencia
Este proyecto está bajo la Licencia MIT.
Creado por Juan Camacho (kuasarx@gmail.com)