## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require yiisoft/html

Add to composer.json if using Laravel’s autoloader:

"autoload": {
    "psr-4": {
        "App\\": "app/",
        "Yiisoft\\Html\\": "vendor/yiisoft/html/src/"
    }
}

Run composer dump-autoload.

First Use Case: Generate a simple link in a Blade template:
```
<?= \Yiisoft\Html\Html::a('Click Me', route('home')) ?>
```
Output: <a href="/home">Click Me</a>.
Key Entry Points:
- Tag Objects: Use new \Yiisoft\Html\Tag\A() for fluent tag building.
- Helper Methods: Static Html::a(), Html::button(), etc.
- Widgets: CheckboxList, RadioList, ButtonGroup for complex UIs.

Implementation Patterns

1. Fluent Tag Building

Chain methods for readability and reusability:

$button = (new \Yiisoft\Html\Tag\Button())
    ->type('submit')
    ->class('btn btn-primary')
    ->content('Save');
echo $button; // Renders as string

Laravel Integration: Store reusable tags in a service class:

class HtmlBuilder {
    public static function primaryButton(string $text): string {
        return (new \Yiisoft\Html\Tag\Button())
            ->type('button')
            ->class('btn btn-primary')
            ->content($text)
            ->render();
    }
}

Use in Blade:

{!! HtmlBuilder::primaryButton('Submit') !!}

2. Dynamic Form Handling

Checkbox/Radio Lists:

$checkboxes = (new \Yiisoft\Html\Widget\CheckboxList\CheckboxList('roles'))
    ->items([
        'admin' => 'Administrator',
        'user' => 'User',
    ])
    ->value('admin', 'user') // Pre-select
    ->containerAttributes(['class' => 'form-check']);
echo $checkboxes;

Laravel Form Requests: Bind to a FormRequest validator:

public function rules(): array {
    return [
        'roles' => 'array',
        'roles.*' => 'in:admin,user',
    ];
}

3. Asset Management

CSS/JS Files:

<?= \Yiisoft\Html\Html::cssFile(
    asset('css/app.css'),
    ['integrity' => 'sha256-...', 'crossorigin' => 'anonymous']
) ?>

Laravel Mix Integration: Use mix() helper:

<?= \Yiisoft\Html\Html::cssFile(mix('css/app.css')) ?>

4. Conditional Rendering

Dynamic Attributes:

$link = (new \Yiisoft\Html\Tag\A())
    ->href(route('profile'))
    ->class('nav-link' . ($active ? ' active' : ''));

Blade Directives: Create a custom Blade directive:

Blade::directive('htmlTag', function ($expression) {
    return "<?php echo {$expression}; ?>";
});

Usage:

@htmlTag(\Yiisoft\Html\Html::a('Home', route('home')))

5. Widgets in Blade Components

Encapsulate widgets in Laravel components:

// app/View/Components/ButtonGroup.php
class ButtonGroup extends Component {
    public function render(): string {
        return (new \Yiisoft\Html\Widget\ButtonGroup())
            ->buttons(
                \Yiisoft\Html\Html::button('Save'),
                \Yiisoft\Html\Html::button('Cancel')
            )
            ->containerAttributes(['class' => 'btn-group']);
    }
}

Usage in Blade:

<x-button-group />

Gotchas and Tips

1. Encoding Pitfalls

Default Behavior: All string content is HTML-encoded unless wrapped in NoEncode or passed as a NoEncodeStringableInterface object.

// Encoded: <div>&lt;script&gt;alert()&lt;/script&gt;</div>
echo \Yiisoft\Html\Html::div('<script>alert()</script>');

// Not Encoded: <div><script>alert()</script></div>
echo \Yiisoft\Html::div(\Yiisoft\Html\NoEncode::string('<script>alert()</script>'));

Tag Objects: Child tag objects (e.g., Html::a() inside Html::div()) are not encoded by default.

2. ID Generation Quirks

Auto-Generated IDs: Use Html::generateId() for unique IDs:
```
$id = \Yiisoft\Html\Html::generateId('user-');
```

Testing: Override ID generation in tests:

\Yiisoft\Html\Html::setIdGenerator(function () {
    return 'test-id';
});

3. Attribute Handling

Boolean Attributes: Omit false values (e.g., disabled="disabled" becomes disabled).

Data Attributes: Use data-* helpers:

$tag = (new \Yiisoft\Html\Tag\Div())
    ->data('user-id', 123)
    ->data('active', true);

Class Manipulation: Use addCssClass()/removeCssClass():

$button = (new \Yiisoft\Html\Tag\Button())
    ->class('btn')
    ->addCssClass('btn-primary')
    ->removeCssClass('disabled');

4. Performance Tips

Reuse Tag Objects: Cache frequently used tags (e.g., navigation menus) in a service container.
Avoid Redundant Rendering: Call render() once and store the result:
```
$html = $tag->render(); // Store in cache
```
Minimize Encoding: Use NoEncode for trusted HTML (e.g., Markdown content).

5. Debugging

Inspect Attributes: Use renderTagAttributes() to debug:

echo \Yiisoft\Html\Html::renderTagAttributes([
    'class' => 'btn btn-primary',
    'data-test' => 'true',
]);

Widget Debugging: Check widget methods like CheckboxList::renderUncheckInput() for hidden issues.

6. Extension Points

Custom Tags: Extend CustomTag for non-standard HTML:

class CustomComponentTag extends \Yiisoft\Html\Tag\CustomTag {
    public function __construct(string $tagName, array $attributes = []) {
        parent::__construct($tagName, $attributes);
        $this->addAttribute('is', 'custom-component');
    }
}

Override Helpers: Replace Html helper methods in Laravel’s service provider:

app()->singleton('html', function () {
    return new class extends \Yiisoft\Html\Html {
        public static function customTag(string $tag, array $attributes = []): string {
            return (new CustomComponentTag($tag, $attributes))->render();
        }
    };
});

7. Common Mistakes

Forgetting to Render: Tag objects must be cast to string or called via render():
```
// Wrong: Outputs object
echo $tag;

// Correct:
echo $tag->render();
```

Nested Encoding: Double-encoding occurs when passing already-encoded strings:

// Wrong: Encodes twice
echo \Yiisoft\Html\Html::div(htmlspecialchars('text'));

// Correct: Use NoEncode
echo \Yiisoft\Html\Html::div(\Yiisoft\Html\NoEncode::string(htmlspecialchars('text')));

Widget Configuration: Ensure items, value, and uncheckValue are set for CheckboxList/RadioList.

8. Laravel-Specific Tips

Blade Escaping: Use {!! !!} for raw HTML output:

{!! \Yiisoft\Html\Html::div('<strong>Safe</strong>') !!}

Form Requests: Validate widget-generated inputs (

Html Laravel Package