A powerful PHP library to simplify HTML element creation
Generate attributes, encode content, sanitize HTML, and manage CSS classes with ease.
composer require ui-awesome/html-helper:^0.5Ensures attribute keys have the correct prefix (like aria-, data-, or on), supporting strings, Enums, and
Stringables.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\AttributeBag;
// normalize string key (adds prefix if missing)
echo AttributeBag::normalizeKey('label', 'aria-');
// aria-label
// normalize Enum key
echo AttributeBag::normalizeKey(Data::ACTION, 'data-');
// data-action
// normalize event (flexible prefixing)
echo AttributeBag::normalizeKey('click', 'on');
// onclickUse AttributeBag to query and mutate an attribute array in-place with a minimal API (get(), merge(),
remove(), set(), setMany()).
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\AttributeBag;
$attributes = ['id' => 'submit'];
// merge arrays (later values override; merge is raw — no key normalization or `null` filtering)
AttributeBag::merge(
$attributes,
[
'class' => ['btn', 'btn-primary'],
'type' => 'submit',
],
);
// get with fallback default
$type = AttributeBag::get($attributes, 'type', 'button');
// get with prefix normalization
$label = AttributeBag::get($attributes, 'label', null, 'aria-');
// remove unwanted keys
AttributeBag::remove($attributes, 'readonly');
// set values (closures are resolved)
AttributeBag::set($attributes, 'disabled', true);
AttributeBag::set($attributes, 'id', static fn () => 'submit');
// set one key (raw value)
AttributeBag::set($attributes, 'aria-label', 'Save');
// booleans for `aria`, `data`, and `on*` attributes are stored as literal strings
AttributeBag::set($attributes, 'expanded', true, 'aria-');
// $attributes['aria-expanded'] === 'true'
// set many keys at once (useful for trait-driven prefixed attributes)
AttributeBag::setMany(
$attributes,
[
'data-toggle' => 'modal',
'onclick' => 'handleClick()',
],
);
// remove a key explicitly
AttributeBag::remove($attributes, 'id');Pass your domain objects directly to helpers like Encode, Attributes, or CSSClass. The library automatically
handles __toString().
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\Encode;
class User implements \Stringable
{
public function __construct(private string $name) {}
public function __toString(): string
{
return $this->name;
}
}
$user = new User('<John Doe>');
// automatically casts and safely encodes
echo Encode::content($user);
// <John Doe>Use Attributes::render() to generate a safe, escaped HTML attribute string from an array. It automatically handles class arrays, style arrays, and data-* expansions.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\Attributes;
?>
<?= Attributes::render(
[
'id' => 'submit-btn',
// automatically joined
'class' => ['btn', 'btn-primary'],
// `true` booleans are rendered as valueless attributes
'disabled' => true,
// `false` booleans are skipped
'readonly' => false,
// JSON encoded automatically
'data' => [
'id' => 42,
'options' => ['modal' => true],
],
'style' => [
'color' => '#fff',
'margin-top' => '10px'
],
]
) ?>
// class="btn btn-primary" id="submit-btn" disabled data-id="42" data-options='{"modal":true}' style='color: #fff; margin-top: 10px;'When working with DOMDocument, SimpleXMLElement, or other XML/SVG builders, you should not use pre-escaped strings to avoid "double escaping" (for example, &lt;).
Use Attributes::normalizeAttributes() with encode: false to get a flat array of raw values ready for insertion.
use UIAwesome\Html\Helper\Attributes;
$attributes = [
'class' => ['icon', ButtonType::PRIMARY],
'data-config' => ['key' => '<val>'],
'title' => '<Safe Title>',
];
// Get raw values (encode: `false`)
$rawAttributes = Attributes::normalizeAttributes($attributes, encode: false);
// [
// 'class' => 'icon btn-primary',
// 'data-config' => '{"key":"<val>"}'
// 'title' => '<Safe Title>',
// ]
// Perfect for DOMDocument
foreach ($rawAttributes as $name => $value) {
// DOMDocument handles the escaping automatically here
$domElement->setAttribute($name, $value);
}Allows you to merge, add, or override CSS classes within an attributes array smartly.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\CSSClass;
$attributes = ['class' => 'base-class'];
// add new classes (merges efficiently)
CSSClass::add($attributes, ['text-center', 'mt-5']);
// override existing classes
CSSClass::add($attributes, 'alert alert-danger', true);
echo $attributes['class'];
// alert alert-dangerEnsures your content and attribute values are safe from XSS.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\Encode;
// safe Content
echo Encode::content('<script>alert("xss")</script>');
// <script>alert("xss")</script>
// safe Attribute Value
echo Encode::value('Name "Quote"');
// Name "Quote"Normalizes values against a predefined set, supporting both arrays and Enums.
<?php
declare(strict_types=1);
namespace App;
use App\Enums\Status;
use UIAwesome\Html\Helper\Enum;
// normalize array of Enums
$result = Enum::normalizeArray([Status::ACTIVE, Status::INACTIVE]);
// ['active', 'inactive']
// normalize mixed array
$result = Enum::normalizeArray(['foo', Status::ACTIVE, 42]);
// ['foo', 'active', 42]
// normalize value from Enum
Enum::normalizeValue(Status::ACTIVE);
// 'active'
// normalize value from mixed
Enum::normalizeValue('foo');
// 'foo'Generates standard PHP form names and valid HTML IDs, handling arrayable and nested properties effortlessly.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\Naming;
// generate input name (Nested)
echo Naming::generateInputName('User', 'profile[0][email]');
// User[profile][0][email]
// generate input ID (Sanitized)
echo Naming::generateInputId('User', 'profile[0][email]');
// user-profile-0-email
// convert regex to pattern
echo Naming::convertToPattern('/^[a-z]+$/i');
// ^[a-z]+$Performs clean token replacement with normalized line endings.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\Template;
echo Template::render("Hello, {name}!", ['{name}' => 'Yii3']);
// Hello, Yii3!Collapses multiple line breaks into a single \n, useful for cleaning up user input or generated text.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\LineBreakNormalizer;
echo LineBreakNormalizer::normalize("Hello\n\n\nWorld");
// Hello\nWorldEnforces strict types and approved values for your HTML logic.
<?php
declare(strict_types=1);
namespace App;
use UIAwesome\Html\Helper\Validator;
// validate integer-like string
$isValid = Validator::intLike('123', 0, 1000);
// validate against allowed list (supports Enums)
Validator::oneOf('sm', ['sm', 'md', 'lg'], 'size');
// passes
// validate positive-like number
$isPositive = Validator::positiveLike('42.5', 0, 100);
// true
// validate SVG offset-like values (ratio: 0..1, percent: 0%..100%)
$isOffsetValid = Validator::offsetLike('50%');
// trueFor detailed configuration options and advanced usage.
