ui-awesome / html-contracts
Shared interfaces for the UI Awesome HTML ecosystem: rendering, attribute management, element typing, and form controls.
Requires
- php: ^8.3
Requires (Dev)
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
HTML Contracts for PHP
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
Quick start
Installation
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 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 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 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
- ๐ก Implementation examples
- ๐งช Testing 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-contractsskill: immutable implementations, encoded versus raw content, and explicit form-control capabilities.
See the repository guides, the skill source, the source PHPDoc and the changelog. This interfaces-only package does not supply a renderer or require Yii.