# HTML Contracts

> Contracts (interfaces) for the UI Awesome HTML ecosystem for PHP

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

**Contracts (interfaces) for the UI Awesome HTML ecosystem for PHP**

_Provides shared interfaces for rendering, attribute management, and form control typing across HTML packages._

## Features

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

## Quick start

### Installation

```bash
composer require ui-awesome/html-contracts:^0.2
```

### Basic usage

#### RenderableInterface

Core contract for any object that can be rendered as an HTML string. Extends `Stringable`.

```php
<?php

declare(strict_types=1);

use UIAwesome\Html\Contracts\RenderableInterface;

final class MyTag implements RenderableInterface
{
    public function __toString(): string
    {
        return $this->render();
    }

    public function render(): string
    {
        return '<div>Hello</div>';
    }
}
```

#### AttributesInterface

Contract for objects that manage HTML attributes with an immutable API.

Methods: `addAttribute()`, `attributes()`, `class()`, `getAttribute()`, `getAttributes()`, and `removeAttribute()`.

#### ContentInterface

Contract for immutable encoded element content. `content(string|Stringable|UnitEnum ...$values)` normalizes enum
values before HTML encoding; `getContent()` returns accumulated content, and `html(string|Stringable|UnitEnum ...$values)`
normalizes enum values and appends trusted raw HTML without encoding or sanitizing. Backed enums use their value (including integer zero); pure enums use their name.

Existing callers remain compatible. Implementations and overrides retaining the old narrower signature must be
updated; see [signature compatibility](https://github.com/ui-awesome/html-contracts/blob/main/docs/examples.md#signature-compatibility) before upgrading implementations.

#### ClearableContentInterface

Optional capability extending `ContentInterface`. `clearContent()` returns a new instance with empty content,
preserving other component state. Existing `ContentInterface` implementations need no changes.
Call `clearContent()->content($value)` to replace accumulated content with encoded text.

#### FormControlInterface

Composed interface extending both `RenderableInterface` and `AttributesInterface`. Use this to type form control
elements (inputs, selects, textareas, etc.) that need both rendering and attribute management.

```php
<?php

declare(strict_types=1);

use UIAwesome\Html\Contracts\Form\FormControlInterface;

function renderField(FormControlInterface $control): string
{
    return $control->class('form-control')->render();
}
```

## Documentation

Practical guides for implementing framework-independent HTML interfaces and verifying their contracts.

- 📚 [Installation guide](https://github.com/ui-awesome/html-contracts/blob/main/docs/installation.md)
- 💡 [Implementation examples](https://github.com/ui-awesome/html-contracts/blob/main/docs/examples.md)
- 🧪 [Testing guide](https://github.com/ui-awesome/html-contracts/blob/main/docs/testing.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-contracts` skill](https://github.com/ui-awesome/html-contracts/blob/main/docs/agents.md):
  immutable implementations, encoded versus raw content,
  and explicit form-control capabilities.

See the [repository guides](#documentation), the [skill source](https://github.com/ui-awesome/html-contracts/blob/main/skills/ui-awesome-html-contracts/SKILL.md), the source PHPDoc and
the [changelog](https://github.com/ui-awesome/html-contracts/blob/main/CHANGELOG.md). This interfaces-only package does not supply a renderer or require Yii.

## 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-contracts/blob/main/LICENSE)

## Package

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