Download the PHP package ucscode/uss-element without Composer

Uss Element

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:

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

If you prefer, you can use the NodeNameEnum enum

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

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

Traversing Elements

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

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

• getElementsByClassName
• getElementsByTagName

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:

Loading HTML

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

You can also load framents

Basic Example

Render HTML

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

Output

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

Output

Element Render Visibility

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

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.

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.

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

Decoding a Node

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

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.

NodeInterface methods

ElementInterface methods

Includes:

• NodeInterface methods

TextNode methods

Includes:

• NodeInterface methods

Collection Objects

Node Objects

Parser Objects

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

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

License

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