# HTML Mixin

> A type-safe PHP mixin library for HTML tag rendering components

Package entry: `ui-awesome/html-mixin`. Requires PHP `^8.3`. Checked 2026-11-13. [View the entry in the package directory](</docs/packages/ui-awesome/html-mixin/index.md>)

**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

![Feature Overview](https://raw.githubusercontent.com/ui-awesome/html-mixin/main/docs/svgs/features.svg)

### Installation

```bash
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
<?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 (`&amp;` becomes
`&amp;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
<?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
<?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
<?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](https://github.com/ui-awesome/html-mixin/blob/main/docs/testing.md)
- ⬆️ [Upgrade guide](https://github.com/ui-awesome/html-mixin/blob/main/UPGRADE.md)

## AI assistance

AI agents: read the [documentation index](https://yii2-framework.github.io/docs/llms.txt) and fetch the Markdown version
of a page by appending `index.md` to its URL. The
[AI agents guide](https://github.com/yii2-framework/docs/blob/main/src/content/docs/project/ai-agents.md) covers skill
installation, client setup and verification.

- 🤖 [`ui-awesome-html-mixin` skill](https://github.com/ui-awesome/html-mixin/blob/main/docs/agents.md):
  immutable attributes, encoded and raw content, templates, and label,
  container, prefix and suffix collections.

See the [repository guides](#documentation), the [skill source](https://github.com/ui-awesome/html-mixin/blob/main/skills/ui-awesome-html-mixin/SKILL.md), the source PHPDoc and
the [changelog](https://github.com/ui-awesome/html-mixin/blob/main/CHANGELOG.md). This package is framework-independent and provides traits for host classes; it does not
render elements by itself.

## Our social networks

[Follow on X](https://x.com/Terabytesoftw)
[Follow on Facebook](https://www.facebook.com/wilmer.arambula.9)

## License

[License](https://github.com/ui-awesome/html-mixin/blob/main/LICENSE)

## Package

- Source code and issues: [ui-awesome/html-mixin](https://github.com/ui-awesome/html-mixin). Star the repository if the package is useful to you.
- Composer package: [ui-awesome/html-mixin](https://packagist.org/packages/ui-awesome/html-mixin).
- Changelog: [CHANGELOG.md](https://github.com/ui-awesome/html-mixin/blob/main/CHANGELOG.md).