Official SOAP Plugin for Saloon?

[Sammyjo20]

Hey y'all!

I understand that while SOAP is a pretty old standard, it's still used quite a lot in enterprise applications and older APIs. It's something that we've all probably come across in the past and not something that is going to change any time soon. Because of this, I am currently working on a cool concept for an official SOAP plugin for Saloon! 🤠

My motivation for this is to help people use one tool for all their API integrations (Saloon) - additionally, it would be amazing to use Saloon for these types of API integrations as we could make use of the Guzzle Sender and Saloon v3's PSR-7 request and response support - this means that if you're using a REST API or SOAP API - You still have connectors, requests and responses - and every other Saloon feature would work with it.

I don't want to spend loads of time and effort building something really fancy, so I'd rather build something minimal but useful for people to get up and running with their SOAP APIs. Because of this, I don't intend to build any kind of WSDL guessing or logic - you would need to define each XML request yourself - with the help of a few DTOs that the SOAP plugin will provide.

So far, I've come up with a new body trait that would be added (HasSoapBody), which will require a few methods to be defined to resolve the Envelope, Header, and body of the request. I'm thinking of providing some nice Saloon DTOs for writing the XML but allowing people to use array keys and values if the XML elements are simple. I'm also considering using Spatie's array-to-xml library to convert the XML behind the scenes.

As previously mentioned, all Saloon will do is convert the data into an XML string and send it with Guzzle, just like any other Saloon request - the plugin will just provide a beautiful, modern way of writing these SOAP requests.

Also just to be clear - this won't be bundled into Saloon by default - this will be a separate installable package with its own versioning.

Here's what I'm thinking. What do you all think? I have some questions below.

 // Normal Saloon Request

class GetUserRequest extends Request
{
    use HasSoapBody;
    
    protected function resolveSoapEnvelope(): SoapEnvelope
    {
        return new SoapEnvelope(
            namespaces: [
              'name' => 'url',
            ],
            attributes: [],
        );
    }
    
    protected function resolveSoapHeader(): ?SoapHeader
    {
        // Can be nullable to omit header
        
        return new SoapHeader(
            namespaces: [...],
            attributes: [...],
            content: [
                'HeaderOne' => 'Simple',
                'HeaderTwo' => new Element(attributes: []),
            ],
        );
    }
    
    protected function resolveSoapBody(): ?SoapBody
    {
        // Can be nullable to omit body
        
        return new SoapBody(
            namespaces: [...],
            attributes: [...],
            content: [
                'ElementOne' => 'Simple',
                'ElementTwo' => new Element(attributes: []),
            ],
        );
    }
}

Some questions for you -

• What do you think of it? Do you think an MVP without WSDL and all that stuff will be fine?
• Is there anything missing from this MVP?
• Do you think people would mind writing the XML in the form of arrays like this?

[aydinfatih]

Hello @Sammyjo20 ,

I agree with the idea of using a single package for all api requests. Using a separate package for Soap is a separate learning process. Including it as a plugin in the Saloon package will be very useful.

What do you think of it? Do you think an MVP without WSDL and all that stuff will be fine?

• I think we can simplify it in the following way. Instead of creating soap classes like SoapHeader, SoapBody, we can use php's own soap classes.

class GetUserRequest extends Request
{
    use HasSoapBody;
    

    protected function resolveSoapUrl(): string
    {
        return 'url';
    }

    protected function resolveSoapOption(): array
    {
        return [];
    }


    protected function resolveSoapHeader(): ?array
    {
        // Can be nullable to omit header
        
        return [
          new SoapHeader(...), // raw php SoapHeader class
          new SoapHeader(...)
       ];
    }
    
    protected function resolveSoapBody(): ?array
    {
        // Can be nullable to omit body
        
        return [
           'ElementOne' => 'Simple',
             ...
         ];
    }
}

Is there anything missing from this MVP?

• There is nothing missing, I think the methods you mentioned will solve the soap needs I have encountered so far.

Do you think people would mind writing the XML out "manually" like this?

• When I examine different php soap libraries, they usually ask the user for the values to be sent as an array. Requesting everything as xml here can be a bit confusing. I think we can get especially body and options fields as array.

If you want, I can take over the plugin issue related to the Soap plugin.

[Sammyjo20]

Hey @aydinfatih thank you for responding and your ideas!

I like your idea of using the SoapHeader - hopefully there's a way to convert this into an array or get the underlying XML from this because I'm not actually going to use the SoapClient at all in this plugin. If I can get that working, I'll definitely use the built in header.

With regards to the body/envelope I'll see if we still need these DTOs because it might be nice to use a DTO to define custom attributes/namespaces. Either way it'll be good to make it consistent.

I noticed your renamed some of the methods - however I'm still intending to use Saloon's connector for the Base URL and the resolveEndpoint for the rest of the URL - and you'll still be able to use defaultHeaders and defaultConfig for HTTP headers and Guzzle client config respectively.

I appreciate the offer but I would quite like to build this initially but I would be more than happy to implement future features.

[Sammyjo20]

Oh by the way when I mention Do you think people would mind writing the XML out "manually" like this? I didn't mean XML I meant defining them in the form of arrays

[simonhamp]

What do you think of it? Do you think an MVP without WSDL and all that stuff will be fine?

It's a start. Always start with some small slice and iterate - don't overthink it! WSDL can come if/when folks are begging for it... who knows, maybe someone will build it out of necessity and PR it back!

Is there anything missing from this MVP?

I don't use SOAP very much any more, so I'm not really in a good position to comment on it. On the surface tho, this looks quite approachable and clean, so if this is enough, I say go with that.

Do you think people would mind writing the XML in the form of arrays like this?

It's far better than hand-rolling the XML.... again, it's a start. When you understand the problem space better and from more angles, you can refine it

The great thing about keeping this as a separate plugin is: if you can maintain compatibility across versions of the Saloon main package, this plugin can have breaking changes internally without necessarily forcing folks to upgrade multiple dependencies at once

It'll take a bit more work and management, but that might be worth it 👍🏼

[Sammyjo20]

Hey @simonhamp Thank you for looking at this! I totally agree I'd rather start with something basic and then we can build the plugin up with more features - it also gives the opportunity for others to contribute. My first step is to provide a really nice way of defining SOAP requests while allowing people to still overwrite Saloon's defaults - because I know what some APIs are like!

Looking forward to sharing more about this soon

[daniplaninc]

Hi,

I am currently working with an enterprise SOAP API and from my perspective the main pain point was implementing the authentication (WSSE / WS-Security). I tried a few packages, and finally settled on codedredd/laravel-soap. I am now using saloon for another API integration and would be awesome if I could use it for the SOAP API as well.

Not sure if the security headers are out of scope, but if your target use case is enterprise, then I think it's quite a common issue.

[Sammyjo20]

Hey @daniplaninc thanks for sharing that - I agree, I've had to use WS-Security for an enterprise API too. I'll definitely have a look. If you need to parse the XML responses, you might be interested in a library I just released: https://github.com/saloonphp/xml-wrangler

[Sammyjo20]

I apologise for the delay on working on this one! It's still something I am interested in doing - however I am currently working on a few things here which have taken priority.

[gpibarra]

nothing to apologize, this is open source!
It seems to me @inxilpro has been implementing something that looks like this. From what I understood (according to what he put on Twitter/X) he has built the definition for Saloon (using DTOs in addition) from a GraphQL definition, I think that in this case, the source would be from the WSDL definition of soap.

[ithuis]

@Sammyjo20 Hi, is the any progress on this? ( not pushing, just asking! )

[Sammyjo20]

Hey @ithuis sadly not yet, I still think this would be a pretty fun project to tackle, hopefully over the next couple of months I can look into this further! I would highly check out https://github.com/saloonphp/xml-wrangler though as it has a great way of writing/reading XML.

[ithuis]

yeah , thats also a great package.. i am using that to.
but no worries. about the soap, for me soap is just a one off...

[veewee]

@Sammyjo20

Maybe a different insight on the topic:
I've finished this package about a month ago:

https://github.com/php-soap/encoding

It's a drop-in replacement that mimics how PHP's SoapClient does the encoding / decoding of it's data.
By using the schema(s) inside the WSDL, it knows how raw data can be transformed into a valid SOAP payload.

Some examples:

Setup

$wsdl = (new Wsdl1Reader(new StreamWrapperLoader()))('your.wsdl');
$driver = Driver::createFromWsdl1($wsdl);

Encoding

$encoded = $driver->encode('CategoryList', [
    [
        'languagecode' => 'nl',
    ]
]);

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Body xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
        <tns:CategoryList xmlns:tns="urn:tns">
            <tns:languagecode xmlns:tns="urn:tns">nl</tns:languagecode>
        </tns:CategoryList>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Decoding

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/">
    <soap:Body xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap12/">
        <ns2:CategoryList_Result xmlns:ns2="urn:tns" xmlns:ns1="urn:ns1">
            <ns2:result>
                <ns1:Category xmlns:ns1="urn:ns1">
                    <ns1:Code>x</ns1:Code>
                    <ns1:Descriptions>
                        <ns1:Description ns1:LanguageCode="nl" ns1:Value="hello"/>
                        <ns1:Description ns1:LanguageCode="fr" ns1:Value="bonjour"/>
                    </ns1:Descriptions>
                </ns1:Category>
            </ns2:result>
        </ns2:CategoryList_Result>
    </soap:Body>
</soap:Envelope>

var_dump($result = $driver->decode('CategoryList', new SoapResponse($xmlResponsePayload)));

^ {#2374
  +"result": {#2296
    +"Category": array:1 [
      0 => {#160
        +"Code": "x"
        +"Descriptions": {#2418
          +"Description": array:2 [
            0 => {#11571
              +"LanguageCode": "nl"
              +"Value": "hello"
            }
            1 => {#2355
              +"LanguageCode": "fr"
              +"Value": "bonjour"
            }
          ]
        }
      }
    ]
  }
}

Where this encoding library really starts to shine, is that you can highly configure the encoding system. This makes it possible to map from and to DTOs directly, Gives you control on how to encode/decode any type of data. For example: how do you want to work with dates? \DateTime, Carbon , ...

EncoderRegistry::default()
    ->addClassMap('urn:namespace', 'TypeA', TypeA::class)
    ->addClassMap('urn:namespace', 'TypeB', TypeB::class)
    ->addClassMapCollection(new ClassMapCollection(
        new ClassMap('urn:namespace', 'TypeC', TypeC::class),
    ))
    ->addBackedEnum('urn:namespace', 'EnumA', EnumA::class)
    ->addSimpleTypeConverter(Xmlns::xsd()->value(), 'dateTime', new DateTimeTypeEncoder('Y-m-d\TH:i:s'))
    ->addComplexTypeConverter('urn:namespace', 'TypeC', new MySpecificTypeCEncoder());

The php-soap project aims to replace PHP's built-in SOAP extension and contains a lot of other usefull packages that allow you to deal with more advanced SOAP service.

Some examples of it's components:

• PSR bindings (which might make it easy to implement here)
• SOAP headers
• WSSE security
• Common SOAP middlewares
• async capabilities, ...
• Much much more

So what's in this for you?

• You don't have to bother with parsing WSDLs nor with implementing the various SOAP encoding rules (soap 1.1 vs 1.2, encoded vs literal, RPC vs document, ...). The ecoding package does that for you and you can keep your custom connector layer quite simple.
• SoapFaults get transformed into sensible exceptions
• You can work with array structures (as you initially propesed) which get transformed into the schema compliant XML structures. The benifit of this is that it can give you sensible error messages on broken formats when you for example made a typo in a key name or when you provided an invalid value type.

[SanderMuller]

@veewee I'm not sure yet how to get this working, I don't think Saloon can send a PSR-7 request. connector->send() requires a SaloonRequest instance which doesnt seem to have an option to create one from PSR

[veewee]

I dont know how saloon works to be fair. But then you'll need to write your own saloon request / response converter logic based on the examples above. You could always take a look at how they currently do it for XML and use a similar approach for SOAP. You'll somehow need to specify the drive from outside the request and response and use that in order to properly encode from / to php data structures.

[itmsh]

@veewee Maybe we can simply use like this:

<?php declare(strict_types=1);

namespace App\Library;

use Saloon\Contracts\Body\HasBody;
use Saloon\Enums\Method;
use Saloon\Http\Request;
use Saloon\Http\Response;
use Saloon\Traits\Body\HasXmlBody;
use Soap\Encoding\Driver;
use Soap\Engine\HttpBinding\SoapResponse;
use Soap\Wsdl\Loader\StreamWrapperLoader;
use Soap\WsdlReader\Wsdl1Reader;

class SoapSaloonRequest extends Request implements HasBody
{
    use HasXmlBody;

    const string SOAP11 = '1.1';
    const string SOAP12 = '1.2';

    private string $endpoint = '';
    private string $soapVersion = self::SOAP11;
    private string $soapAction = '';
    private ?string $soapBody = null;
    private bool $hasSoapMessage = false;
    protected Method $method = Method::POST;
    protected Driver $wsdlDriver;

    public function __construct($wdlPath, protected $soapMethod, protected $soapPayload)
    {
        $wsdl = (new Wsdl1Reader(new StreamWrapperLoader))($wdlPath);
        $this->wsdlDriver = Driver::createFromWsdl1($wsdl);
        $request = $this->wsdlDriver->encode($soapMethod, [$soapPayload]);

        $this->soapVersion = $request->isSOAP11() ? self::SOAP11 : self::SOAP12;
        $this->endpoint = $request->getLocation();
        $this->soapAction = $request->getAction();
        $this->soapBody = $request->getRequest();
    }

    protected function defaultHeaders(): array
    {
        return $this->prepareHeaders();
    }

    public function resolveEndpoint(): string
    {
        return $this->endpoint;
    }

    public function defaultBody(): ?string
    {
        return $this->soapBody;
    }

    public function createDtoFromResponse(Response $response): mixed
    {
        return $this->wsdlDriver->decode($this->soapMethod, new SoapResponse($response->body()));
    }

    /**
     * @return array<string, string>
     */
    private function prepareHeaders(): array
    {
        if ($this->soapVersion === self::SOAP11) {
            return $this->prepareSoap11Headers();
        }

        return $this->prepareSoap12Headers();
    }

    /**
     * @link https://www.w3.org/TR/2000/NOTE-SOAP-20000508/#_Toc478383526
     * @return array<string, string>
     */
    private function prepareSoap11Headers(): array
    {
        $headers = [];
        $headers['SOAPAction'] = $this->prepareQuotedSoapAction($this->soapAction);
        $headers['Content-Type'] = 'text/xml; charset="utf-8"';

        return array_filter($headers);
    }

    /**
     * SOAPAction header is removed in SOAP 1.2 and now expressed as a value of
     * an (optional) "action" parameter of the "application/soap+xml" media type.
     * @link https://www.w3.org/TR/soap12-part0/#L4697
     * @return array<string, string>
     */
    private function prepareSoap12Headers(): array
    {
        $headers = [];
        if ($this->method !== Method::POST) {
            $headers['Accept'] = 'application/soap+xml';
            return $headers;
        }

        $soapAction = $this->prepareQuotedSoapAction($this->soapAction);
        $headers['Content-Type'] = 'application/soap+xml; charset="utf-8"' . '; action='.$soapAction;

        return array_filter($headers);
    }

    private function prepareQuotedSoapAction(string $soapAction): string
    {
        $soapAction = trim($soapAction, '"\'');

        return '"'.$soapAction.'"';
    }
}

[veewee]

@itmsh As mentioned above, I don't really know the internals of saloon - so I'll leave the implementation up to people who know these things. Looking at the documentation of Saloon - from a user perspective - the request should look something more like this:

trait HasSoapBody
{
    abstract public function soapDriver(): Driver;
    abstract public function soapMethod(): string;

   // Specific methods that set the headers, body, ...
}

class MySpecficSoapActionRequest extends Request implements HasBody
{
    use HasSoapBody;

    public function soapDriver(): Driver
    {
        // Either use dependency injection or use a singleton / facade:
        // You don't want to create the driver for every request.
        return myMemoizedDriverInstance();
    }

    public function soapMethod(): string
    {
        // Can be used as input for the encode method.
        // You can also grab all possible information for building the HTTP headers by using
        // $driver->getMetadata()->getMethods()->fetchByName($yourMethod);
        // Extra information can be found on $method->meta().
        // You're probably interested in $methodMeta>action(), $methodMeta>location() and $methodMeta>soapVersion()
        return 'MySpecificSoapAction';
    }

    protected function defaultBody(): array
    {
        return [
            ['param1' => 'payload'],
            ['param2' => 'payload'],
        ];
    }
}

Some pointers:

• The method is POST indeed, unless oneWay on SOAP 1.2 is set. Haven't seen that used in the wild though.
• I think you get the headers part right.
• You can use the driver's metadata to find the specific in formation you need for building the headers. You don't have to rely on having the request pre-built at that time if this makes things easier.
• In your example, you are also parsing the response. Looking at the documentation - the response class of saloon should probably be extended to support soap responses directly?

Hope this helps :)

[itmsh]

@veewee Appreciate your guidance!

[fastsol]

Hello, Is there any chance that Soap can be added in the very near future? I have a project that requires Soap to get product info from our vendor and it would be really nice if this was something I could do through Saloon. I already use Saloon in this project that works great for getting info from a different vendor but this new vendor still uses Soap... :(

[SanderMuller]

I second it, still struggling to get it working (I really want to get it working, not giving up yet)