README

A lightweight PHP library for DOM operations with CSS selector support and comprehensive element manipulation. Designed with clean APIs that make complex DOM tasks simple and reliable.

Features

🎯 Clean API: Separate classes for different DOM operations (DOM, Element, CSS)
🔍 CSS Selectors: Modern querySelector and querySelectorAll support
🏗️ Element Manipulation: Wrap, unwrap, insert, replace, and transform elements
🎨 Style Management: Parse and modify CSS styles with ease
🏷️ Class Utilities: Add, remove, and modify CSS classes intelligently
🛠️ Structure Modification: Change tag names, clone elements, and restructure DOM
⚡ WordPress Ready: Built for WordPress but works in any PHP environment
🔒 Safe Operations: Graceful error handling with null returns

Why Not WordPress's HTML API?

WordPress 6.2+ includes an HTML Tag Processor, but it's limited to linear attribute modifications. Our library provides:

Full DOM tree manipulation (WordPress can't wrap, insert, or restructure)
CSS selector support (WordPress uses linear tag scanning)
Element creation and cloning (WordPress is read-modify only)
Style and class management (WordPress focuses on attributes)

Requirements

PHP 7.4 or later
DOM extension
libxml extension

Installation

composer require arraypress/wp-dom-utils

Basic Usage

Creating and Parsing DOM

use ArrayPress\DOMUtils\DOM;

// Create DOM from HTML string
$dom = DOM::create( '<div class="container"><p>Hello World</p></div>' );

// Query elements with CSS selectors
$container  = DOM::query_selector( '.container', $dom );
$paragraphs = DOM::query_selector_all( 'p', $dom );

// Convert back to HTML
$html = DOM::to_html( $dom );

Element Manipulation

use ArrayPress\DOMUtils\Element;

// Wrap an element
$wrapper = Element::wrap( $paragraph, 'div', [ 'class' => 'wrapper' ] );

// Change tag name
$new_element = Element::change_tag_name( 'section', $div );

// Insert content
Element::insert_before( $target, '<span>Before</span>' );
Element::insert_after( $target, '<span>After</span>' );
Element::replace_with( $target, '<p>Replacement</p>' );

// Clone elements
$clone = Element::clone_element( $original, true ); // deep clone

Class Management

use ArrayPress\DOMUtils\Element;

// Add multiple classes
Element::add_classes( $element, [ 'active', 'highlighted' ] );

// Remove classes
Element::remove_classes( $element, [ 'old', 'deprecated' ] );

// Replace classes
Element::replace_classes( $element, [ 'old-class' ], [ 'new-class' ] );

// Check for classes
if ( Element::has_classes( $element, [ 'required', 'validated' ] ) ) {
	// Element has all required classes
}

CSS Style Management

use ArrayPress\DOMUtils\CSS;
use ArrayPress\DOMUtils\Element;

// Parse CSS string to array
$styles = CSS::string_to_array( 'color: red; margin: 10px; padding: 5px;' );
// Returns: ['color' => 'red', 'margin' => '10px', 'padding' => '5px']

// Convert array back to CSS string
$css_string = CSS::array_to_string( [ 'color' => 'blue', 'font-size' => '14px' ] );
// Returns: "color: blue; font-size: 14px"

// Add styles to element
Element::add_styles( $element, [
	'background-color' => '#f0f0f0',
	'border'           => '1px solid #ccc',
	'padding'          => '10px'
] );

Common Use Cases

Content Transformation

function transform_content( $html ) {
	$dom = DOM::create( $html );

	// Wrap all images in figure elements
	$images = DOM::query_selector_all( 'img', $dom );
	foreach ( $images as $img ) {
		Element::wrap( $img, 'figure', [ 'class' => 'image-wrapper' ] );
	}

	return DOM::to_html( $dom );
}

WordPress Integration

// Hook into WordPress content filters
add_filter( 'the_content', function ( $content ) {
	$dom = DOM::create( $content );

	// Add lazy loading to images
	$images = DOM::query_selector_all( 'img', $dom );
	foreach ( $images as $img ) {
		if ( ! Element::get_attribute( $img, 'loading' ) ) {
			Element::set_attributes( $img, [ 'loading' => 'lazy' ] );
		}
	}

	// Wrap tables for responsiveness
	$tables = DOM::query_selector_all( 'table', $dom );
	foreach ( $tables as $table ) {
		Element::wrap( $table, 'div', [ 'class' => 'table-responsive' ] );
	}

	return DOM::to_html( $dom );
} );

API Reference

DOM Class

create( string $html, array $options = [] ): DOMDocument
query_selector( string $selector, $context ): ?DOMElement
query_selector_all( string $selector, $context ): DOMNodeList
create_element( DOMDocument $dom, string $tag, array $attributes = [], $content = ''): ?DOMElement
to_html( $node, bool $inner_html = false ): string

Element Class

Attributes:

get_attribute( DOMElement $element, string $attribute, $default = null
set_attributes( DOMElement $element, array $attributes ): void
remove_attributes( DOMElement $element, array $attributes ): void

Classes:

get_classes( DOMElement $element ): array
add_classes( DOMElement $element, array $classes ): void
remove_classes( DOMElement $element, array $classes ): void
has_classes( DOMElement $element, array $classes ): bool

Styles:

get_styles( DOMElement $element ): array
add_styles( DOMElement $element, array $styles ): void

Structure:

wrap( DOMElement $element, string $wrapper_tag, array $attributes = [] ): ?DOMElement
unwrap( DOMElement $element ): bool
change_tag_name(string $name, DOMElement $element ): ?DOMElement
insert_before( DOMElement $target, $content ): bool
insert_after( DOMElement $target, $content ): bool
replace_with( DOMElement $target, $content ): bool
clone_element( DOMElement $element, bool $deep = true ): DOMElement

CSS Class

string_to_array( string $style_string ): array
array_to_string( array $styles ): string

Error Handling

All methods return null, false, or empty arrays for invalid inputs rather than throwing exceptions, making them safe for direct use in conditionals.

arraypress / wp-dom-utils

Maintainers

Details