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.