veewee/xml

XML without worries

<XML />

XML without worries

This package aims to provide all tools for dealing with XML in PHP without worries. You will find a type-safe, declarative API that deals with errors for you!

Installation

composer require veewee/xml

Components

• DOM: Operate on XML documents through the DOM API.
• Encoding: Provides xml_encode() and xml_decode() so that you can deal with XML just like you deal with JSON!
• ErrorHandling: Provides the tools you need to safely deal with XML.
• Reader: Memory-safe XML reader.
• Writer: Memory-safe XML writer.
• XSD: Tools for working with XSD schemas.
• XSLT: Transform XML documents into something else.

Roadmap

These components are not implemented yet, but have been thought about. Stay tuned if you want to use these!

• External: Saxon/C: XSLT 3.0/2.0, XQuery 3.1, XPath 3.1 and Schema Validation 1.0/1.1
  • Awaiting PHP8 support: https://saxonica.plan.io/issues/4842
• External: XSLT2 (prefer saxon/c)

About

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub. Please take a look at our rules before contributing your code.

License

veewee/xml is licensed under the MIT License.

xml's Issues

Use of mutation testing in xml - Help needed

Hello there!

My name is Ana. I noted that you use the mutation testing tool infection in the project.
I am a postdoctoral researcher at the University of Seville (Spain), and my colleagues and I are studying how mutation testing tools are used in practice. With this aim in mind, we have analysed over 3,500 public GitHub repositories using mutation testing tools, including yours! This work has recently been published in a journal paper available at https://link.springer.com/content/pdf/10.1007/s10664-022-10177-8.pdf.

To complete this study, we are asking for your help to understand better how mutation testing is used in practice, please! We would be extremely grateful if you could contribute to this study by answering a brief survey of 21 simple questions (no more than 6 minutes). This is the link to the questionnaire https://forms.gle/FvXNrimWAsJYC1zB9.

Drop me an e-mail if you have any questions or comments ([email protected]). Thank you very much in advance!!

xmlns:default added, how to remove?

Q	A
Version	2.6.0

Support Question

Firstly, awesome work on this package! I am testing this against some xml that is returned from a 3rd party api call. I am using xml_decode() then xml_encode() to see how to xml is transformed:

Before transformation:

...
<soapenv:Envelope
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
...

After transformation:

...
<soapenv:Envelope
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:xsd="http://www.w3.org/2001/XMLSchema"
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:default="urn:messages_2022_1.platform.webservices.netsuite.com">
...

There is an extra attribute added. In theory after decoding and encoding I should end up with the same xml string. Is there a certain configuration detail I am missing?

Feature: decode_from_element()

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

It could be handy to create a decode_from_element() function so that you could transform any XML DOMElement into the array structure. Otherwise you'll need to manually map it into xml before decoding it back again.

For example: decode a specific element inside the SOAP body.

Loading UTF-16 XML

Hi there,

it is possible to load/read xml with an encoding of UTF-16?

for example:

<?xml version="1.0" encoding="utf-16" standalone="yes"?>
<Response>
  <IsSuccessful>false</IsSuccessful>
  <Data></Data>
  <Errors>
    <Error>InsuredEmail required.</Error>
    <Error>AgentEmail required.</Error>
    <Error>InsuredEmail is not a valid e-mail address.</Error>
    <Error>AgentEmail is not a valid e-mail address.</Error>
  </Errors>
</Response>

loading with xml_decode or Document will result in
Could not load the DOM Document [FATAL] : Document labelled UTF-16 but has UTF-8 content (81) on line 1,38

thanks!

Fix PSL 2 support

Bug Report

Q	A
BC Break	no
Version

See new PRs:
#33, #34, #35

• Failing unit tests - assertions not working properly
• Autoload build failure due to usage of old function
• PSL psalm plugin not being registered

Currently PSL 2 is not supported by the codebase.
PSL 1 is not compatible with PSL 2.
Since PSL2 is only supporting PHP >=8.1 and we still support PHP 8.0 - it currently makes no sense to upgrade.
Once PHP 8.2 lands or PHP 8.0 support ends in this package, we can upgrade the internal API to use PSL 2.

In the meantime, PSL1 is still compatible with both PHP 8.1 and 8.0

Roadmap

I see my genkgo/xsl packages was on your roadmap. Too bad you didn't choose to use it ;).

Anyhow, since the number of XML/XSL dev in PHP is small, I do wanted to let you know that I am following the XRust project with interest. While it may seem not too active, do have a look at other branches than the main branch. To me that project is very promising, and combined with the PHP Enjoy Rust framework we can actually get XSL 2.0+ implemented in a good manner. You might consider to have that on your roadmap rather than my package or Saxon C.

Investigate spec compliance (PHP 84)

Feature Request

More info:

• https://externals.io/message/122363
• RFC : https://wiki.php.net/rfc/opt_in_dom_spec_compliance
• RFC : HTML5 separation : https://wiki.php.net/rfc/domdocument_html5_parser

WIP: Extended DOM

• nielsdos/php-src#93

Additional new PHP 84 RFCs:

• RFC : https://wiki.php.net/rfc/improve_callbacks_dom_and_xsl
• RFC : https://wiki.php.net/rfc/xmlreader_writer_streams

Branch php/php-src#13031

./buildconf --force
make clean
./configure --without-iconv --enable-mbstring --disable-opcache --with-xsl
make -j4
./sapi/cli/php -v

Investigation

General idea : create v4 (or higher) that requries PHP 8.4 and make the DOM layer spec compliant.
Downside : this drops support for all older PHP versions which will be annoying.
Both v3 and v4 could remain LTS branches that are compatible in functionality.
However, this would be a maintainence pain for at least for the coming 3-4 year.
It won't be possible to support both v3 and v4 in downstream repo's either, since the signatures of the callbacks will be different.

First steps

•  POC : Try to get current DOM layer working with the new spec-compliant version.

Document traverse works only once

I was trying to traverse the document tree and delete empty nodes, but it only works once. I.e it does traverse the document, finds all the node elements I need, but deletes only the first one it sees, discarding everything else.

I've checked the unit tests for Action\RemoveNode, and it only tests the deletion of the first attribute.

Feature: element_encode()

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

I have come across a scenario where I needed to generated a part of an xml document instead of the full document. The available helper functions only allow for generating full documents. It might be useful to have a helper function like element_encode().

Example full doc

$doc = [
    'Data' => [
        'Hello' => 'World',
        'Extra' => [
            'Lorem' => 'Ipsum',
        ],
    ],
];

xml_encode($doc);

Output

<?xml version="1.0"?>
<Data>
  <Hello>World</Hello>
  <Extra>
    <Lorem>Ipsum</Lorem>
  </Extra>
</Data>

Example partial doc

$element = [
    'Lorem' => 'Ipsum',
];

element_encode($element);

Output

<Lorem>Ipsum</Lorem>

Improve functions autloader

Feature Request

Q	A
New Feature	no
RFC	no
BC Break	no

Summary

Currently the autoloader requires all php files once.
It would be better to wrap a function_exists around all functions to make sure PHP doesn't end up with a fatal.

Fatal error: Cannot redeclare VeeWee\Xml\Dom\Assert\assert_attribute()

Q	A
Version	3.1.0

Support Question

I am using this library inside a Magento 2 project. When running a CLI command, I get an error related to this library:

$ bin/magento yireo_extensionchecker:scan --module Vendor_Module

Fatal error: Cannot redeclare VeeWee\Xml\Dom\Assert\assert_attribute() (previously declared in /var/www/html/vendor/veewee/xml/src/Xml/Dom/Assert/assert_attribute.php:15) in /var/www/html/vendor/veewee/xml/src/Xml/Dom/Assert/assert_attribute.php on line 17

I tried to debug the issue, but I cannot wrap my head around it. The issue pretty much says that in line 17 of /var/www/html/vendor/veewee/xml/src/Xml/Dom/Assert/assert_attribute.php, the method VeeWee\Xml\Dom\Assert\assert_attribute() is declared. However, line 17 doesn't declare a method at all:

xml/src/Xml/Dom/Assert/assert_attribute.php

Line 17 in 47504ae

return instance_of(DOMAttr::class)->assert($node);

I know it is a very poor issue, because it is not possible to reproduce this. I still wanted to ask you, whether you have any idea by chance? Have you seen this before?

Thanks!

[RFC] Provide matching sequence on XML\Reader

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';

}

forFile fails if file does not exist

Bug Report

When using forFile .. is_writeable fails if file not exists.

Summary

I always have to create an empty file before i can use this function, otherwise i get a runtime exception.

How to reproduce

Writer::forFile('test.xml')
    ->write(document('1.0', 'UTF-8'));

Current behaviour

PHP Fatal error: Uncaught Webmozart\Assert\InvalidArgumentException: The path "test.xml" is not writable

Expected behaviour

Create the file because the directory is writeable.