# 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)*