README

一个PHP库，让您能够以面向对象的方式生成HTML元素。

我为什么创建这个？

我曾经在一个非MVC的PHP项目中工作，有时候我需要在函数中直接输出几行HTML。将HTML代码与PHP代码混合对我来说是不一致的，而且由于这些疯狂且丑陋的拼接，长期保持代码易于阅读和维护是很困难的。这就是为什么我想到了直接在PHP中生成HTML元素的想法。（当然，如果您需要创建许多HTML元素，您应该考虑使用模板引擎）
在Packagist上已经有一些具有相同目的的现有库，但我并不完全满意，我也想为了乐趣和学习目的创建自己的库。

功能

支持自闭合标签。（例如 input 标签）
支持布尔属性。（例如 required 属性）

要求

PHP ^7.4 或 PHP ^8.0
Composer

安装

composer require artyuum/html-element

示例

简单

一个简单的带有一些属性和内容的DIV元素。

use Artyum\HtmlElement\Element;
use Artyum\HtmlElement\Attribute;

$divElement = new Element('div');

$divElement
    ->addAttributes(
        new Attribute('title', 'This is an editable DIV with a red background color'),
        new Attribute('style', [
                'width: 100px',
                'height: 100px',
                'background-color: red'
        ]),
        new Attribute('contenteditable', true)
    )
    ->addContent('This is an editable DIV with a red background color.')
;

echo $divElement;
// or 
echo $divElement->toHtml();

输出

<div title="This is an editable DIV with a red background color" style="width: 100px;height: 100px;background-color: red;" contenteditable>
    This is an editable DIV with a red background color.
</div>

高级

一个包含子元素的登录表单示例。

use Artyum\HtmlElement\Element;
use Artyum\HtmlElement\Attribute;

$formElement = new Element('form');
$divElement = new Element('div');
$labelElement = new Element('label');
$usernameInputElement = new Element('input');
$passwordInputElement = new Element('input');
$buttonElement = new Element('button');
$spanElement = new Element('span');

$formElement
    ->addAttributes(
        new Attribute('action', '/login'),
        new Attribute('method', 'post')
    )
    ->addContent(
        $divElement
            ->addAttributes(new Attribute('class', 'form-group'))
            ->addContent(
                $labelElement
                    ->addAttributes(new Attribute('for', 'username'))
                    ->addContent('Username'),
                $usernameInputElement
                    ->addAttributes(
                        new Attribute('type', 'text'),
                        new Attribute('class', 'form-control'),
                        new Attribute('id', 'username'),
                        new Attribute('name', 'username'),
                        new Attribute('placeholder', 'Username'),
                        new Attribute('style', [
                            'border: none',
                            'background-color: rgba(100, 100, 255, .1)'
                        ]),
                        new Attribute('required', true)
                    ),
                $passwordInputElement
                    ->addAttributes(
                        new Attribute('type', 'password'),
                        new Attribute('class', 'form-control'),
                        new Attribute('id', 'password'),
                        new Attribute('name', 'password'),
                        new Attribute('placeholder', 'Password'),
                        new Attribute('style', [
                            'border: none',
                            'background-color' => 'rgba(100, 100, 255, .1)'
                        ]),
                        new Attribute('required', true)
                    ),
                $buttonElement
                    ->addAttributes(new Attribute('type', 'submit'))
                    ->addContent(
                        $spanElement
                            ->addAttributes(new Attribute('class', 'fa fa-sign-in-alt'))
                            ->addContent('Login')
                    )
            )
    );

echo $formElement;
// or
echo $formElement->toHtml();

输出

<form action="/login" method="post">
    <div class="form-group">
        <label for="username">Username</label>
        <input type="text" class="form-control" id="username" name="username" placeholder="Username" style="border: none;background-color: rgba(100, 100, 255, .1)" required>
        <input type="password" class="form-control" id="password" name="password" placeholder="Password" style="border: none;rgba(100, 100, 255, .1)" required>
        <button type="submit"><span class="fa fa-sign-in-alt">Login</span></button>
    </div>
</form>

API

Artyum\HtmlElement\Element

在实例化 Element 类时，您可以可选地提供元素名称作为第一个参数，以及一个选项数组作为第二个参数。

__construct(?string $name = null, ?array $options = null)

获取元素的HTML代码。

toHtml(): string

如果您在设置名称属性之前调用此方法，将抛出 LogicException。

注意，您也可以简单地 echo 实例，它将内部调用 toHtml() 方法。这是由于 __toString() 魔法方法。

示例

// both will return the same result
echo $element->toHtml();
echo $element;

获取元素的名称。

getName(): ?string

设置元素的名称。

setName(string $name): self

获取元素的选项。

getOptions(): ?array

设置元素的选项。

setOptions(array $options): self

可用选项

获取分配给元素的属性。

getAttributes(): Attribute[]

向元素添加一个或多个属性。

addAttributes(... Attribute $attribute): self

多亏了扩展运算符 (...)，您可以传递任意数量的参数。您也可以多次调用此方法以添加更多属性。

返回元素的内容。

getContent(): ?string

向元素添加一个或多个内容。您可以传递一个字符串、一个整数、一个浮点数或Element类的实例。

addContent(...$content): self

Artyum\HtmlElement\Attribute

在实例化 Attribute 类时，您必须提供属性名称及其值。如果您传递一个值数组，您可以可选地传递用于分隔值的分隔符。

__construct(?string $name = null, mixed $value = null, string $separator = ';')

获取名称。

getName(): ?string

设置名称。

setName(string $name): self

获取值。

getValue(): mixed

设置值。

setValue(mixed $value): self

获取分隔符。

getSeparator(): string

设置属性值分隔符。

setSeparator(string $separator): self

构建并返回属性的HTML表示。

build(): string

如果您在设置名称或值属性之前调用此方法，将抛出 LogicException。

您也可以 echo 实例，它将内部调用 build() 方法。

更新日志

此库遵循语义版本控制。

4.0.0 - (2021-05-13)
- 将属性类构造函数参数设置为可选
- 在属性中添加了名称和值设置器
- 现在在调用属性上的 build() 时，如果未设置名称或值，将抛出异常
- 将元素类构造函数参数设置为可选
- 在元素中添加了名称设置器
- 现在在调用元素上的 toHtml() 时，如果未设置名称，将抛出异常
- 现在与 PHP 8 兼容
3.0.0 - (2020-09-21)
- 将 HtmlElement 重命名为 Element。
- 添加了一个新的属性类。
- 将 setContent 重命名为 addContent().
- 移除了 setName() 并在实例化元素类时将 $name 设置为必需。
- 为了使用属性类的新方式处理属性，移除了对 style 属性的原生支持。
- 为了 InvalidArgumentException，移除了 WrongAttributeValueException。
- addAttributes() 现在可以接受一个或多个参数。
- 根据新的更改更新了测试。
2.0.1 - (2020-01-22)
- 简化了 buildAttributes() 和 validateAttributes() 方法。
- 为具有数组值的属性添加了适当的验证。
- 更新测试以便更容易调试。
2.0.0 - (2019-12-29)
- 重新排列了代码。
- 现在要求 PHP 7.2 或更高版本。
- 移除了一个不必要的异常并添加了一个新的异常。
- 将 setAttributes() 重命名为 addAttributes() 并实现了合并属性的功能。
- 将 build() 重命名为 toHtml()（更明确）。
- 现在可以将数组设置为属性值（对于 "style" 属性）。
- 现在将自动修剪元素名称，以移除任何空格。
- 修复了可以返回 null 值的方法的返回类型。
- setContent() 现在接受整数和浮点值。
- 在实例化时不再需要传递元素的名称。
- 添加了 setName() 和 setOptions() 方法。
1.1.0 - (2019-05-05)
- 现在在实例化 HtmlElement 类时可以将 $options[] 数组传递给构造函数。
1.0.0 - (2019-05-04)
- 库完全功能且准备就绪。

贡献

如果您想贡献，请分叉存储库并根据您的意愿进行更改。确保遵循此库中使用的相同的编码风格和命名，以产生一致的代码。

artyuum / html-element

维护者

详细信息

README

我为什么创建这个？

功能

要求

安装

示例

简单

高级

API

Artyum\HtmlElement\Element

Artyum\HtmlElement\Attribute

更新日志

贡献