Add default SoapHeaders middleware

[veewee]

Feature Request

Q	A
New Feature	yes
RFC	no
BC Break	no

Summary

See phpro/soap-client#413.

We currently don't have an easy way of adding Soap headers through middleware.

The provided exmaple could be added in the set of middleware:

<?php

use Http\Client\Common\Plugin;
use Http\Promise\Promise;
use Psr\Http\Message\RequestInterface;
use Soap\Psr18Transport\Xml\XmlMessageManipulator;
use Soap\Xml\Builder\SoapHeaders;
use Soap\Xml\Manipulator\PrependSoapHeaders;
use VeeWee\Xml\Dom\Document;

class SoapHeaderMiddleware implements Plugin
{
    /**
     * @var list<callable(DOMNode): DOMElement>
     */
    private array $configurators;

    /**
     * @no-named-arguments
     * @param list<callable(DOMNode): DOMElement> $configurators
     */
    public function __construct(callable ... $configurators)
    {
        $this->configurators = $configurators;
    }

    public function handleRequest(RequestInterface $request, callable $next, callable $first): Promise
    {
        return $next((new XmlMessageManipulator)(
            $request,
            function (Document $document) {
                $headers = $document->build(new SoapHeaders($this->configurators))[0];

                return $document->manipulate(new PrependSoapHeaders($headers));
            }
        ));
    }
}

❗ We might want to introduce a default interface in engine for soap headers - which can also be used in ext-soap-engine: $client->__setSoapHeaders(...);