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.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GPL-2.0-or-later License.

Support

• Documentation
• Issue Tracker