Hypertool

Class: Hypertool\Html\HtmlElement

1. Overview

The HtmlElement class is the core component of the hypertool/html library. Its primary purpose is to provide a flexible and fluent interface for programmatically generating HTML elements in PHP. It serves as the base class for all specific HTML element classes (like Div, Button, etc.) and also provides static factory methods for creating any HTML element. It supports setting standard HTML attributes, managing child elements, adding text content, and includes dedicated methods for integrating with HTMX and Hyperscript attributes.

Within the Hypertool HTML Generator project, HtmlElement is the foundation upon which all HTML structures are built.

2. API Reference

Constructor

__construct(string $tagName)

Public Methods

(Note: This is not exhaustive for all attribute setters, but covers key methods and categories.)

output(): string

text(string $content): self

add_child(?string $identifier, string|HtmlElement $tagNameOrElement): HtmlElement

setClass(string $class): self

setId(string $id): self

Attribute Setters (setAttribute, setStyle, setSrc, setHref, etc.)

HTMX Setters (setHxGet, setHxPost, setHxTrigger, setHxSwap, setHxTarget, setHxOn, etc.)

Hyperscript Setter (setHyperscript)

Static Factory Methods (HtmlElement::div(), HtmlElement::button(), etc.)

Public Attributes/Properties

All functional properties are managed internally and accessed/modified via public methods. There are no public attributes intended for direct manipulation.

3. Usage Examples

(Assumes Composer autoloader is included and use Hypertool\Html\HtmlElement;)

Example 1: Basic Form Input

<?php
require_once __DIR__ . '/../vendor/autoload.php';
use Hypertool\Html\HtmlElement;

$label = HtmlElement::label('Username')->setFor('username-input');
$input = HtmlElement::input()
    ->setType('text')
    ->setId('username-input')
    ->setName('username')
    ->setPlaceholder('Enter your username')
    ->setClass('form-control'); // Example Bootstrap class

echo $label->output();
echo $input->output();
?>
// Expected Output:
// <label for="username-input">Username</label>
// <input type="text" id="username-input" name="username" placeholder="Enter your username" class="form-control">

Example 2: Nested Structure with Children

<?php
require_once __DIR__ . '/../vendor/autoload.php';
use Hypertool\Html\HtmlElement;

$list = HtmlElement::ul()->setClass('list-group'); // Create a <ul>

$item1 = HtmlElement::li('First item')->setClass('list-group-item');
$item2 = HtmlElement::li('Second item')->setClass('list-group-item active'); // Add 'active' class
$item3 = HtmlElement::li()->setClass('list-group-item'); // Empty item
$link = HtmlElement::a('Click me')->setHref('#');
$item3->add_child('link', $link); // Add link to the third item

$list->add_child('i1', $item1)
     ->add_child('i2', $item2)
     ->add_child('i3', $item3);

echo $list->output();
?>
// Expected Output:
// <ul class="list-group">
//   <li class="list-group-item">First item</li>
//   <li class="list-group-item active">Second item</li>
//   <li class="list-group-item"><a href="#">Click me</a></li>
// </ul>

Example 3: HTMX Partial Loading with Hyperscript Interaction

<?php
require_once __DIR__ . '/../vendor/autoload.php';
use Hypertool\Html\HtmlElement;

$loadButton = HtmlElement::button('Load Content')
    ->setClass('btn btn-secondary')
    ->setHxGet('/content-partial')
    ->setHxTarget('#content-area')
    ->setHxSwap('innerHTML')
    ->setHyperscript('on click add @disabled then add .opacity-50 until htmx:afterRequest then remove @disabled remove .opacity-50');

$contentArea = HtmlElement::div()->setId('content-area');

echo $loadButton->output();
echo $contentArea->output();
?>
// Expected Output:
// <button class="btn btn-secondary" hx-get="/content-partial" hx-target="#content-area" hx-swap="innerHTML" _="on click add @disabled then add .opacity-50 until htmx:afterRequest then remove @disabled remove .opacity-50">Load Content</button>
// <div id="content-area"></div>

4. Detailed Use Cases/Scenarios

  1. Building Standard HTML Pages: Use the library to generate common HTML structures like headers, footers, navigation, content sections, lists, and tables programmatically, often within a PHP templating system or framework.
  2. Creating Reusable UI Components: Encapsulate complex HTML structures (like cards, modals, form groups) into custom PHP classes that extend HtmlElement, applying consistent styling (e.g., Bootstrap/Tailwind classes) and behavior.
  3. Developing HTMX-powered Interfaces: Easily add HTMX attributes (hx-get, hx-target, hx-trigger, etc.) to elements to create dynamic, AJAX-driven user interfaces without writing complex JavaScript.
  4. Integrating Hyperscript for Client-Side Behavior: Add simple, inline client-side interactivity using the _ attribute via the setHyperscript method, often in conjunction with HTMX events.

5. Dependencies

6. Error Handling & Exceptions

7. Configuration

8. Best Practices & Pitfalls