包简介

UssElement is a PHP library for building and manipulating HTML elements programmatically.

README 文档

README

A simple, lightweight, standalone PHP library for programmatically creating and manipulating HTML elements. It simplifies the process of working with HTML structures and DOM elements, offering functionality similar to DOMDocument but with reduced boilerplate and enhanced ease of use.

With UssElement, you can effortlessly create DOM nodes, set attributes, set innerHtml, use querySelector, modify element classlist etc, and generate (or render) HTML strings with ease.

Why Uss Element?

UssElement is designed to simplify and streamline the process of working with HTML elements in PHP. If (like me) you've ever been frustrated by the complexity of PHP's DOMDocument or found yourself writing repetitive, cumbersome code just to manipulate HTML structures, UssElement is the solution you’ve been waiting for.

This standalone library takes care of the heavy lifting, reducing boilerplate code and eliminates the need for complex XPath queries, offering a simple, intuitive API for tasks like creating elements, setting inner HTML, and selecting elements using CSS selectors.

The library is lightweight, fast, and easy to integrate into any project, making it perfect for both small and large-scale applications.

Key Features:

Create HTML elements using PHP code.
More inspired by Javascript DOM than PHP DOMDocument
Set element attributes, such as class names and IDs.
Define inner HTML content for elements.
Generate or render HTML strings with the NodeInterface::render() method.
Boost your productivity by simplifying HTML generation in PHP.
Reducing Complexity
Providing an Intuitive API
Encouraging Dependency-Free Development
Efficiency in Common DOM Tasks
Flexibility and Extensibility
Improving Developer Experience
Encoding element to Json format
Decoding element from json format

Prerequisite

PHP >= 8.2

Installation (Composer)

You can include UssElement library in your project using Composer:

composer require ucscode/uss-element

Getting Started:

Instantiate the UssElement class with the desired HTML element type (e.g., NodeNameEnum::NODE_DIV).
Use UssElement methods to set attributes and content.
Generate HTML strings with NodeInterface::render() for seamless integration into your web pages.

Creating Elements

You can create elements by instantiating the type of node

use Ucscode\UssElement\Node\ElementNode;

$element = new ElementNode('div');

If you prefer, you can use the NodeNameEnum enum

use Ucscode\UssElement\Node\ElementNode;
use Ucscode\UssElement\Enums\NodeNameEnum;

$element = new ElementNode(NodeNameEnum::NODE_DIV);

You can also create an element and set their attributes at the point of instantiation:

$span = new ElementNode('span', [
  'id' => 'short-cut',
  'class' => 'to set',
  'data-what' => 'attributes'
]);

You can use many available methods to manipulate the DOM.

A summary of these methods are provided in the following sections:

NodeInterface methods
ElementInterface methods
TextNode methods

$element->appendChild($span);

$element->getNextSibling();

$element->getChild(0)
  ->setAttribute('data-name', 'Ucscode')
  ->setAttribute('title', 'Uss Element')
;

Traversing Elements

Use the querySelector() or querySelectorAll() method to select elements based on CSS selectors:

$element->querySelector('.to.set[data-what=attributes]'); // Returns the <span> element

You can also retrieve an element by other methods such as:

getElementsByClassName
getElementsByTagName

$element->getElementsByClassName('.set'); // Returns the <span> element

Inner HTML

You can easily set the inner HTML content of an element using the setInnerHtml() method:
You can also get inner HTML of an element using getInnerHTML() method:

$element->setInnerHtml('<p>This is a paragraph inside a div.</p>');

Loading HTML

You can convert an HTML string to NodeList containing all elements using the HtmlLoader class:

use Ucscode\UssElement\Parser\Translator\HtmlLoader;

// An example HTML document:
$html = <<< 'HERE'
  <html>
    <head>
      <title>TEST</title>
    </head>
    <body id='foo'>
      <h1>Hello World</h1>
      <p>This is a test of the HTML5 parser.</p>
    </body>
  </html>
HERE;

$htmlLoader = new HtmlLoader($html);

$htmlLoader->getNodeList()->count(); // Returns the number of direct nodes (1 in this case)
$htmlLoader->getNodeList()->first; // HTML ElementNode

You can also load framents

use Ucscode\UssElement\Parser\Translator\HtmlLoader;

$html = <<< 'HERE'
  <h1>Hi there</h1>
  <p>Please enter your detail</p>
  <form name="my-form>
    <input name="username"/>
  </form>
HERE;

$htmlLoader = new HtmlLoader($html);

$htmlLoader->getNodeList()->count(); // Returns the number of direct nodes (3 in this case)

$htmlLoader->getNodeList()->get(0); // H1 ElementNode
$htmlLoader->getNodeList()->get(1); // P ElementNode
$htmlLoader->getNodeList()->get(2); // FORM ElementNode

Basic Example

$html = '<div class="container"><p>Hello, world!</p></div>';
$htmlLoader = new HtmlLoader($html);

// Access the root div element
$divElement = $htmlLoader->getNodeList()->get(0);

// Set inner HTML of the root element
$divElement->setInnerHtml('<i class="fa-icon"></i><h1 class="heading">New Heading</h1><br/>');

// Query the first paragraph within the container
$paragraph = $divElement->querySelector('p'); // null
$heading = $divElement->querySelector('h1.heading'); // H1 ElementNode

// Accessing the number of direct child nodes
echo $divElement->getChildNodes()->count(); // 3

Render HTML

You can get or render the ElementNode as HTML using the render() method.

echo $divElement->render();

Output

<div class="container"><i class="fa-icon"></i><h1 class="heading">New Heading</h1><br/></div>

If you want to indent the rendered output, pass an unsigned integer (initially one) to the render() method

echo $divElement->render(1);

The higher the integer, the more the indentation

Output

<div class="container">
    <i class="fa-icon"></i>
    <h1 class="heading">
        New Heading
    </h1>
    <br/>
</div>

Element Render Visibility

To keep an element in the DOM tree but exclude it from the rendered output, set its visibility to false.

$divElement->querySelector('.heading')->setVisible(false);

$divElement->render(1);

<div class="container">
    <i class="fa-icon"></i>
    <br/>
</div>

$divElement->getChildren()->count(); // 3

Setting Void Item

Some HTML elements, like <br> and <img>, do not have closing tags.

The setVoid() method marks an element as void, ensuring that it is rendered without a closing tag. This is especially helpful when defining custom elements.

$element = new Element('x-widget', [
  ':vue-binder' => 'project'
]);

$element->render(); // <x-widget :vue-binder="project"></x-widget>

$element->setVoid(true);

$element->render(); // <x-widget :vue-binder="project"/>

Encoding and Decoding Nodes

This library provides methods for encoding a node into JSON format and decoding it back to its original structure.
This is useful for transferring nodes between systems or storing them in a format that can be easily reconstructed.

Encoding a Node

To encode a node into JSON format, the toJson() method is used.

$node->toJson(); // Node to JSON Serialization

The toJson() method internally uses an instance of the NodeJsonEncoder, which is the actual encoder responsible for serializing the node.

(new NodeJsonEncoder($node))->encode();

Decoding a Node

To decode a JSON string back into a node, use the NodeJsonDecoder class.

(new NodeJsonDecoder($json))->decode(); // JSON to Node Deserilization

The decoding process restores the full structure of the original node, including its attributes, child nodes, and content.

Normalization

Both the NodeJsonEncoder and NodeJsonDecoder provide a normalize method to convert the input into an array.

(new NodeJsonEncoder($node))->normalize(); // to array
(new NodeJsonDecoder($json))->normalize(); // to array

NodeInterface methods

Method	Description	Returns
`getNodeName`	Return the name of the current node	`string`
`getNodeType`	Return the node identifier	`integer`
`setVisible`	Set the visibility state of a node when rendered	`static`
`isVisible`	Verify the visibility state of a node when rendered	`boolean`
`render`	Convert the node to string (OuterHTML)	`string`
`getParentElement`	Returns an Element that is the parent of the current node	`ElementInterface\|null`
`getParentNode`	Returns a Node that is the parent of the current node	`NodeInterface\|null`
`getChildNodes`	Returns a NodeList containing all the children of the current node	`NodeList`
`clearChildNodes`	Remove all the child Nodes from the current element	`static`
`appendChild`	Adds the specified Node argument as the last child to the current node	`static`
`prependChild`	Adds the specified Node argument as the first child to the current node	`static`
`getFirstChild`	Returns a Node representing the last direct child node of the current node	`NodeInterface\|null`
`getLastChild`	Returns a Node representing the last direct child node of the node	`NodeInterface\|null`
`getNextSibling`	Returns a Node representing the next node in the tree	`NodeInterface\|null`
`getPreviousSibling`	Returns a Node representing the previous node in the tree	`NodeInterface\|null`
`insertBefore`	Inserts a Node before the reference node as a child of a specified parent node	`static`
`insertAfter`	Inserts a Node after the reference node as a child of a specified parent node	`static`
`insertAdjacentNode`	Inserts a Node at a specific position relative to other child nodes	`static`
`hasChild`	Verify that a node has the provided child node	`boolean`
`getChild`	Get a child node from the Nodelist	`NodeInterface\|null`
`removeChild`	Removes a child node from the current element	`static`
`replaceChild`	Replaces one child Node of the current one with the second one given in parameter	`static`
`cloneNode`	Clone a Node, and optionally, all of its contents	`NodeInterface`
`sortChildNodes`	Reorder the child nodes of a specified parent node	`static`
`moveBefore`	Move the current node before a sibling node within the same parent node	`static`
`moveAfter`	Move the current node after a sibling node within the same parent node	`static`
`moveToFirst`	Move the current node to the first position of its relative sibling nodes	`static`
`moveToLast`	Move the current node to the last position of its relative sibling nodes	`static`
`moveToIndex`	Move the current node to a specific position within its sibling nodes	`static`
`toJson`	Converts the node and its descendants into a JSON-encoded string	`string`

ElementInterface methods

Includes:

NodeInterface methods

Method	Description	Returns
`getTagName`	Return the tag name of the current element	`string`
`setInnerHtml`	Set the inner HTML of the element	`static`
`getInnerHtml`	Get the inner HTML of the element	`string`
`setVoid`	Set whether the element is void (no closing tag)	`static`
`isVoid`	Verify if the element is void, meaning it has no closing tag	`boolean`
`getOpenTag`	Get the opening tag of the element	`string`
`getCloseTag`	Get the closing tag of the element (if any)	`string\|null`
`getChildren`	Get a collection of the element's children	`ElementList`
`getAttribute`	Get the value of a specific attribute by name	`string\|null`
`getAttributes`	Get a collection of all attributes of the element	`Attributes`
`getAttributeNames`	Get a list of all attribute names of the element	`array`
`hasAttribute`	Check if the element has a specific attribute	`boolean`
`hasAttributes`	Check if the element has any attributes	`boolean`
`setAttribute`	Set the value of a specific attribute	`static`
`removeAttribute`	Remove a specific attribute from the element	`static`
`querySelector`	Find and return the first matching element by the given CSS selector	`ElementInterface\|null`
`querySelectorAll`	Find and return all matching elements by the given CSS selector	`ElementList`
`getClassList`	Get a collection of classes of the element	`ClassList`
`matches`	Check if the current element matches the given CSS selector	`boolean`
`getElementsByClassName`	Get all elements with the specified class name	`ElementList`
`getElementsByTagName`	Get all elements with the specified tag name	`ElementList`

TextNode methods

Includes:

NodeInterface methods

Method	Description	Returns
`getData`	Get the text data	`string`
`length`	The length of the text data	`integer`
`isContentWhiteSpace`	Check if the content of the text node is empty or contains only whitespace	`boolean`

Collection Objects

PHP Class	Description
`Attributes`	Manages attributes of an element.
`ClassList`	Handles class names for an element.
`ElementList`	A collection of `ElementInterface` types.
`NodeList`	A collection of any node types.

Node Objects

PHP Class	Description
`CommentNode`	Represents HTML comments.
`DocumentTypeNode`	Represents the `<!DOCTYPE>` declaration.
`ElementNode`	Represents HTML elements.
`TextNode`	Represents textual content.

Parser Objects

PHP Class	Description
`HtmlLoader`	Parses an HTML string into nodes.
`Matcher`	Matches nodes against CSS selectors.
`Tokenizer`	Breaks down CSS selectors into tokens.
`Transformer`	Encodes and decodes CSS selectors.
`NodeSelector`	Finds descendants matching CSS selectors.
`NodeJsonEncoder`	Encodes a node and its descendants into JSON format
`NodeJsonDecoder`	Decodes a node JSON back into a node instance.

Providing Support For:

Combinators: Use of combinator such as >, +, ~, $ are captured but not yet supported

Contributing

Feel free to open issues or submit pull requests. We welcome contributions to improve the library.

How to Contribute

Fork the repository.
Create a new branch (git checkout -b feature-xyz).
Commit your changes (git commit -am 'Add feature xyz').
Push to the branch (git push origin feature-xyz).
Create a new pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

ucscode/uss-element 适用场景与选型建议

ucscode/uss-element 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 203 次下载、GitHub Stars 达 4，最近一次更新时间为 2023 年 09 月 10 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「php」「library」「html」「dom」「element」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 ucscode/uss-element 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 ucscode/uss-element 我们能提供哪些服务？

定制开发 / 二次开发

基于 ucscode/uss-element 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 ucscode/uss-element 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

dg/texy 159

Texy converts plain text in easy to read Texy syntax into structurally valid (X)HTML. It supports adding of images, links, nested lists, tables and has full support for CSS. Texy supports hyphenation of long words (which reflects language rules), clickable emails and URL (emails are obfuscated again

axelarge/html-helpers 6

HTML and form generation

shipsaas/laravel-inbox-process 13

Inbox pattern process implementation for your Laravel Applications

eyupcanakman/simple-html-dom 1

A modern HTML DOM parser for PHP using DOMDocument and Symfony CssSelector.

intahwebz/core 0

Core library that defines common interfaces used by the rest of the intahwebz..

lacus/utils 0

Reusable utilities library for Lacus Solutions' packages (type description, HTML escaping, random sequences)

ucscode/uss-element

包简介

关键字：

README 文档

README

Why Uss Element?

Key Features:

Prerequisite

Installation (Composer)

Getting Started:

Creating Elements

Traversing Elements

Inner HTML

Loading HTML

Basic Example

Render HTML

Output

Output

Element Render Visibility

Setting Void Item

Encoding and Decoding Nodes

Encoding a Node

Decoding a Node

Normalization

NodeInterface methods

ElementInterface methods

TextNode methods

Collection Objects

Node Objects

Parser Objects

Providing Support For:

Contributing

How to Contribute

License

ucscode/uss-element 适用场景与选型建议

与 ucscode/uss-element 相关的其它包

统计信息

GitHub 信息

其他信息