ui-awesome/html-core

UI Awesome HTML Core for PHP.

0.4.0 2025-12-27 20:43 UTC

Requires

• php: ^8.1
• ui-awesome/html-helper: ^0.6

Requires (Dev)

• infection/infection: ^0.27|^0.32
• maglnet/composer-require-checker: ^4.1
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.1
• phpstan/phpstan-strict-rules: ^2.0.3
• phpunit/phpunit: ^10.5
• rector/rector: ^2.2
• symplify/easy-coding-standard: ^13.0

BSD-3-Clause

• php
• html
• core
• ui-awesome

README

Html core

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

Features

Installation

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

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\Core\Tag\{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\Core\Tag\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\Core\Tag\Voids;

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

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

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\Core\Tag\Block;

final class Div extends BaseBlock
{
    protected function getTag(): Block
    {
        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\Core\Tag\Block;

final class Div extends BaseBlock
{
    protected function getTag(): Block
    {
        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\Core\Tag\Inline;

final class Span extends BaseInline
{
    protected function getTag(): Inline
    {
        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\Core\Tag\Inline;

final class Span extends BaseInline
{
    protected function getTag(): Inline
    {
        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>

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) by implementing the core interfaces backed by a string Enum.

• \UIAwesome\Html\Core\Tag\BlockInterface: For container elements that have content and a closing tag.
• \UIAwesome\Html\Core\Tag\InlineInterface: For text-level elements.
• \UIAwesome\Html\Core\Tag\VoidInterface: For self-closing elements (no closing tag).

You can create a custom Enum for your specific domain (for example, SVG tags) and use it seamlessly with html-core.

use UIAwesome\Html\Core\Tag\BlockInterface;

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

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

Documentation

For detailed configuration options and advanced usage.

• Testing Guide

Package information

Quality code

Our social networks

License