piecesphp / html

v3.0.0 2026-08-28 21:08 UTC

Requires

• php: >=8.5 <8.6
• piecesphp/datastructures: ^4.0

Requires (Dev)

• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpunit/phpunit: ^10.5
• rector/rector: ^2.3

MIT

• Vicsen Morantes

• generator
• html

Published on Packagist.org on 2026-08-28 21:29 UTC

README

Genera HTML desde PHP con objetos: elementos con atributos e hijos, campos de formulario, tablas, y un formateador que indenta el resultado.

Es parte del framework PiecesPHP, pero no depende de él.

⚠ Seguridad: no escapa nada

Ni el texto ni los atributos se escapan, ni por defecto ni como opción. Lo que pases sale tal cual en el HTML. Un valor que venga del usuario debes escaparlo tú antes de pasarlo:

$seguro = htmlspecialchars($valorDelUsuario, ENT_QUOTES, 'UTF-8');

Requisitos

• PHP >=8.5 <8.6, con mbstring.
• piecesphp/datastructures ^4.0 (se instala solo).

Instalación

composer require piecesphp/html

Qué trae

Todo bajo PiecesPHP\Core\HTML:

Clase	Qué es
HtmlElement	Un elemento cualquiera: etiqueta, texto, hijos y atributos
Attribute	Un atributo con uno o varios valores
Form, Input, Select, Button	Formularios y sus campos
Table	Una tabla a partir de nombres de columna y filas
FormatHtml	Indenta y embellece una cadena HTML
Collections\AttributeArray, ElementArray, FormElementArray, HtmlElementArray	Colecciones tipadas
Interfaces\Element, Interfaces\FormElement	Los contratos
Exceptions\MalformedAttributeException, MalformedChildException	Atributo o hijo inválido

Uso

Un elemento con atributos e hijos

use PiecesPHP\Core\HTML\HtmlElement;

$enlace = new HtmlElement('a', 'Ver más', null, ['href' => '/articulos', 'class' => 'btn primario']);
$enlace->getAttributeInstance('class')->appendValue('grande');

$caja = HtmlElement::create('div', '', [$enlace]);

echo $caja; // o: $html = $caja->render(false);

• render() sin argumento hace echo además de devolver la cadena. Para solo obtenerla: render(false) o (string) $elemento.
• La salida pasa siempre por FormatHtml::format(), que la indenta.

Un elemento sin cierre

$salto = new HtmlElement('br', '', null, null, false); // <br>

Atributos

$caja->setAttribute('data-id', '15');
$enlace->getAttribute('class');          // "btn primario grande", como cadena
$enlace->getAttribute('class', false);   // ['btn', 'primario', 'grande'], como lista
$caja->getAttribute('class');            // null: la caja no tiene clase
$caja->removeAttribute('data-id');

Un valor escalar se parte por el separador (un espacio por defecto): 'btn primario' son dos valores.

Formularios

use PiecesPHP\Core\HTML\Form;

$form = new Form('POST', '/guardar');
$form->appendFieldSemantic(Form::text('nombre', null, 'Tu nombre'), 'Nombre', true);
$form->appendFieldSemantic(Form::email('correo'), 'Correo');
echo $form->render(false);

Fábricas estáticas de Form: label(), submit(), text(), hidden(), email(), password() y select().

Formatear HTML existente

use PiecesPHP\Core\HTML\FormatHtml;

echo FormatHtml::format('<div><p>Hola</p></div>');

Referencia de HtmlElement

Método	Qué hace
__construct(string $tag, string $text = '', $childs = null, $attributes = null, bool $doubleTag = true)	$childs: un elemento, un array de elementos o una colección. $attributes: ['nombre' => valor], un Attribute o un AttributeArray
static create(...)	Lo mismo, como fábrica
appendChild(Element $child)	Añade un hijo. Devuelve $this
innerHTML(?Element $html = null)	Sin argumento, el texto y los hijos renderizados; con uno, sustituye los hijos
clearChilds()	Quita los hijos
setAttribute(string $name, $value = null, ?string $separator = null)	Devuelve $this
getAttribute(string $name, bool $outputAsString = true)	Cadena, lista o null
getAttributeInstance(string $name) / removeAttribute(string $name) / getAttributes(bool $outputAsString = true)
render($echo = true): string	Ver arriba

• Un hijo de un tipo no admitido lanza MalformedChildException.
• $attributes de un tipo no admitido en el constructor se ignora en silencio: 'x', 5, un objeto cualquiera o una lista sin claves (['a', 'b']) dan un elemento sin atributos, sin error.
• setAttribute() con un valor que no es escalar, array ni null (por ejemplo, un objeto) lanza MalformedAttributeException. Dentro de un array, los valores no escalares se descartan en silencio.

Demo y pruebas

• demo/index.php: un ejemplo mínimo con un enlace.
• tests/FormatHtmlTest.php: 7 pruebas del formateador. No hay pruebas de HtmlElement, Attribute ni los formularios.

composer install
php examples/readme.php            # ejecuta los ejemplos de este README; sale con 1 si alguno no da lo que dice
vendor/bin/phpunit

Cambios

Ver CHANGELOG.md.

Licencia

MIT. Ver LICENSE.