# HTML

> A fluent, immutable PHP library for generating HTML elements with typed attribute helpers.

Package entry: `ui-awesome/html`. Requires PHP `^8.3`. Checked 2026-10-25. [View the entry in the package directory](</docs/packages/ui-awesome/html/index.md>)

**A fluent, immutable PHP library for generating HTML elements with typed attribute helpers.**

_Safe by default content encoding, raw HTML when needed, and standards-compliant rendering._

## Features

![Feature Overview](https://raw.githubusercontent.com/ui-awesome/html/main/docs/svgs/features.svg)

### Installation

```bash
composer require ui-awesome/html:^0.7
```

### Quick start

This package provides immutable, fluent wrapper classes for common HTML elements.

It supports safe content encoding via `content()`, raw HTML via `html()`, and composition using element instances.

#### Document skeleton + composition + immutability

```php
use UIAwesome\Html\Flow\{Div, Main, P};
use UIAwesome\Html\Heading\H1;
use UIAwesome\Html\Metadata\{Link, Meta, Title};
use UIAwesome\Html\Palpable\A;
use UIAwesome\Html\Root\{Body, Head, Html};

$baseLink = A::tag()->class('nav-link');

echo Html::tag()
    ->lang('en')
    ->html(
        Head::tag()->html(
            Meta::tag()->charset('utf-8'),
            Meta::tag()->name('viewport')->content('width=device-width, initial-scale=1'),
            Title::tag()->content('UI Awesome HTML'),
            Link::tag()->rel('stylesheet')->href('/assets/app.css'),
        ),
        Body::tag()->class('app')->html(
            Main::tag()->class('container')->html(
                H1::tag()->content('UI Awesome HTML'),
                P::tag()->content('Build HTML with a fluent, immutable API.'),
                Div::tag()->class('nav')->html(
                    $baseLink->href('/docs')->content('Documentation'),
                    $baseLink->href('/github')->content('GitHub'),
                ),
            ),
        ),
    )
    ->render();
```

#### Safe content vs raw HTML

```php
use UIAwesome\Html\Flow\Div;

echo Div::tag()->content('<strong>encoded</strong>')->render();
// <div>
// &lt;strong&gt;encoded&lt;/strong&gt;
// </div>

echo Div::tag()->html('<strong>raw</strong>')->render();
// <div>
// <strong>raw</strong>
// </div>
```

#### Powerful list composition

Create ordered lists, unordered lists, and description lists with a fluent API.

```php
use UIAwesome\Html\List\{Dl, Ol, Ul};

// Unordered list with items
$features = Ul::tag()
    ->class('feature-list')
    ->items(
        'Immutable by design',
        'Type-safe attributes',
        'Fluent API',
        'Standards-compliant',
    );

// Ordered list with custom start and nested items
$steps = Ol::tag()
    ->class('steps')
    ->start(1)
    ->reversed(false)
    ->li('Install with Composer', 1)
    ->li('Create HTML elements', 2)
    ->li('Render to string', 3);

// Description list for metadata or glossaries
$metadata = Dl::tag()
    ->class('metadata-list')
    ->dt('Package')
    ->dd('ui-awesome/html')
    ->dt('Version')
    ->dd('0.4.0')
    ->dt('License')
    ->dd('BSD-3-Clause');

// Render all lists
$html = $features->render() . PHP_EOL . $steps->render() . PHP_EOL . $metadata->render();
```

#### Typed form choices

Build selects and choice lists from typed objects. Selection state stays on the composite control while each option
keeps its own submitted value.

```php
use UIAwesome\Html\Form\{CheckboxList, ChoiceItem, Option, Select};

$pet = Select::tag()
    ->name('pet')
    ->options(
        Option::tag()->value('dog')->content('Dog'),
        Option::tag()->value('cat')->content('Cat'),
    )
    ->value('cat');

$channels = CheckboxList::tag()
    ->id('channels')
    ->name('channels')
    ->items(
        ChoiceItem::tag()->value('email')->label('Email'),
        ChoiceItem::tag()->value('sms')->label('SMS'),
    )
    ->checked(['email']);

// Render both controls
$html = $pet->render() . PHP_EOL . $channels->render();
```

## Enum content

Pass enum cases directly to any block or inline tag's `content()` method:

```php
use UIAwesome\Html\Flow\P;

enum ContentMessage: string
{
    case GUIDANCE = 'Capture <events> & inspect them.';
}

echo P::tag()->content(ContentMessage::GUIDANCE)->render();
```

The enum value is HTML-encoded, not inserted as raw markup. Integer-backed enums preserve zero, and pure enums
use their name. Multiple arguments and chained calls append content in order without mutating the original tag.
`html()` remains the explicit API for trusted raw HTML. See [UPGRADE.md](https://github.com/ui-awesome/html/blob/main/UPGRADE.md) before upgrading custom
implementations or overrides of `content()`.

## Documentation

For detailed testing and quality workflows.

- [Testing Guide](https://github.com/ui-awesome/html/blob/main/docs/testing.md)

## AI assistance

AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version
of a page by appending `index.md` to its URL. The
[AI agents guide](https://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill
installation, client setup and verification.

- 🤖 [`ui-awesome-html` skill](https://github.com/ui-awesome/html/blob/main/docs/agents.md): typed element
  composition, content encoding versus trusted raw HTML, immutable setters and form-control rendering contracts.

See the [repository guides](#documentation), the [skill source](https://github.com/ui-awesome/html/blob/main/skills/ui-awesome-html/SKILL.md), the source PHPDoc and
the [changelog](https://github.com/ui-awesome/html/blob/main/CHANGELOG.md).

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)

## License

[License](https://github.com/ui-awesome/html/blob/main/LICENSE)

## Package

- Source code and issues: [ui-awesome/html](https://github.com/ui-awesome/html). Star the repository if the package is useful to you.
- Composer package: [ui-awesome/html](https://packagist.org/packages/ui-awesome/html).
- Changelog: [CHANGELOG.md](https://github.com/ui-awesome/html/blob/main/CHANGELOG.md).