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.

clearContent() returns a clone with empty content and preserves all other component state. It clears both encoded and raw content; subsequent content() and html() calls keep their existing append behavior.

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 store content, optional tags and their attributes. The host component is responsible for rendering those tags; the minimal host below concatenates only the stored content.

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();
// Prefix: Main Content :Suffix

Documentation

For detailed configuration options and advanced usage.

🧪 Testing Guide
⬆️ Upgrade Guide

AI assistance

AI agents: read the documentation index and fetch the Markdown version of a page by appending index.md to its URL. The AI agents guide covers skill installation, client setup and verification.

🤖 ui-awesome-html-mixin skill: immutable attributes, encoded and raw content, templates, and label, container, prefix and suffix collections.

Match the installed package revision. If hosted documentation does not match or is unavailable, use the repository guides, the skill source, the source PHPDoc and the changelog. This package is framework-independent and provides traits for host classes; it does not render elements by itself.