Html

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

Installation

composer require ui-awesome/html:^0.6

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

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

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.

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.

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:

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 before upgrading custom implementations or overrides of content().

Documentation

For detailed testing and quality workflows.

• Testing Guide

Package information

Project status

Our social networks

License