[Proposal]: Add a new `DOMElementParent` function

[stloyd]

Describe the Proposal

Using CSS selectors on the DOM is harder than using XPath, as you don't have access to the parent of the found element. But DOM elements hold this information internally as object relations:

$document = HTMLDocument::createFromString('<article><section><h1>User Name</h1></section><span>01</span></article>');
$document->querySelector('section h1')->parentElement; // <section> relation
$document->querySelector('span')->parentElement; // <article> relation

API Adjustments

final class DOMElementParent extends ScalarFunctionChain
{
    public function __construct(
        private readonly ScalarFunction|\DOMNode|HTMLElement $element,
    ) {
    }

    public function eval(Row $row, FlowContext $context) : \DOMNode|HTMLElement|null
    {
         // ...

        if ($node instanceof \DOMNode || $node instanceof HTMLElement) {
            return $node->parentElement;
        }

        return null;
    }
}

Are you intending to also work on proposed change?

Yes

Are you interested in sponsoring this change?

None

Integration & Dependencies

No response