How to specify a method signature for a function that returns void?

[cmanley]

I don't see void mentioned in the docs or in \PhpXmlRpc\Value class. What is the recommended wat to specify (no) result type void in the method signature?

[gggeek]

That's a good question. I am dumbfounded never to have thought about it - or maybe I just forgot... :-D

The long-read version is:

• the xml-rpc spec is quite clear in stating that a response always contains a value (or a fault) - see http://xmlrpc.com/spec.md, the notes section about "1/21/99 update"
• the spec does not include support for VOID or NULL data types
• the support for method signatures as implemented by the phpxmlrpc was built around the system. family or xmlrpc methods. My memory is a bit fuzzy about where those methods were originally specified (or first developed). They seem to have no formal definition floating around the interwebs as of today. I think they might have been discussed on a now long-deceased mailing list, of which I might have a local archive on some backup disk somewhere at the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying 'Beware of the Leopard'
• it thus stands to reason that there is no provision for void returns in either system.methodSignature and the php code which builds it
• some xml-rpc implementations do implement support for the optional NIL data type. However, there is no definitive agreement on how NIL values are represented - some libs use <NIL>, some <EX:NIL>
• given that there is no clear agreement about how NIL values are to be represented in the XML payload, I'd be surprised to find that there is agreement on what to use as the "name of the NIL type" within system.methodSignature responses

So it seems that we are stuck between a rock and a hard place. There is no support for void returns in xml-rpc, and trying to shoehorn NULL as the closest thing to VOID might be unreliable.

You might of course extend phpxmlrpc to make it better support void returns, but then any automation around validation of parameters would become essentially valid only when you control both sides of the communication, ie. bye bye interoperability.

On a more practical note:

I just looked at the source code of phpxmlrpc, the Wrapper::php2XmlrpcType method being the one used to scan phpdocs of existing php methods/functions and turning it into data to be exposed as system.methodSignature info.
For any php data type annotation it does not understand, it returns the string "undefined".
(side note: there even is a TODO comment there, stating 'check if nil support is enabled when finding null' :-D)
As for what happens when a php function/method which returns void/null is automatically exposed as an xml-rpc method by the Encoder class, it should produce the following bit of xml: <value></value>, which is an empty string value according to the spec.

If you are creating by hand the data structure for the method signature, you should thus probably use "undefined"...

[gggeek]

ps: looking at the manual, I think that the solution I outlined above, i.e. using the string undefined, is already mentioned, in the section about method signatures - it just uses Value::$xmlrpcValue as a more elegant way of doing that.

See: https://github.com/gggeek/phpxmlrpc/blob/master/doc/manual/phpxmlrpc_manual.adoc#signatures

Of course, saying "this method will return anything" is not the same thing as saying "this method will return nothing", so I agree that this is more of a workaround/hack than anything else.

But atm I can think of no better solution, for the reasons detailed above.

[cmanley]

Thanks for the detailed explanation. I'll use Value::$xmlrpcValue: that's good enough for me.

[gggeek]

Ok.
I will keep this ticket open as a reminder for me to update the docs with better info about this scenario