FileMaster

Edit File: class-html2text.php

<?php
/**
 * HTML to Text Converter class
 *
 * This file was extracted from the `soundasleep/html2text` package.
 * Copyright (c) 2019 Jevon Wright
 * MIT License
 *
 * @package Automattic\WooCommerce\EmailEditor
 */

declare( strict_types = 1 );

namespace Automattic\WooCommerce\EmailEditor\Engine\Renderer;

/**
 * Converts HTML into plain text format suitable for email display
 *
 * Features:
 * - Maintains links with href copied over
 * - Information in the <head> is lost
 * - Handles various HTML elements appropriately for text conversion
 */
class Html2Text {

/**
	 * Default options for HTML to text conversion
	 *
	 * @return array<string, bool|string> Default options array.
	 */
	public static function default_options(): array {
		return array(
			'ignore_errors' => false,
			'drop_links'    => false,
			'char_set'      => 'auto',
		);
	}

/**
	 * Converts HTML into plain text format
	 *
	 * @param string                             $html    The input HTML.
	 * @param boolean|array<string, bool|string> $options Conversion options.
	 * @return string The HTML converted to text.
	 * @throws Html2Text_Exception|\InvalidArgumentException If the HTML could not be loaded or invalid options are provided.
	 */
	public static function convert( string $html, $options = array() ): string {

if ( false === $options || true === $options ) {
			// Using old style (< 1.0) of passing in options.
			$options = array( 'ignore_errors' => $options );
		}

$options = array_merge( static::default_options(), $options );

// Check all options are valid.
		foreach ( array_keys( $options ) as $key ) {
			if ( ! in_array( $key, array_keys( static::default_options() ), true ) ) {
				// Log invalid option for debugging purposes without exposing in exception.
				// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Security: Logging sensitive data separately from user-facing exception messages.
				error_log( 'Html2Text: Invalid option provided: ' . htmlspecialchars( (string) $key, ENT_QUOTES, 'UTF-8' ) . '. Valid options are: ' . htmlspecialchars( implode( ',', array_keys( static::default_options() ) ), ENT_QUOTES, 'UTF-8' ) );
				// Throw generic error message to avoid exposing user input.
				throw new \InvalidArgumentException( 'Invalid option provided for html2text conversion.' );
			}
		}

$is_office_document = self::is_office_document( $html );

if ( $is_office_document ) {
			// Remove office namespace.
			$html = str_replace( array( '<o:p>', '</o:p>' ), '', $html );
		}

$html = self::fix_newlines( $html );

// Use mb_convert_encoding for legacy versions of php.
		if ( PHP_MAJOR_VERSION * 10 + PHP_MINOR_VERSION < 81 && mb_detect_encoding( $html, 'UTF-8', true ) ) {
			$converted = mb_convert_encoding( $html, 'HTML-ENTITIES', 'UTF-8' );
			$html      = false !== $converted ? $converted : $html;
		}

// Ensure $html is always a string before passing to get_document.
		if ( ! is_string( $html ) ) {
			$html = (string) $html;
		}

$doc = self::get_document( $html, $options );

$output = self::iterate_over_node( $doc, null, false, $is_office_document, $options );

// Process output for whitespace/newlines.
		$output = self::process_whitespace_newlines( $output );

return $output;
	}

/**
	 * Unify newlines
	 *
	 * Converts \r\n to \n, and \r to \n. This means that all newlines
	 * (Unix, Windows, Mac) all become \ns.
	 *
	 * @param string $text Text with any number of \r, \r\n and \n combinations.
	 * @return string The fixed text.
	 */
	public static function fix_newlines( string $text ): string {
		// Replace \r\n to \n.
		$text = str_replace( "\r\n", "\n", $text );
		// Remove \rs.
		$text = str_replace( "\r", "\n", $text );

return $text;
	}

/**
	 * Get non-breaking space character codes
	 *
	 * @return array<string> Array of nbsp codes.
	 */
	public static function nbsp_codes(): array {
		return array(
			"\xc2\xa0",
			"\u00a0",
		);
	}

/**
	 * Get zero-width non-joiner character codes
	 *
	 * @return array<string> Array of zwnj codes.
	 */
	public static function zwnj_codes(): array {
		return array(
			"\xe2\x80\x8c",
			"\u200c",
		);
	}

/**
	 * Remove leading or trailing spaces and excess empty lines from provided multiline text
	 *
	 * @param string $text Multiline text with any number of leading or trailing spaces or excess lines.
	 * @return string The fixed text.
	 */
	public static function process_whitespace_newlines( string $text ): string {

// Remove excess spaces around tabs.
		$result = preg_replace( '/ *\t */im', "\t", $text );
		$text   = null !== $result ? $result : $text;

// Remove leading whitespace.
		$text = ltrim( $text );

// Remove leading spaces on each line.
		$result = preg_replace( "/\n[ \t]*/im", "\n", $text );
		$text   = null !== $result ? $result : $text;

// Convert non-breaking spaces to regular spaces to prevent output issues,
		// do it here so they do NOT get removed with other leading spaces, as they
		// are sometimes used for indentation.
		$text = self::render_text( $text );

// Remove trailing whitespace.
		$text = rtrim( $text );

// Remove trailing spaces on each line.
		$result = preg_replace( "/[ \t]*\n/im", "\n", $text );
		$text   = null !== $result ? $result : $text;

// Unarmor pre blocks.
		$text = self::fix_newlines( $text );

// Remove unnecessary empty lines.
		$result = preg_replace( "/\n\n\n*/im", "\n\n", $text );

return null !== $result ? $result : $text;
	}

/**
	 * Can we guess that this HTML is generated by Microsoft Office?
	 *
	 * @param string $html The HTML content.
	 * @return bool True if this appears to be an Office document.
	 */
	public static function is_office_document( string $html ): bool {
		return strpos( $html, 'urn:schemas-microsoft-com:office' ) !== false;
	}

/**
	 * Check if text is whitespace
	 *
	 * @param string $text The text to check.
	 * @return bool True if the text is whitespace.
	 */
	public static function is_whitespace( string $text ): bool {
		return 0 === strlen( trim( self::render_text( $text ), "\n\r\t " ) );
	}

/**
	 * Parse HTML into a DOMDocument
	 *
	 * @param string                     $html    The input HTML.
	 * @param array<string, bool|string> $options Parsing options.
	 * @return \DOMDocument The parsed document tree.
	 * @throws Html2Text_Exception If the HTML could not be loaded.
	 */
	private static function get_document( string $html, array $options ): \DOMDocument {

$doc = new \DOMDocument();

$html = trim( $html );

if ( ! $html ) {
			// DOMDocument doesn't support empty value and throws an error.
			// Return empty document instead.
			return $doc;
		}

if ( '<' !== $html[0] ) {
			// If HTML does not begin with a tag, we put a body tag around it.
			// If we do not do this, PHP will insert a paragraph tag around
			// the first block of text for some reason which can mess up
			// the newlines. See pre.html test for an example.
			$html = '<body>' . $html . '</body>';
		}

$header = '';
		// Use char sets for modern versions of php.
		if ( PHP_MAJOR_VERSION * 10 + PHP_MINOR_VERSION >= 81 ) {
			// Use specified char_set, or auto detect if not set.
			$char_set = ! empty( $options['char_set'] ) && is_string( $options['char_set'] ) ? $options['char_set'] : 'auto';
			if ( 'auto' === $char_set ) {
				$detected = mb_detect_encoding( $html );
				$char_set = false !== $detected ? $detected : 'UTF-8';
			} elseif ( strpos( $char_set, ',' ) !== false ) {
				$encoding_list = explode( ',', $char_set );
				$encoding_list = array_map( 'trim', $encoding_list );
				$encoding_list = array_filter(
					$encoding_list,
					function ( $encoding ) {
						return ! empty( $encoding );
					}
				);
				if ( ! empty( $encoding_list ) ) {
					// Ensure we have a proper list with consecutive integer keys.
					$encoding_list = array_values( $encoding_list );
					mb_detect_order( $encoding_list );
					$detected = mb_detect_encoding( $html );
					$char_set = false !== $detected ? $detected : 'UTF-8';
				}
			}
			// Turn off error detection for Windows-1252 legacy html.
			if ( strpos( $char_set, '1252' ) !== false ) {
				$options['ignore_errors'] = true;
			}
			$header = '<?xml version="1.0" encoding="' . $char_set . '">';
		}

if ( ! empty( $options['ignore_errors'] ) ) {
			// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
			$doc->strictErrorChecking = false;
			// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
			$doc->recover = true;
			// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
			$doc->xmlStandalone  = true;
			$old_internal_errors = libxml_use_internal_errors( true );
			$load_result         = $doc->loadHTML( $header . $html, LIBXML_NOWARNING | LIBXML_NOERROR | LIBXML_NONET | LIBXML_PARSEHUGE );
			libxml_use_internal_errors( $old_internal_errors );
		} else {
			$load_result = $doc->loadHTML( $header . $html );
		}

if ( ! $load_result ) {
			// Log truncated HTML content for debugging purposes (limit to 500 chars to prevent log bloat).
			$html_preview = strlen( $html ) > 500 ? substr( $html, 0, 500 ) . '...[truncated]' : $html;
			// phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Security: Logging sensitive data separately from user-facing exception messages.
			error_log( 'Html2Text: Failed to load HTML content: ' . htmlspecialchars( $html_preview, ENT_QUOTES, 'UTF-8' ) );
			// Throw a generic error message to avoid exposing sensitive data.
			throw new Html2Text_Exception( 'Could not load HTML - the content may be malformed.' );
		}

return $doc;
	}

/**
	 * Replace any special characters with simple text versions
	 *
	 * This prevents output issues:
	 * - Convert non-breaking spaces to regular spaces; and
	 * - Convert zero-width non-joiners to '' (nothing).
	 *
	 * This is to match our goal of rendering documents as they would be rendered
	 * by a browser.
	 *
	 * @param string $text The text to process.
	 * @return string The processed text.
	 */
	private static function render_text( string $text ): string {
		$text = str_replace( self::nbsp_codes(), ' ', $text );
		$text = str_replace( self::zwnj_codes(), '', $text );
		return $text;
	}

/**
	 * Get the next child name
	 *
	 * @param \DOMNode|null $node The node to check.
	 * @return string|null The next child name.
	 */
	private static function next_child_name( ?\DOMNode $node ): ?string {
		// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
		if ( null === $node || null === $node->nextSibling ) {
			return null;
		}

// Get the next child.
		// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
		$next_node = $node->nextSibling;
		while ( null !== $next_node ) {
			if ( $next_node instanceof \DOMText ) {
				// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
				if ( ! self::is_whitespace( $next_node->wholeText ) ) {
					break;
				}
			}

if ( $next_node instanceof \DOMElement ) {
				break;
			}

// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
			$next_node = $next_node->nextSibling;
		}

$next_name = null;
		if ( $next_node instanceof \DOMElement || $next_node instanceof \DOMText ) {
			// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
			$next_name = strtolower( $next_node->nodeName );
		}

return $next_name;
	}

/**
	 * Iterate over a DOM node and convert to text
	 *
	 * @param \DOMNode                   $node                The DOM node.
	 * @param string|null                $prev_name           Previous node name.
	 * @param bool                       $in_pre              Whether we're in a pre block.
	 * @param bool                       $is_office_document  Whether this is an Office document.
	 * @param array<string, bool|string> $options             Conversion options.
	 * @return string The converted text.
	 */
	private static function iterate_over_node( \DOMNode $node, ?string $prev_name, bool $in_pre, bool $is_office_document, array $options ): string {
		if ( $node instanceof \DOMText ) {
			// Replace whitespace characters with a space (equivalent to \s).
			if ( $in_pre ) {
				// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
				$text = "\n" . trim( self::render_text( $node->wholeText ), "\n\r\t " ) . "\n";

// Remove trailing whitespace only.
				$result = preg_replace( "/[ \t]*\n/im", "\n", $text );
				$text   = null !== $result ? $result : $text;

// Armor newlines with \r.
				return str_replace( "\n", "\r", $text );
			}
			// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
			$text   = self::render_text( $node->wholeText );
			$result = preg_replace( "/[\\t\\n\\f\\r ]+/im", ' ', $text );
			$text   = null !== $result ? $result : $text;

if ( ! self::is_whitespace( $text ) && ( 'p' === $prev_name || 'div' === $prev_name ) ) {
				return "\n" . $text;
			}
			return $text;
		}

if ( $node instanceof \DOMDocumentType || $node instanceof \DOMProcessingInstruction ) {
			// Ignore.
			return '';
		}

// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
		$name      = strtolower( $node->nodeName );
		$next_name = self::next_child_name( $node );

// Start whitespace.
		switch ( $name ) {
			case 'hr':
				$prefix = '';
				if ( null !== $prev_name ) {
					$prefix = "\n";
				}
				return $prefix . "---------------------------------------------------------------\n";

case 'style':
			case 'head':
			case 'title':
			case 'meta':
			case 'script':
				// Ignore these tags.
				return '';

case 'h1':
			case 'h2':
			case 'h3':
			case 'h4':
			case 'h5':
			case 'h6':
			case 'ol':
			case 'ul':
			case 'pre':
				// Add two newlines.
				$output = "\n\n";
				break;

case 'td':
			case 'th':
				// Add tab char to separate table fields.
				$output = "\t";
				break;

case 'p':
				// Microsoft exchange emails often include HTML which, when passed through
				// html2text, results in lots of double line returns everywhere.
				//
				// To fix this, for any p element with a className of `MsoNormal` (the standard
				// classname in any Microsoft export or outlook for a paragraph that behaves
				// like a line return) we skip the first line returns and set the name to br.
				if ( $is_office_document && $node instanceof \DOMElement && 'MsoNormal' === $node->getAttribute( 'class' ) ) {
					$output = '';
					$name   = 'br';
					break;
				}

// Add two lines.
				$output = "\n\n";
				break;

case 'tr':
				// Add one line.
				$output = "\n";
				break;

case 'div':
				$output = '';
				if ( null !== $prev_name ) {
					// Add one line.
					$output .= "\n";
				}
				break;

case 'li':
				$output = '- ';
				break;

default:
				// Print out contents of unknown tags.
				$output = '';
				break;
		}

// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
		if ( $node->childNodes->length > 0 ) {

// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
			$n                      = $node->childNodes->item( 0 );
			$previous_sibling_names = array();
			$previous_sibling_name  = null;
			$parts                  = array();
			$trailing_whitespace    = 0;

while ( null !== $n ) {

$text = self::iterate_over_node( $n, $previous_sibling_name, $in_pre || 'pre' === $name, $is_office_document, $options );

// Pass current node name to next child, as previousSibling does not appear to get populated.
				if ( $n instanceof \DOMDocumentType
					|| $n instanceof \DOMProcessingInstruction
					|| ( $n instanceof \DOMText && self::is_whitespace( $text ) ) ) {
					// Keep current previousSiblingName, these are invisible.
					++$trailing_whitespace;
				} else {
					// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
					$previous_sibling_name    = strtolower( $n->nodeName );
					$previous_sibling_names[] = $previous_sibling_name;
					$trailing_whitespace      = 0;
				}

$node->removeChild( $n );
				// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase
				$n = $node->childNodes->item( 0 );

$parts[] = $text;
			}

// Remove trailing whitespace, important for the br check below.
			while ( $trailing_whitespace-- > 0 ) {
				array_pop( $parts );
			}

// Suppress last br tag inside a node list if follows text.
			$last_name = array_pop( $previous_sibling_names );
			if ( 'br' === $last_name ) {
				$last_name = array_pop( $previous_sibling_names );
				if ( '#text' === $last_name ) {
					array_pop( $parts );
				}
			}

$output .= implode( '', $parts );
		}

// End whitespace.
		switch ( $name ) {
			case 'h1':
			case 'h2':
			case 'h3':
			case 'h4':
			case 'h5':
			case 'h6':
			case 'pre':
			case 'p':
				// Add two lines.
				$output .= "\n\n";
				break;

case 'br':
				// Add one line.
				$output .= "\n";
				break;

case 'div':
				break;

case 'a':
				// Links are returned in [text](link) format.
				$href = $node instanceof \DOMElement ? $node->getAttribute( 'href' ) : '';

$output = trim( $output );

// Remove double [[ ]] s from linking images.
				if ( '[' === substr( $output, 0, 1 ) && ']' === substr( $output, -1 ) ) {
					$output = substr( $output, 1, strlen( $output ) - 2 );

// For linking images, the title of the <a> overrides the title of the <img>.
					if ( $node instanceof \DOMElement && $node->getAttribute( 'title' ) ) {
						$output = $node->getAttribute( 'title' );
					}
				}

// If there is no link text, but a title attr.
				if ( ! $output && $node instanceof \DOMElement && $node->getAttribute( 'title' ) ) {
					$output = $node->getAttribute( 'title' );
				}

if ( ! $href ) {
					// It doesn't link anywhere.
					if ( $node instanceof \DOMElement && $node->getAttribute( 'name' ) ) {
						if ( $options['drop_links'] ) {
							$output = "$output";
						} else {
							$output = "[$output]";
						}
					}
				} elseif ( $href === $output || "mailto:$output" === $href || "http://$output" === $href || "https://$output" === $href ) {
					// Link to the same address: just use link.
					$output = "$output";
				} elseif ( $output ) {
					// Replace it.
					if ( $options['drop_links'] ) {
						$output = "$output";
					} else {
						$output = "[$output]($href)";
					}
				} else {
					// Empty string.
					$output = "$href";
				}

// Does the next node require additional whitespace?
				switch ( $next_name ) {
					case 'h1':
					case 'h2':
					case 'h3':
					case 'h4':
					case 'h5':
					case 'h6':
						$output .= "\n";
						break;
				}
				break;

case 'img':
				if ( $node instanceof \DOMElement && $node->getAttribute( 'title' ) ) {
					$output = '[' . $node->getAttribute( 'title' ) . ']';
				} elseif ( $node instanceof \DOMElement && $node->getAttribute( 'alt' ) ) {
					$output = '[' . $node->getAttribute( 'alt' ) . ']';
				} else {
					$output = '';
				}
				break;

case 'li':
				$output .= "\n";
				break;

case 'blockquote':
				// Process quoted text for whitespace/newlines.
				$output = self::process_whitespace_newlines( $output );

// Add leading newline.
				$output = "\n" . $output;

// Prepend '> ' at the beginning of all lines.
				$result = preg_replace( "/\n/im", "\n> ", $output );
				$output = null !== $result ? $result : $output;

// Replace leading '> >' with '>>'.
				$result = preg_replace( "/\n> >/im", "\n>>", $output );
				$output = null !== $result ? $result : $output;

// Add another leading newline and trailing newlines.
				$output = "\n" . $output . "\n\n";
				break;
			default:
				// Do nothing.
		}

return $output;
	}
}

Back