ucscode/uss-element

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

Maintainers

Details

github.com/ucscode/uss-element

Source

Issues

Installs: 68

Dependents: 6

Suggesters: 0

Security: 0

Stars: 4

Watchers: 1

Forks: 0

Open Issues: 0

3.7.1 2025-02-28 23:35 UTC

Requires

  • php: >=8.2

Requires (Dev)

MIT 1c1e6c2158c5868d9a3af52248f67dda5f30c0bc

  • Uchenna Ajah <uche23mail.woop@gmail.com>

phplibraryhtmldomelement

This package is auto-updated.

Last update: 2025-02-28 23:35:56 UTC

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:

$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:

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:

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

  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.