Make namespace declaration eager

[Jean85]

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

I was upgrading from phpro/soap-client v3 to v4, and it changed how namespaces are declared, breaking my integration with Microsoft Business Central (BC).

BC is unfortunately picky, and it breaks if all namespaces are not declared at the top, on the envelope node. Would it be possible to have a flag/feature that I can enable to bring back the old behavior? Right now I had to hack a workaround by rewriting the XML at the transport level, with a transport wrapper.

[veewee]

Thanks for reporting!

The current behavior is by design — each encoder is isomorphic (encoding/decoding are mirror operations), so namespace declarations end up on the elements that use them. This is semantically valid XML — any spec-compliant XML parser should handle it fine regardless of where the declarations appear.

That said, I'm curious about a few things:

• What errors does Business Central actually return? It's surprising that they'd be sensitive to where namespaces are declared — that shouldn't matter to any proper XML parser. Understanding the exact failure would help determine what actually needs to change.
• What does your transport-level workaround look like? You mentioned rewriting the XML — are you hoisting declarations to the envelope, renaming prefixes, or something else entirely?

There is an optimize_namespaces utility in veewee/xml that consolidates and renames namespace declarations to the root element. It could be applied as a post-processing step on the generated XML — for example at the transport layer, which is essentially what you're already doing. Though it does rename prefixes, which could cause issues with xsi:type attribute values in SOAP encoded mode.

We're open to exploring options here, but want to better understand the actual problem before committing to a direction. Could you share the error response from BC and your current workaround? That would help a lot.

[Jean85]

Thank you for your swift and thorough response! I'll list all the details below:

• BC error: the error response that I see is
  Imported XML cannot validate with the schema: The 'tns' attribute is not declared (Code:a:Microsoft.Dynamics.Nav.Types.Exceptions.NavNCLXmlPortInvalidXmlException)
  where tns is the first namespace prefix being used.
• my transport level hack is very dirty, and looks like this:
  I wrap the transport before creating the client:

        $this->transport = new EagerEnvelopeNamespaceTransport(
            Psr18Transport::createForClient($this->soapNtlmClient)
        );

The wrapper rewrites the SOAP request on the fly using SoapEnvelopeNamespacePromoter

final readonly class EagerEnvelopeNamespaceTransport implements Transport
{
    public function __construct(
        private Transport $inner,
        private SoapEnvelopeNamespacePromoter $namespacePromoter = new SoapEnvelopeNamespacePromoter(),
    ) {}

    public function request(SoapRequest $request): SoapResponse
    {
        $body = $this->namespacePromoter->promote($request->getRequest());
        if ($body === $request->getRequest()) {
            return $this->inner->request($request);
        }

        $rewritten = new SoapRequest(
            $body,
            $request->getLocation(),
            $request->getAction(),
            $request->getVersion(),
            $request->getOneWay(),
        );

        return $this->inner->request($rewritten);
    }
}

SoapEnvelopeNamespacePromoter does the dirty work:

final class SoapEnvelopeNamespacePromoter
{
    public function promote(string $xml): string
    {
        $dom = new DOMDocument();
        $dom->preserveWhiteSpace = true;
        $dom->formatOutput = false;

        if ($dom->loadXML($xml, LIBXML_NONET) !== true) {
            return $xml;
        }

        $envelope = $dom->documentElement;
        if (! $envelope instanceof DOMElement || strtolower((string) $envelope->localName) !== 'envelope') {
            return $xml;
        }

        $bindings = $this->readPrefixedXmlnsBindings($envelope);
        $this->liftPrefixedXmlnsOntoEnvelope($envelope, $bindings);

        $out = $dom->saveXML();
        if ($out === false || $out === '') {
            return $xml;
        }

        return $out;
    }
// ...

Thank you for the optimize_namespaces suggestion, I'll take a look to see if I can leverage it instead of this hack in the meantime.

[Jean85]

Unfortunately, optimize_namespaces doesn't work, I get this error from BC:

SOAP Fault: Imported XML cannot validate with the schema: The 'ns2' attribute is not declared. (Code:a:Microsoft.Dynamics.Nav.Types.Exceptions.NavNCLXmlPortInvalidXmlException) 

I see the NS declared correctly, but I fear not using SOAP-ENV at the top breaks something. If I pass the prefix, it goes SOAP-ENV1, SOAP-ENV2 etc, so it's a no go regardless.

[veewee]

Thanks for the detailed follow-up — that's really helpful!

Looking at the error message more closely: "The 'tns' attribute is not declared" — this looks like BC is running XSD validation on the request, and the schema expects specific prefixes to be declared on the envelope. That explains why optimize_namespaces doesn't work either: it renames prefixes to ns1, ns2, etc., and the schema expects the original ones.

So what's needed is a hoist operation: move namespace declarations to the envelope element while preserving the original prefixes. Which is essentially what your SoapEnvelopeNamespacePromoter already does.

Why not add this to the encoder directly? The encoder produces semantically correct XML — every encoder is isomorphic (encoding and decoding are mirror operations), and adding post-processing to work around server-side validation quirks would break that symmetry. The encoder shouldn't need to know about the expectations of specific servers. This kind of XML rewriting belongs in the HTTP layer, where you can opt into it per-service.

Here's the plan going forward:

1. A hoist_namespaces function will be added to veewee/xml v4 — this is a general-purpose XML operation that belongs there.
2. php-soap will move to veewee/xml v4 (which requires PHP 8.4+ due to the new spec-compliant DOM layer) — this is a broader migration that touches multiple php-soap components.
3. The recommended integration point is an HTTP middleware. The psr18-transport package already has a pattern for XML manipulation through middleware. Once the hoist function is available, we could ship a ready-made HoistNamespacesMiddleware there so you don't have to roll your own.

This will take some time since the veewee/xml v4 migration is a larger effort. In the meantime, your transport-level workaround is the right approach — you're essentially doing what the hoist function will do.

[Jean85]

That explains why optimize_namespaces doesn't work either: it renames prefixes to ns1, ns2, etc., and the schema expects the original ones.

That is a wrong assumption: my workaround changes the prefixes too, and that is not breaking the functionality. It seems BC is only requiring the hoisting, and (maybe?) the SOAP-ENV prefix for the envelope.

[veewee]

Ah ok, then I understood wrong.

Can you share what's inside this as well?

        $bindings = $this->readPrefixedXmlnsBindings($envelope);
        $this->liftPrefixedXmlnsOntoEnvelope($envelope, $bindings);

[Jean85]

I just refactored it to leverage XPath, here's the full implementation:

final class SoapEnvelopeNamespacePromoter
{
    private const string XMLNS_NS = 'http://www.w3.org/2000/xmlns/';

    public function promote(string $xml): string
    {
        $dom = new DOMDocument();
        $dom->preserveWhiteSpace = true;
        $dom->formatOutput = false;

        if (@$dom->loadXML($xml, LIBXML_NONET) !== true) {
            throw new \InvalidArgumentException('Unable to parse XML');
        }

        $envelope = $dom->documentElement;
        if (! $envelope instanceof DOMElement || strtolower((string) $envelope->localName) !== 'envelope') {
            throw new \InvalidArgumentException('Unable to parse envelope');
        }

        $bindings = $this->readPrefixedXmlnsBindings($envelope);
        $this->liftPrefixedXmlnsOntoEnvelope($envelope, $bindings);

        $out = $dom->saveXML();
        if ($out === false || $out === '') {
            return $xml;
        }

        return $out;
    }

    /**
     * @return array<string, string> prefix => namespace URI
     */
    private function readPrefixedXmlnsBindings(DOMElement $element): array
    {
        $map = [];
        foreach ($this->prefixedXmlnsAttributeNames($element) as $name) {
            $map[$this->prefixFromXmlnsAttributeName($name)] = $element->getAttribute($name);
        }

        return $map;
    }

    /**
     * @param array<string, string> $bindings
     */
    private function liftPrefixedXmlnsOntoEnvelope(DOMElement $envelope, array &$bindings): void
    {
        $ownerDocument = $envelope->ownerDocument;
        if ($ownerDocument === null) {
            return;
        }

        $xpath = new DOMXPath($ownerDocument);
        $nodesWithXmlns = $xpath->query('//*[namespace::*]');
        if ($nodesWithXmlns === false) {
            return;
        }

        foreach ($nodesWithXmlns as $node) {
            if (! $node instanceof DOMElement || $node === $envelope) {
                continue;
            }

            foreach ($this->prefixedXmlnsAttributeNames($node) as $name) {
                $prefix = $this->prefixFromXmlnsAttributeName($name);
                $uri = $node->getAttribute($name);
                if (! isset($bindings[$prefix])) {
                    $envelope->setAttributeNS(self::XMLNS_NS, 'xmlns:' . $prefix, $uri);
                    $bindings[$prefix] = $uri;
                    $node->removeAttribute($name);
                } elseif ($bindings[$prefix] === $uri) {
                    $node->removeAttribute($name);
                }
            }
        }
    }

    /**
     * @return list<string> e.g. ['xmlns:tns', ...]
     */
    private function prefixedXmlnsAttributeNames(DOMElement $element): array
    {
        return array_values(array_filter(
            $element->getAttributeNames(),
            static fn(string $name): bool => str_starts_with($name, 'xmlns:'),
        ));
    }

    private function prefixFromXmlnsAttributeName(string $xmlnsAttributeName): string
    {
        return substr($xmlnsAttributeName, \strlen('xmlns:'));
    }
}

Namespace prefixes are preserved, but they are changes at the start from the v4 implementation; I have some E2E tests where I compare the final produced XML, that's why I know that for sure.

[veewee]

Thanks for the full implementation and the correction!

One thing I want to clarify: you mention "my workaround changes the prefixes too," but looking at your SoapEnvelopeNamespacePromoter, it only promotes declarations to the envelope without renaming any prefixes.

Could it be that the prefix differences you're seeing come from the switch between ext-soap and this library? ext-soap typically uses shortened namespace prefixes (like ns1, ns2), while this encoder uses the prefixes as defined in the WSDL (like tns). That's a separate difference from the promoting itself.

[Jean85]

As I said above:

Namespace prefixes are preserved, but they are changes at the start from the v4 implementation; I have some E2E tests where I compare the final produced XML, that's why I know that for sure.

The changes to the prefixes come from the code before my workaround, and the change there comes from upgrading from phpro/soap-client v3 to v4

[veewee]

I've created a first implementation of promote_namespaces in veewee/xml: veewee/xml#103

If you want to try it out, you can require the branch in your composer.json:

{
    "require": {
        "veewee/xml": "dev-feature/promote-namespaces"
    }
}

This requires veewee/xml v4 and PHP 8.4+, which means upgrading to soap-client v6 (you mentioned being on v4).

The recommended approach would be an HTTP middleware instead of a transport wrapper:

use Http\Client\Common\Plugin;
use Http\Promise\Promise;
use Psr\Http\Message\RequestInterface;
use Soap\Psr18Transport\Xml\XmlMessageManipulator;
use VeeWee\Xml\Dom\Document;
use function VeeWee\Xml\Dom\Manipulator\Document\promote_namespaces;

class PromoteNamespacesMiddleware implements Plugin
{
    public function handleRequest(RequestInterface $request, callable $next, callable $first): Promise
    {
        $request = (new XmlMessageManipulator)(
            $request,
            fn (Document $document) => $document->manipulate(
                promote_namespaces(...)
            )
        );

        return $next($request);
    }
}

Then register it in your plugin client:

use Http\Client\Common\PluginClient;

$httpClient = new PluginClient(
    $psr18Client,
    [
        new PromoteNamespacesMiddleware(),
    ]
);