` markers at all) yields only a null-blockName freeform
* entry, which its own flatten() correctly skips, producing an EMPTY unit
* array for every such post. This class's DOMDocument walk has no such
* gap: block-comment markers parse as DOMComment nodes (never DOMElement),
* so they're simply invisible to the walk below, regardless of whether
* the source was a page builder's rendered output, a Classic Editor post,
* or genuine Gutenberg block HTML.
*
* Recognizes h1-h6/p/img/ul/ol as their own unit kinds (matched at any
* nesting depth, not only as direct children — see walk()). Anything else
* becomes kind 'other', but ONLY as a last resort: a wrapper element is
* recursed into first, and only falls back to one opaque 'other' unit for
* its whole subtree when that recursion finds nothing recognized inside
* it. This mirrors the block adapter's own recursive flatten() precedent
* (a container block's innerBlocks are walked, not swallowed whole) and
* is required for the byte-identical-score acceptance bar component 3
* works against: a real Gutenberg "Group" block, for one, renders its
* children inside a wrapper
the checks must still see through.
*
* Known, accepted residual gap (not new — the same class of imprecision
* regex-based checks already had): a wrapper mixing loose, unwrapped text
* with a nested recognized element (e.g. `
Loose text
...
`)
* loses that loose text — the wrapper isn't reduced to one 'other' unit
* (it has a recognized descendant, so it's recursed into, not opaque), and
* the loose text itself isn't inside any recognized or opaque unit either.
* On the raw_content path this is safe: wpautop()/Gutenberg both wrap loose
* text in a real tag, so real post_content essentially never produces this
* exact shape. On the rendered-page fallback path — which this adapter also
* serves as of component 3 — that guarantee does NOT hold: the markup there
* comes from a third-party page builder/theme, not from WordPress's own
* content-serialization functions, and a bare `
Loose text
` is
* plausible there. Not proven safe on that path; scope stays unchanged
* (flagged, not engineered around) rather than silently assumed covered.
*
* @package ABDS_SEO
*/
if ( ! defined( 'ABSPATH' ) ) {
exit;
}
/**
* Builds a ContentUnit sequence from a raw HTML string.
*/
class ABDS_SEO_Rendered_HTML_Content_Adapter {
const KIND_MAP = array(
'h1' => 'heading',
'h2' => 'heading',
'h3' => 'heading',
'h4' => 'heading',
'h5' => 'heading',
'h6' => 'heading',
'p' => 'paragraph',
'img' => 'image',
'ul' => 'list',
'ol' => 'list',
);
/**
* Converts raw HTML into a flat ContentUnit sequence, in document order.
*
* @param string $html Raw HTML — a content-boundary region (from
* ABDS_SEO_Content_Boundary_Detector::detect()) or
* a post's raw post_content directly.
* @return array
*/
public static function units_from_html( string $html ): array {
if ( '' === trim( $html ) ) {
return array();
}
$previous_state = libxml_use_internal_errors( true );
$dom = new DOMDocument();
$loaded = $dom->loadHTML(
'' . $html . '
',
LIBXML_NOERROR | LIBXML_NOWARNING
);
libxml_clear_errors();
libxml_use_internal_errors( $previous_state );
if ( ! $loaded ) {
return array();
}
$root = $dom->getElementById( 'abds-seo-root' );
if ( ! $root instanceof DOMElement ) {
return array();
}
return self::walk( $dom, $root );
}
/**
* Recursively collects units from $node's element children, in
* document order: a recognized tag becomes its own unit (not recursed
* into further — a heading/paragraph/image/list's own inner markup is
* never re-decomposed, same as the block adapter never re-walks a
* block's own innerHTML); anything else is recursed into, and only
* becomes a single opaque 'other' unit when that recursion finds
* nothing recognized inside it at all — see this class's own docblock
* for why a right-away 'other' (no recursion) would lose real content
* nested inside common wrapper elements (Gutenberg's Group block, for
* one).
*
* @param DOMDocument $dom Owning document (needed for saveHTML()).
* @param DOMElement $node Element whose children to walk.
* @return array
*/
protected static function walk( DOMDocument $dom, DOMElement $node ): array {
$units = array();
// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- childNodes is a native PHP DOM extension property, not this codebase's own naming.
foreach ( $node->childNodes as $child ) {
if ( ! $child instanceof DOMElement ) {
continue;
}
// phpcs:ignore WordPress.NamingConventions.ValidVariableName.UsedPropertyNotSnakeCase -- tagName is a native PHP DOM extension property, not this codebase's own naming.
$tag = strtolower( $child->tagName );
if ( isset( self::KIND_MAP[ $tag ] ) ) {
$units[] = self::unit_from_node( $dom, $child, self::KIND_MAP[ $tag ], $tag );
continue;
}
$nested = self::walk( $dom, $child );
if ( ! empty( $nested ) ) {
array_push( $units, ...$nested );
} else {
$units[] = self::unit_from_node( $dom, $child, 'other', $tag );
}
}
return $units;
}
/**
* Builds one ContentUnit from a matched or opaque DOM node.
*
* @param DOMDocument $dom Owning document (needed for saveHTML()).
* @param DOMElement $node Matched element.
* @param string $kind One of KIND_MAP's values, or 'other'.
* @param string $tag Lowercased tag name (already resolved by the caller).
* @return array{kind:string, level:?int, html:string, text:string, ref:string, source_type:string}
*/
protected static function unit_from_node( DOMDocument $dom, DOMElement $node, string $kind, string $tag ): array {
$html = (string) $dom->saveHTML( $node );
// For an
, "text" is meaningless (no inner text) — alt-text
// checks read the ref-matched unit's own html/attributes directly,
// not text, so an empty text value here doesn't lose information.
$text = 'image' === $kind ? '' : self::strip_html( $html );
return array(
'kind' => $kind,
'level' => 'heading' === $kind ? (int) substr( $tag, 1 ) : null,
'html' => $html,
'text' => $text,
'ref' => ABDS_SEO_Content_Ref::of( '' !== $text ? $text : $html ),
'source_type' => 'html:' . $tag,
);
}
/**
* Strips HTML down to plain, whitespace-normalized text — identical
* rule to ABDS_SEO_Block_Content_Adapter::strip_html(), duplicated
* rather than shared per that class's own documented precedent (each
* pure-logic adapter/checker keeps its own copy).
*
* @param string $text Text that may contain HTML.
* @return string
*/
protected static function strip_html( string $text ): string {
$text = (string) preg_replace( '@<(script|style)[^>]*?>.*?\\1>@si', ' ', $text );
$text = (string) preg_replace( '/<[^>]*>/', ' ', $text );
return trim( (string) preg_replace( '/\s+/u', ' ', $text ) );
}
}