README

Html Mixin

A type-safe PHP mixin library for HTML tag rendering components
Build reusable components with traits for attributes, content, templates, and prefix/suffix management.

Features

Installation

composer require ui-awesome/html-mixin:^0.8

Quick start

Managing HTML attributes with HasAttributes

The HasAttributes trait provides a fluent, immutable API for managing HTML attributes on elements. It supports enum keys/values, closure-based values, additive updates with attributes(), explicit replacement with replaceAttributes(), and null values for removing attributes.

<?php

declare(strict_types=1);

namespace App\Component;

use UIAwesome\Html\Mixin\HasAttributes;

final class MyComponent
{
    use HasAttributes;
}

$component = new MyComponent();

$component = $component
    ->addAttribute('id', 'my-component')
    ->attributes(['class' => 'container', 'role' => 'main'])
    ->attributes(['data-state' => 'open', 'aria-label' => 'Close'])
    ->removeAttribute('role');

$component->getAttributes();
// ['id' => 'my-component', 'class' => 'container', 'data-state' => 'open', 'aria-label' => 'Close']

$component->getAttribute('id', 'default-id');
// 'my-component'

$component->getAttribute('aria-label');
// 'Close'

$replacement = $component->replaceAttributes(['id' => 'replacement']);

$replacement->getAttributes();
// ['id' => 'replacement']

Managing content with encoding support

The HasContent trait encodes content() values through Encode::content() and appends trusted html() values verbatim.

content() accepts string|Stringable|UnitEnum values. String-backed enums use their value, integer-backed enums use their value converted to a string (including 0), and pure enums use their case name. Each normalized value passes through Encode::content() once. Existing entities keep the encoder's default behavior (& becomes &amp;); quotes are not additionally escaped. Variadic order, chained accumulation, and immutability are unchanged.

html() accepts string|Stringable|UnitEnum and appends normalized, trusted raw HTML without encoding or sanitizing. Backed enums use their value (including zero); pure enums use their name. The content attribute of Meta is a separate API and is unchanged.

<?php

declare(strict_types=1);

namespace App\Component;

use UIAwesome\Html\Mixin\HasContent;

final class MyComponent
{
    use HasContent;
}

enum ContentMessage: string
{
    case GUIDANCE = 'Capture <events> & inspect them.';
}

$component = new MyComponent();

$enumContent = $component->content(ContentMessage::GUIDANCE)->getContent();
// Capture &lt;events&gt; &amp; inspect them.

$encodedContent = $component
    ->content('<script>alert("XSS")</script>')
    ->getContent();
// &lt;script&gt;alert("XSS")&lt;/script&gt;

$component2 = new MyComponent();

$htmlContent = $component2
    ->html('<strong>Raw HTML</strong>')
    ->getContent();
// <strong>Raw HTML</strong>

enum TrustedMarkup: string
{
    case NOTICE = '<strong>Saved &amp; ready</strong>';
}

$rawEnumContent = $component2->html(TrustedMarkup::NOTICE)->getContent();
// <strong>Saved &amp; ready</strong>

Custom templates with HasTemplate

Define custom rendering templates for your components using the HasTemplate trait.

<?php

declare(strict_types=1);

namespace App\Component;

use UIAwesome\Html\Mixin\{HasContent, HasTemplate};

final class MyComponent
{
    use HasContent;
    use HasTemplate;

    public function render(): string
    {
        return str_replace('{content}', $this->content, $this->template);
    }
}

$component = new MyComponent();

echo $component
    ->content('Card Content')
    ->template('<div class="card">{content}</div>')
    ->render();
// <div class="card">Card Content</div>

Prefix and suffix content with tag support

The HasPrefixCollection and HasSuffixCollection traits add content before and after your element, optionally wrapped in tags with their own attributes.

Tag APIs now accept UnitEnum, so your components can use any project enum without a direct runtime dependency on ui-awesome/html-interop.

<?php

declare(strict_types=1);

namespace App\Component;

use UIAwesome\Html\Mixin\{HasContent, HasPrefixCollection, HasSuffixCollection};

enum InlineTag: string
{
    case STRONG = 'strong';
    case EM = 'em';
}

final class MyComponent
{
    use HasContent;
    use HasPrefixCollection;
    use HasSuffixCollection;

    public function render(): string
    {
        return $this->prefix . $this->content . $this->suffix;
    }
}

$component = new MyComponent();

echo $component
    ->content('Main Content')
    ->prefix('Prefix: ')
    ->prefixAttributes(['class' => 'prefix-badge'])
    ->prefixTag(InlineTag::STRONG)
    ->suffix(' :Suffix')
    ->suffixTag(InlineTag::EM)
    ->render();
// <strong class="prefix-badge">Prefix: </strong>Main Content<em> :Suffix</em>