Documentación de la Clase PHP `Html` 🛠️

La clase `Html` es un utilitario básico diseñado para la generación controlada de etiquetas HTML y para la visualización segura de código en la web. Permite construir elementos de dos tipos (etiquetas solas y pares con contenido) utilizando plantillas predefinidas.

---

1. Constantes de Definición

Estas constantes definen el modo de creación de la etiqueta en el método `crear()`.

Constante	Valor	Descripción
SOLA	'1'	Se utiliza para generar una etiqueta autocerrada (ej: <br>, <img>), que no tiene contenido ni etiqueta de cierre separada.
PAR	'2'	Se utiliza para indicar que se debe usar la plantilla de etiqueta con par (apertura y cierre).
TEXTO	'3'	Se utiliza internamente para indicar que el valor a insertar es el contenido (texto o HTML anidado) de una etiqueta de par.

---

2. Propiedad y Constructor

public function __construct(private array $base)

El constructor inicializa la propiedad privada $base, que contiene las plantillas básicas para generar HTML:

private array $base = [
    ["\n<","1",">\n"], // Plantilla para SOLA (<tag>)
    ["\n<","2",">\n"," ...LOGO ART... ","\n</","4",">\n"] // Plantilla para PAR (<tag> Contenido </tag>)
]
        

• La matriz `$base` almacena las estructuras base, donde los números ('1', '2', '4') son placeholders que serán reemplazados por el nombre de la etiqueta.
• El elemento $base[1][3] contiene un arte ASCII predefinido, que actúa como el contenido por defecto (o inicial) para las etiquetas de par.

---

3. Métodos Privados

Estos métodos manejan la manipulación interna de las plantillas en la propiedad $base.

private function modificar(string $ubicacion, string $insertar)

Reemplaza los *placeholders* en las plantillas según la ubicación:

• Case '1' (SOLA): Reemplaza el *placeholder* de la etiqueta simple (`$this->base[0][1]`).
• Case '2' (PAR): Reemplaza el *placeholder* de la etiqueta de apertura (`$this->base[1][1]`). Además, usa `explode(" ", $insertar)` para extraer la etiqueta base (ignorando atributos) y la usa para reemplazar el *placeholder* de la etiqueta de cierre (`$this->base[1][5]`). *Ej: Si se inserta 'div id="box"', la etiqueta de cierre será 'div'.*
• Case '3' (TEXTO): Reemplaza el contenido (`$this->base[1][3]`), eliminando el logo ASCII por defecto.

private function obtener(string $ubicacion)

Une y devuelve la cadena HTML de la plantilla modificada:

• Case '1' (SOLA): Retorna la cadena resultante de la plantilla simple (`$this->base[0]`).
• Case '2' (PAR): Retorna la cadena resultante de la plantilla de par (`$this->base[1]`).

---

4. Métodos Públicos

public function crear(string $etiqueta, string $contenido): string

Método principal para generar HTML. Recibe la etiqueta (con o sin atributos) y el contenido.

• Si `$contenido` es igual a `SOLA`:
  • Llama a `modificar(SOLA, $etiqueta)` para crear la etiqueta simple.
  • Retorna el resultado de `obtener(SOLA)`. *Ej: `<br>`*
• Si no es `SOLA`: (Etiqueta de Par)
  • Llama a `modificar(PAR, $etiqueta)` para configurar la apertura y cierre.
  • Llama a `modificar(TEXTO, $contenido)` para insertar el contenido.
  • Retorna el resultado de `obtener(PAR)`. *Ej: `<div>Contenido</div>`*

public function logo(): string

Devuelve el arte ASCII del logo que está preestablecido como contenido por defecto en la plantilla de par (`$this->base[1][3]`).

public function imprimir(string $x, string $path, bool $ejecutar_codgo = false): void

Controla cómo se muestra el resultado en la página web.

• Si `$ejecutar_codgo` es `true`:
  • Simplemente hace un echo $x. El HTML es renderizado por el navegador.
• Si `$ejecutar_codgo` es `false` (Modo Documentación/Código):
  • Usa htmlspecialchars($x) para escapar los caracteres HTML (convierte `<` en `<`) y nl2br() para preservar los saltos de línea. Esto hace que el código sea visible como texto, no como elementos renderizados.
  • Incluye un botón "copy txt" y vincula un archivo JavaScript (`copytxt.js`) usando la variable `$path`. Ideal para mostrar ejemplos de código seguro.

---

5. Fortalezas y Limitaciones

Puntos Fuertes 🟢

• Visualización Segura de Código: El método imprimir() con el modo `false` es excelente para documentación, ya que utiliza htmlspecialchars() para evitar que el código de ejemplo se ejecute.
• Generación Simple: Proporciona una interfaz limpia (`crear()`) para distinguir entre etiquetas solas y etiquetas de par.
• Reconocimiento Básico de Cierre: El método `modificar()` extrae inteligentemente la etiqueta base de una cadena con atributos para generar el cierre correcto (ej: de `'div class="x"'` a `</div>`).

Limitaciones 🔴

• Una Etiqueta a la Vez: La clase está diseñada para generar una sola etiqueta por instancia (debido a que los cambios se hacen sobre `$this->base`). Encadenar llamadas a `crear()` en una sola instancia sobrescribirá la plantilla base.
• Dependencia de Constantes: El uso de `SOLA`, `PAR`, y `TEXTO` (cadenas numéricas) hace que el código sea menos legible que si se hubieran usado nombres descriptivos o *enums* modernos.
• Control Limitado de Atributos: No hay un método explícito para gestionar atributos; se deben pasar directamente en la cadena de la etiqueta (`'div id="x"'`).

---

6. Ejemplo de Uso Detallado

El siguiente ejemplo muestra la creación de una etiqueta anidada, la visualización del código y la ejecución del HTML en la misma página.

Código PHP de Ejemplo

<?php

    // Asumimos que la clase Html está en la ubicación correcta.
    require_once "../Etiquetas/Html.php";

    $html = new Html; // Instancia 1: Para visualizar el código (imprimir=false)
    $html2 = new Html; // Instancia 2: Para ejecutar el código (imprimir=true)

    // Bloque 1: Visualiza el código generado (No lo ejecuta)
    $html -> imprimir (
        $html -> crear (
            'div id="logo"' , // Etiqueta externa (PAR)
            $html -> crear (
                'img src="../Archivos/Imagenes/logo.png" alt="logo"' ,
                SOLA // Etiqueta anidada (SOLA)
            )
        ) ,
        "../Archivos/Js" , // Ruta donde se encuentra 'copytxt.js'
        false // Muestra el código (escapado)
    );

    // Bloque 2: Ejecuta el código generado (Lo renderiza)
    $html2 -> imprimir (
        $html2 -> crear (
            'div' , 
            $html2 -> logo () // Usa el arte ASCII preestablecido
        ) ,
        "../Archivos/Js" ,
        true // Ejecuta el HTML (lo renderiza en el navegador)
    );

?>
        

Resultado del Bloque 1 (Visualización de Código)

<div id='contenedor-texto'>
<br />
<div id="logo">
<br />
<img src="../Archivos/Imagenes/logo.png" alt="logo">
<br />
</div>
</div>
<br><button id='boton-copiar'>copy txt</button><script src='../Archivos/Js/copytxt.js'></script>
        

*(Note que el código HTML se muestra como texto literal)*

Resultado del Bloque 2 (Ejecución de Código)

El navegador renderizaría lo siguiente, insertando el arte ASCII dentro de un `div`:

<div>
<pre>
███████   █████████   █████████
... (el resto del arte ASCII) ...
</pre>
</div>
        

*(El navegador mostraría un div conteniendo el arte ASCII renderizado)*