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.
composer require ui-awesome/html-core:^0.5Renders 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><?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">
// <span>Test Content</span>
// </div>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">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, BlockInterface};
final class Div extends BaseBlock
{
protected function getTag(): BlockInterface
{
return Block::DIV;
}
}
echo Div::tag()
->class('card')
->content('Content')
->render();
// <div class="card">
// Content
// </div>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, BlockInterface};
final class Div extends BaseBlock
{
protected function getTag(): BlockInterface
{
return Block::DIV;
}
}
echo Div::tag()->begin();
echo 'Nested Content';
echo Div::end();
// <div>
// Nested Content
// </div>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, InlineInterface};
final class Span extends BaseInline
{
protected function getTag(): InlineInterface
{
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>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, InlineInterface};
final class Span extends BaseInline
{
protected function getTag(): InlineInterface
{
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>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, BlockInterface};
final class Container extends BaseBlock
{
protected function getTag(): BlockInterface
{
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-fluid"></div>Configuration priority (from weakest to strongest):
- Global defaults via
SimpleFactory::setDefaults() - Class defaults from
loadDefault() - User defaults passed to
tag()
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\Interop\BlockInterface: For container elements that have content and a closing tag.\UIAwesome\Html\Interop\InlineInterface: For text-level elements.\UIAwesome\Html\Interop\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\Interop\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>For detailed configuration options and advanced usage.
