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.5

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 handles both safe encoded content and raw HTML with XSS protection through Encode::content().

<?php

declare(strict_types=1);

namespace App\Component;

use UIAwesome\Html\Mixin\HasContent;

final class MyComponent
{
    use HasContent;
}

$component = new MyComponent();

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

$component2 = new MyComponent();

$htmlContent = $component2
    ->html('<strong>Raw HTML</strong>')
    ->getContent();
// <strong>Raw HTML</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>