[RFC] Provide matching sequence on XML\Reader

[veewee]

RFC

Q	A
New Feature	yes
RFC	yes
BC Break	yes

Summary

This would be a BC break!

Currently, the reader yields only the XML strings that match your criteria.
It could make sense to wrap that string-result with some kind of MatchingNode class.
That way, it is possible to detect some more information about the match.

For example:

final class MatchingNode
{
    public function __construct(
        public readonly string $xml,
        public readonly NodeSequence $sequence,
    ){
    }
}

So given this reader:

$reader = Reader::fromXmlString(<<<'EOXML'
    <root>
        <products>
            <item>Product 1</item>
            <item>Product 2</item>
        </products>
        <categories>
            <item>Category 1</item>
            <item>Category 2</item>
        </categories>
    </root>
EOXML
);

You could match on both products and categories items all at once, and make it possible to segment them again in 1 go.

$matches = $reader->provide(Matcher\element_name('item');


foreach ($matches as $match) {
    $xml = $match->xml;
    $isProducts = $match->sequence->at(1)?->name === 'products';

}

[Sammyjo20]

I think providing the outer “NodeSequence” in each iteration is great, then I assume they’ll be a method like “->getXml()” or something to get what you have currently?

[veewee]

Yes, the yielded match object would contain both the XML string (what we have right now) and the sequence of the match.
It's not the outer sequence (as-in parents only), but in the example above it would be similar to either of those:

• root > products > item
• root > categories > item

depending on what it mached on.

(just using a breadcrumbs-like notation here, it are actually DTOs which contain more information about the element, it's parent tree and attributes)