README

Html Core

A type-safe PHP library for standards-compliant HTML tag rendering
Build and render block, inline, input, and void elements with immutable fluent APIs.

Features

Installation

composer require ui-awesome/html-core:^0.6

Quick start

Rendering HTML tags with enums

Renders begin/end tags and full elements using standards-compliant tag enums.

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Html;
use UIAwesome\Html\Interop\{Block, Inline, Voids};

echo Html::begin(Block::DIV, ['class' => 'container']);
// <div class="container">

echo Html::inline(Inline::SPAN, 'Hello');
// <span>Hello</span>

echo Html::end(Block::DIV);
// </div>

Rendering a full element (with optional content encoding)

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Html;
use UIAwesome\Html\Interop\Block;

$content = '<span>Test Content</span>';

echo Html::element(Block::DIV, $content, ['class' => 'test-class']);

// <div class="test-class">
// <span>Test Content</span>
// </div>

echo Html::element(Block::DIV, $content, ['class' => 'test-class'], true);

// <div class="test-class">
// &lt;span&gt;Test Content&lt;/span&gt;
// </div>

Rendering void elements with structured attributes

Void tags render without closing tags. Complex attributes (like class arrays and data arrays) are rendered via the installed ui-awesome/html-helper dependency.

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Html;
use UIAwesome\Html\Interop\Voids;

echo Html::void(
    Voids::IMG,
    [
        'class' => ['void'],
        'data' => ['role' => 'presentation'],
    ],
);

// <img class="void" data-role="presentation">

Input elements with prefix/suffix templates

Input elements render the input tag with optional prefix and suffix segments through the same template primitives used by inline elements.

<?php

declare(strict_types=1);

namespace App;

use BackedEnum;
use UIAwesome\Html\Core\Element\BaseInput;
use UIAwesome\Html\Interop\{Inline, Voids};

final class SearchInput extends BaseInput
{
    protected function getTag(): BackedEnum
    {
        return Voids::INPUT;
    }

    protected function run(): string
    {
        return $this->buildElement();
    }
}

echo SearchInput::tag()
    ->type('search')
    ->name('q')
    ->prefix('Search')
    ->prefixTag(Inline::LABEL)
    ->render();

// <label>Search</label>
// <input name="q" type="search">

Building custom elements with immutable fluent APIs

Create your own element classes by extending the provided base elements.

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Element\BaseBlock;
use UIAwesome\Html\Interop\Block;
use BackedEnum;

final class Div extends BaseBlock
{
    protected function getTag(): BackedEnum
    {
        return Block::DIV;
    }
}

echo Div::tag()
    ->class('card')
    ->content('Content')
    ->render();

// <div class="card">
// Content
// </div>

Nested rendering with begin() / end()

BaseBlock supports stack-based begin/end rendering, with protection against mismatched tags.

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Element\BaseBlock;
use UIAwesome\Html\Interop\Block;
use BackedEnum;

final class Div extends BaseBlock
{
    protected function getTag(): BackedEnum
    {
        return Block::DIV;
    }
}

echo Div::tag()->begin();
echo 'Nested Content';
echo Div::end();

// <div>
// Nested Content
// </div>

Inline elements with prefix/suffix and templates

Inline elements can render prefix and suffix segments, optionally wrapped in their own tags.

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Element\BaseInline;
use UIAwesome\Html\Interop\Inline;
use BackedEnum;

final class Span extends BaseInline
{
    protected function getTag(): BackedEnum
    {
        return Inline::SPAN;
    }

    protected function run(): string
    {
        return $this->buildElement($this->getContent());
    }
}

echo Span::tag()
    ->content('Content')
    ->prefix('Prefix')
    ->prefixTag(Inline::STRONG)
    ->suffix('Suffix')
    ->suffixTag(Inline::EM)
    ->render();

// <strong>Prefix</strong>
// <span>Content</span>
// <em>Suffix</em>

Defaults and theming via providers

You can apply configuration through global defaults, per-instance defaults, and optional default/theme providers.

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Base\BaseTag;
use UIAwesome\Html\Core\Element\BaseInline;
use UIAwesome\Html\Core\Factory\SimpleFactory;
use UIAwesome\Html\Core\Provider\{DefaultsProviderInterface, ThemeProviderInterface};
use UIAwesome\Html\Interop\Inline;
use BackedEnum;

final class Span extends BaseInline
{
    protected function getTag(): BackedEnum
    {
        return Inline::SPAN;
    }

    protected function run(): string
    {
        return $this->buildElement($this->getContent());
    }
}

final class Defaults implements DefaultsProviderInterface
{
    public function getDefaults(BaseTag $tag): array
    {
        return ['class' => 'badge'];
    }
}

final class Theme implements ThemeProviderInterface
{
    public function apply(BaseTag $tag, string $theme): array
    {
        return $theme === 'muted' ? ['class' => 'text-muted'] : [];
    }
}

SimpleFactory::setDefaults(Span::class, ['title' => 'from-global']);

echo Span::tag(['id' => 'badge-1'])
    ->addDefaultProvider(Defaults::class)
    ->addThemeProvider('muted', Theme::class)
    ->content('New')
    ->render();

// <span class="badge text-muted" id="badge-1" title="from-global">New</span>

Class-level defaults with loadDefault()

For a simpler approach without separate provider classes, override loadDefault() in your tag class. These defaults are applied automatically when tag() is called.

<?php

declare(strict_types=1);

namespace App;

use UIAwesome\Html\Core\Element\BaseBlock;
use UIAwesome\Html\Interop\Block;
use BackedEnum;

final class Container extends BaseBlock
{
    protected function getTag(): BackedEnum
    {
        return Block::DIV;
    }

    protected function loadDefault(): array
    {
        return [
            'class' => 'container',
        ];
    }
}

echo Container::tag()->render();
// <div class="container">
// </div>

echo Container::tag(['class' => 'container-fluid'])->render();
// <div class="container container-fluid">
// </div>

Configuration priority (from weakest to strongest):

1. Global defaults via SimpleFactory::setDefaults()
2. Class defaults from loadDefault()
3. User defaults passed to tag()

Extensibility

This library is agnostic and designed to be extended. You can define your own tag collections (for example, for SVG, MathML, or Web Components) with custom string-backed enums.

• Html::element() handles generic open/content/close rendering.
• Html::inline() handles inline rendering.
• Html::void() handles void rendering.

You can create a custom enum for your specific domain and use it with html-core.

enum SvgTag: string
{
    case SVG = 'svg';
    case G = 'g';
    // ... add other SVG block tags as needed
}

// now you can use it with the Html renderer or your custom classes
echo Html::element(SvgTag::G, '...');
// <g>...</g>

Documentation

For detailed configuration options and advanced usage.

• 🧪 Testing Guide
• ⬆️ Upgrade Guide

Package information

Quality code

Our social networks

License