+XML-RPC for PHP version 4.0.1 - 2016/??/??
+
+* improved: all of the API documentation has been moved out of the manual and into the source code phpdoc comments
+
+* fixed: the 'valtyp' property of Response was not present in all cases; the ValType property had been added by error
+ and has been removed
+
+
XML-RPC for PHP version 4.0.0 - 2016/1/20
This release does away with the past and starts a transition to modern-world php.
$v = new PhpXmlRpc\Value("What are you saying? >> << &&");
print "<PRE>" . htmlentities($v->serialize()) . "</PRE>";
-$v = new PhpXmlRpc\Value(array(
- new PhpXmlRpc\Value("ABCDEFHIJ"),
- new PhpXmlRpc\Value(1234, 'int'),
- new PhpXmlRpc\Value(1, 'boolean'),),
+$v = new PhpXmlRpc\Value(
+ array(
+ new PhpXmlRpc\Value("ABCDEFHIJ"),
+ new PhpXmlRpc\Value(1234, 'int'),
+ new PhpXmlRpc\Value(1, 'boolean'),
+ ),
"array"
);
== Class documentation
-[[xmlrpcval]]
-
-=== xmlrpcval
-
-This is where a lot of the hard work gets done. This class enables
- the creation and encapsulation of values for XML-RPC.
-
-Ensure you've read the XML-RPC spec at link:$$http://www.xmlrpc.com/stories/storyReader$7$$[http://www.xmlrpc.com/stories/storyReader$7]
- before reading on as it will make things clearer.
-
-The xmlrpcval class can store arbitrarily
- complicated values using the following types: ++i4 int boolean string double dateTime.iso8601 base64 array struct++
- ++null++. You should refer to the link:$$http://www.xmlrpc.com/spec$$[spec] for more information on
- what each of these types mean.
==== Notes on types
[[xmlrpcval-creation]]
-==== Creation
+==== Xmlrpcval creation
The constructor is the normal way to create an
xmlrpcval. The constructor can take these
See the file ++vardemo.php++ in this distribution
for more examples.
-[[xmlrpcval-methods]]
-
-==== Methods
-
-===== addScalar
-
-int addScalarstring$stringValintaddScalarmixed$scalarValstring$scalartypIf $val is an empty
- xmlrpcval this method makes it a scalar
- value, and sets that value.
-
-If $val is already a scalar value, then
- no more scalars can be added and ++0++ is
- returned.
-
-If $val is an xmlrpcval of type array,
- the php value $scalarval is added as its last
- element.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== addArray
-
-intaddArrayarray$arrayValThe argument is a simple (numerically indexed) array. The
- elements of the array __must be xmlrpcval objects themselves__.
-
-Turns an empty xmlrpcval into an
- array with contents as specified by
- $arrayVal.
-
-If $val is an xmlrpcval of type array,
- the elements of $arrayVal are appended to the
- existing ones.
-
-See the fourth constructor form for more information.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== addStruct
-
-int addStructarray$assocArrayValThe argument is an associative array. The elements of the
- array __must be xmlrpcval objects themselves__.
-
-Turns an empty xmlrpcval into a
- struct with contents as specified by
- $assocArrayVal.
-
-If $val is an xmlrpcval of type struct,
- the elements of $arrayVal are merged with the
- existing ones.
-
-See the fourth constructor form for more information.
-
-If all went OK, ++1++ is returned, otherwise
- ++0++.
-
-===== kindOf
-
-string kindOf Returns a string containing "struct", "array" or "scalar"
- describing the base type of the value. If it returns "undef" it
- means that the value hasn't been initialised.
-
-===== serialize
-
-string serialize Returns a string containing the XML-RPC representation of this
- value.
-
-
-===== scalarVal
-
-mixed scalarVal If $val->kindOf() == "scalar", this
- method returns the actual PHP-language value of the scalar (base 64
- decoding is automatically handled here).
-
-===== scalarTyp
-
-string scalarTyp If $val->kindOf() == "scalar", this
- method returns a string denoting the type of the scalar. As
- mentioned before, ++i4++ is always coerced to
- ++int++.
-
-===== arrayMem
-
-xmlrpcval arrayMem int $n If $val->kindOf() == "array", returns
- the $nth element in the array represented by
- the value $val. The value returned is an
- xmlrpcval object.
-
-[source, php]
-----
-
-// iterating over values of an array object
-for ($i = 0; $i < $val->arraySize(); $i++)
-{
- $v = $val->arrayMem($i);
- echo "Element $i of the array is of type ".$v->kindOf();
-}
-
-----
-
-===== arraySize
-
-int arraySize If $val is an
- array, returns the number of elements in that
- array.
-
-===== structMem
-
-xmlrpcval structMem string $memberName If $val->kindOf() == "struct", returns
- the element called $memberName from the
- struct represented by the value $val. The
- value returned is an xmlrpcval object.
-
-===== structEach
-
-array structEach Returns the next (key, value) pair from the struct, when
- $val is a struct.
- $value is an xmlrpcval itself. See also <<structreset>>.
-
-[source, php]
-----
-
-// iterating over all values of a struct object
-$val->structreset();
-while (list($key, $v) = $val->structEach())
-{
- echo "Element $key of the struct is of type ".$v->kindOf();
-}
-
-----
-
-[[structreset]]
-
-===== structReset
-
-void structReset Resets the internal pointer for
- structEach() to the beginning of the struct,
- where $val is a struct.
-
-[[structmemexists]]
-
-===== structMemExists
-
-bool structMemExsists string $memberName Returns TRUE or
- FALSE depending on whether a member of the
- given name exists in the struct.
-
-[[xmlrpcmsg]]
-
-=== xmlrpcmsg
-
-This class provides a representation for a request to an XML-RPC
- server. A client sends an xmlrpcmsg to a server,
- and receives back an xmlrpcresp (see <<xmlrpc-client-send>>).
-
-==== Creation
-
-The constructor takes the following forms:
-
-xmlrpcmsgnew
- xmlrpcmsgstring$methodNamearray$parameterArraynullWhere methodName is a string indicating
- the name of the method you wish to invoke, and
- parameterArray is a simple php
- Array of xmlrpcval
- objects. Here's an example message to the __US state name__ server:
-
-[source, php]
-----
-
-$msg = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
-
-----
-
-This example requests the name of state number 23. For more
- information on xmlrpcval objects, see <<xmlrpcval>>.
-
-Note that the parameterArray parameter is
- optional and can be omitted for methods that take no input parameters
- or if you plan to add parameters one by one.
-
-==== Methods
-
-
-===== addParam
-
-bool addParam xmlrpcval $xmlrpcVal Adds the xmlrpcval
- xmlrpcVal to the parameter list for this
- method call. Returns TRUE or FALSE on error.
-
-===== getNumParams
-
-int getNumParams Returns the number of parameters attached to this
- message.
-
-===== getParam
-
-xmlrpcval getParam int $n Gets the nth parameter in the message
- (with the index zero-based). Use this method in server
- implementations to retrieve the values sent by the client.
-
-===== method
-
-string method string method string $methNameGets or sets the method contained in the XML-RPC
- message.
-
-===== parseResponse
-
-xmlrpcresp parseResponsestring $xmlString Given an incoming XML-RPC server response contained in the
- string $xmlString, this method constructs an
- xmlrpcresp response object and returns it,
- setting error codes as appropriate (see <<xmlrpc-client-send>>).
-
-This method processes any HTTP/MIME headers it finds.
-
-===== parseResponseFile
-
-xmlrpcresp parseResponseFile file handle
- resource$fileHandleGiven an incoming XML-RPC server response on the open file
- handle fileHandle, this method reads all the
- data it finds and passes it to
- parseResponse.
-
-This method is useful to construct responses from pre-prepared
- files (see files ++demo1.xml, demo2.xml, demo3.xml++
- in this distribution). It processes any HTTP headers it finds, and
- does not close the file handle.
-
-===== serialize
-
-string
- serializeReturns the an XML string representing the XML-RPC
- message.
-
[[xmlrpc-client]]
-=== xmlrpc_client
-
-This is the basic class used to represent a client of an XML-RPC
- server.
-
-==== Creation
+==== Xmlrpc-client creation
The constructor accepts one of two possible syntaxes:
meaning of the different values.
-==== Methods
-
-This class supports the following methods.
-
-[[xmlrpc-client-send]]
-
-===== send
-
-This method takes the forms:
-
-xmlrpcresp send xmlrpcmsg $xmlrpc_message int $timeout string $transport array sendarray $xmlrpc_messages int $timeout string $transportxmlrpcrespsendstring$xml_payloadint$timeoutstring$transportWhere xmlrpc_message is an instance of
- xmlrpcmsg (see <<xmlrpcmsg>>),
- and response is an instance of
- xmlrpcresp (see <<xmlrpcresp>>).
-
-If xmlrpc_messages is an array of
- message instances, ++responses++ will be an array of
- response instances. The client will try to make use of a single
- ++system.multicall++ xml-rpc method call to forward to the
- server all the messages in a single HTTP round trip, unless
- ++$$$client->no_multicall$$++ has been previously set to
- ++TRUE++ (see the multicall method below), in which case
- many consecutive xmlrpc requests will be sent.
-
-The third syntax allows to build by hand (or any other means)
- a complete xmlrpc request message, and send it to the server.
- xml_payload should be a string containing the
- complete xml representation of the request. It is e.g. useful when,
- for maximal speed of execution, the request is serialized into a
- string using the native php xmlrpc functions (see link:$$http://www.php.net/xmlrpc$$[the php manual on xmlrpc]).
-
-The timeout is optional, and will be
- set to ++0++ (wait for platform-specific predefined
- timeout) if omitted. This timeout value is passed to
- fsockopen(). It is also used for detecting
- server timeouts during communication (i.e. if the server does not
- send anything to the client for timeout
- seconds, the connection will be closed).
-
-The transport parameter is optional,
- and if omitted will default to the transport set using instance
- creator or 'http' if omitted. The only other valid values are
- 'https', which will use an SSL HTTP connection to connect to the
- remote server, and 'http11'. Note that your PHP must have the "curl"
- extension compiled in order to use both these features. Note that
- when using SSL you should normally set your port number to 443,
- unless the SSL server you are contacting runs at any other
- port.
-
-In addition to low-level errors, the XML-RPC server you were
- querying may return an error in the
- xmlrpcresp object. See <<xmlrpcresp>> for details of how to handle these
- errors.
-
-[[multicall]]
-
-===== multiCall
-
-This method takes the form:
-
-array multiCall array $messages int $timeout string $transport bool $fallback This method is used to boxcar many method calls in a single
- xml-rpc request. It will try first to make use of the
- ++system.multicall++ xml-rpc method call, and fall back to
- executing many separate requests if the server returns any
- error.
-
-msgs is an array of
- xmlrpcmsg objects (see <<xmlrpcmsg>>), and response is an
- array of xmlrpcresp objects (see <<xmlrpcresp>>).
-
-The timeout and
- transport parameters are optional, and behave
- as in the send method above.
-
-The fallback parameter is optional, and
- defaults to TRUE. When set to
- FALSE it will prevent the client to try using
- many single method calls in case of failure of the first multicall
- request. It should be set only when the server is known to support
- the multicall extension.
-
-===== setAcceptedCompression
-
-void setAcceptedCompression string $compressionmethod This method defines whether the client will accept compressed
- xml payload forming the bodies of the xmlrpc responses received from
- servers. Note that enabling reception of compressed responses merely
- adds some standard http headers to xmlrpc requests. It is up to the
- xmlrpc server to return compressed responses when receiving such
- requests. Allowed values for
- compressionmethod are: 'gzip', 'deflate',
- 'any' or null (with any meaning either gzip or deflate).
-
-This requires the "zlib" extension to be enabled in your php
- install. If it is, by default xmlrpc_client
- instances will enable reception of compressed content.
-
-===== setCaCertificate
-
-voidsetCaCertificatestring$certificatebool$is_dirThis method sets an optional certificate to be used in
- SSL-enabled communication to validate a remote server with (when the
- server_method is set to 'https' in the
- client's construction or in the send method and
- SetSSLVerifypeer has been set to
- TRUE).
-
-The certificate parameter must be the
- filename of a PEM formatted certificate, or a directory containing
- multiple certificate files. The is_dir
- parameter defaults to FALSE, set it to
- TRUE to specify that
- certificate indicates a directory instead of
- a single file.
-
-This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- curl_setopt function.
-
-
-===== setCertificate
-
-voidsetCertificatestring$certificatestring$passphraseThis method sets the optional certificate and passphrase used
- in SSL-enabled communication with a remote server (when the
- server_method is set to 'https' in the
- client's construction or in the send method).
-
-The certificate parameter must be the
- filename of a PEM formatted certificate. The
- passphrase parameter must contain the
- password required to use the certificate.
-
-This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- curl_setopt function.
-
-Note: to retrieve information about the client certificate on
- the server side, you will need to look into the environment
- variables which are set up by the webserver. Different webservers
- will typically set up different variables.
-
-===== setCookie
-
-void setCookiestring $name string $value string $path string $domain int $portThis method sets a cookie that will be sent to the xmlrpc
- server along with every further request (useful e.g. for keeping
- session info outside of the xml-rpc payload).
-
-$value is optional, and defaults to
- null.
-
-$path, $domain and $port are optional,
- and will be omitted from the cookie header if unspecified. Note that
- setting any of these values will turn the cookie into a 'version 1'
- cookie, that might not be fully supported by the server (see RFC2965
- for more details).
-
-===== setCredentials
-
-voidsetCredentialsstring$usernamestring$passwordint$authtypeThis method sets the username and password for authorizing the
- client to a server. With the default (HTTP) transport, this
- information is used for HTTP Basic authorization. Note that username
- and password can also be set using the class constructor. With HTTP
- 1.1 and HTTPS transport, NTLM and Digest authentication protocols
- are also supported. To enable them use the constants
- CURLAUTH_DIGEST and
- CURLAUTH_NTLM as values for the authtype
- parameter.
-
-
-===== setCurlOptions
-
-voidsetCurlOptionsarray$optionsThis method allows to directly set any desired
- option to manipulate the usage of the cURL client (when in cURL
- mode). It can be used eg. to explicitly bind to an outgoing ip
- address when the server is multihomed
-
-
-===== setDebug
-
-void setDebugint$debugLvldebugLvl is either ++0, 1++ or 2 depending on whether you require the client to
- print debugging information to the browser. The default is not to
- output this information (0).
-
-The debugging information at level 1includes the raw data
- returned from the XML-RPC server it was querying (including bot HTTP
- headers and the full XML payload), and the PHP value the client
- attempts to create to represent the value returned by the server. At
- level2, the complete payload of the xmlrpc request is also printed,
- before being sent t the server.
-
-This option can be very useful when debugging servers as it
- allows you to see exactly what the client sends and the server
- returns.
-
-
-===== setKey
-
-voidsetKeyint$keyint$keypassThis method sets the optional certificate key and passphrase
- used in SSL-enabled communication with a remote server (when the
- transport is set to 'https' in the client's
- construction or in the send method).
-
-This requires the "curl" extension to be compiled into your
- installation of PHP. For more details see the man page for the
- curl_setopt function.
-
-
-===== setProxy
-
-voidsetProxystring$proxyhostint$proxyportstring$proxyusernamestring$proxypasswordint$authtypeThis method enables calling servers via an HTTP proxy. The
- proxyusername,
- proxypassword and authtype
- parameters are optional. Authtype defaults to
- CURLAUTH_BASIC (Basic authentication protocol);
- the only other valid value is the constant
- CURLAUTH_NTLM, and has effect only when the
- client uses the HTTP 1.1 protocol.
-
-NB: CURL versions before 7.11.10 cannot use a proxy to
- communicate with https servers.
-
-
-===== setRequestCompression
-
-voidsetRequestCompressionstring$compressionmethodThis method defines whether the xml payload forming the
- request body will be sent to the server in compressed format, as per
- the HTTP specification. This is particularly useful for large
- request parameters and over slow network connections. Allowed values
- for compressionmethod are: 'gzip', 'deflate',
- 'any' or null (with any meaning either gzip or deflate). Note that
- there is no automatic fallback mechanism in place for errors due to
- servers not supporting receiving compressed request bodies, so make
- sure that the particular server you are querying does accept
- compressed requests before turning it on.
-
-This requires the "zlib" extension to be enabled in your php
- install.
-
-
-===== setSSLVerifyHost
-
-voidsetSSLVerifyHostint$iThis method defines whether connections made to XML-RPC
- backends via HTTPS should verify the remote host's SSL certificate's
- common name (CN). By default, only the existence of a CN is checked.
- $i should be an
- integer value; 0 to not check the CN at all, 1 to merely check for
- its existence, and 2 to check that the CN on the certificate matches
- the hostname that is being connected to.
-
-
-===== setSSLVerifyPeer
-
-voidsetSSLVerifyPeerbool$iThis method defines whether connections made to XML-RPC
- backends via HTTPS should verify the remote host's SSL certificate,
- and cause the connection to fail if the cert verification fails.
- $i should be a boolean
- value. Default value: TRUE. To specify custom
- SSL certificates to validate the server with, use the
- setCaCertificate method.
-
-
-===== setUserAgent
-
-voidUseragentstring$useragentThis method sets a custom user-agent that will be
- used by the client in the http headers sent with the request. The
- default value is built using the library name and version
- constants.
-
-
-==== Variables
-
-NB: direct manipulation of these variables is only recommended
- for advanced users.
-
-
-===== no_multicall
-
-This member variable determines whether the multicall() method
- will try to take advantage of the system.multicall xmlrpc method to
- dispatch to the server an array of requests in a single http
- roundtrip or simply execute many consecutive http calls. Defaults to
- FALSE, but it will be enabled automatically on the first failure of
- execution of system.multicall.
-
-
-===== request_charset_encoding
-
-This is the charset encoding that will be used for serializing
- request sent by the client.
-
-If defaults to NULL, which means using US-ASCII and encoding
- all characters outside of the ASCII range using their xml character
- entity representation (this has the benefit that line end characters
- will not be mangled in the transfer, a CR-LF will be preserved as
- well as a singe LF).
-
-Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'
-
-[[return-type]]
-
-===== return_type
-
-This member variable determines whether the value returned
- inside an xmlrpcresp object as results of calls to the send() and
- multicall() methods will be an xmlrpcval object, a plain php value
- or a raw xml string. Allowed values are 'xmlrpcvals' (the default),
- 'phpvals' and 'xml'. To allow the user to differentiate between a
- correct and a faulty response, fault responses will be returned as
- xmlrpcresp objects in any case. Note that the 'phpvals' setting will
- yield faster execution times, but some of the information from the
- original response will be lost. It will be e.g. impossible to tell
- whether a particular php string value was sent by the server as an
- xmlrpc string or base64 value.
-
-Example usage:
-
-
-[source, php]
-----
-
-$client = new xmlrpc_client("phpxmlrpc.sourceforge.net/server.php");
-$client->return_type = 'phpvals';
-$message = new xmlrpcmsg("examples.getStateName", array(new xmlrpcval(23, "int")));
-$resp = $client->send($message);
-if ($resp->faultCode()) echo 'KO. Error: '.$resp->faultString(); else echo 'OK: got '.$resp->value();
-
-----
-
-For more details about usage of the 'xml' value, see Appendix
- A.
-
-[[xmlrpcresp]]
-
-=== xmlrpcresp
-
-This class is used to contain responses to XML-RPC requests. A
- server method handler will construct an
- xmlrpcresp and pass it as a return value. This
- same value will be returned by the result of an invocation of the
- send method of the
- xmlrpc_client class.
-
-
-==== Creation
-
-xmlrpcrespnew
- xmlrpcrespxmlrpcval$xmlrpcvalxmlrpcrespnew
- xmlrpcresp0int$errcodestring$err_stringThe first syntax is used when execution has happened without
- difficulty: $xmlrpcval is an
- xmlrpcval value with the result of the method
- execution contained in it. Alternatively it can be a string containing
- the xml serialization of the single xml-rpc value result of method
- execution.
-
-The second type of constructor is used in case of failure.
- errcode and err_string
- are used to provide indication of what has gone wrong. See <<xmlrpc-server>> for more information on passing error
- codes.
-
-
-==== Methods
-
-
-===== faultCode
-
-intfaultCodeReturns the integer fault code return from the XML-RPC
- response. A zero value indicates success, any other value indicates
- a failure response.
-
-
-===== faultString
-
-stringfaultStringReturns the human readable explanation of the fault indicated
- by $resp->faultCode().
-
-
-===== value
-
-xmlrpcvalvalueReturns an xmlrpcval object containing
- the return value sent by the server. If the response's
- faultCode is non-zero then the value returned
- by this method should not be used (it may not even be an
- object).
-
-Note: if the xmlrpcresp instance in question has been created
- by an xmlrpc_client object whose
- return_type was set to 'phpvals', then a plain
- php value will be returned instead of an
- xmlrpcval object. If the
- return_type was set to 'xml', an xml string will
- be returned (see the return_type member var above for more
- details).
-
-
-===== serialize
-
-stringserializeReturns an XML string representation of the response (xml
- prologue not included).
-
[[xmlrpc-server]]
=== xmlrpc_server
use PhpXmlRpc\Helper\Logger;
+/**
+ * The basic class used to represent a client of an XML-RPC server.
+ */
class Client
{
/// @todo: do these need to be public?
public $cookies = array();
public $extracurlopts = array();
+ /**
+ * @var bool
+ *
+ * This determines whether the multicall() method will try to take advantage of the system.multicall xmlrpc method
+ * to dispatch to the server an array of requests in a single http roundtrip or simply execute many consecutive http
+ * calls. Defaults to FALSE, but it will be enabled automatically on the first failure of execution of
+ * system.multicall.
+ */
public $no_multicall = false;
/**
* curl_version() to determine wheter compression is supported or not
*/
public $accepted_compression = array();
+
/**
* Name of compression scheme to be used for sending requests.
* Either null, gzip or deflate.
*/
+
public $request_compression = '';
/**
* CURL handle: used for keep-alive connections (PHP 4.3.8 up, see:
* http://curl.haxx.se/docs/faq.html#7.3).
*/
public $xmlrpc_curl_handle = null;
+
/// Whether to use persistent connections for http 1.1 and https
public $keepalive = false;
+
/// Charset encodings that can be decoded without problems by the client
public $accepted_charset_encodings = array();
- /// Charset encoding to be used in serializing request. NULL = use ASCII
+
+ /**
+ * The charset encoding that will be used for serializing request sent by the client.
+ * If defaults to NULL, which means using US-ASCII and encoding all characters outside of the ASCII range using
+ * their xml character entity representation (this has the benefit that line end characters will not be mangled in
+ * the transfer, a CR-LF will be preserved as well as a singe LF).
+ * Valid values are 'US-ASCII', 'UTF-8' and 'ISO-8859-1'
+ */
public $request_charset_encoding = '';
+
/**
- * Decides the content of Response objects returned by calls to send()
- * valid strings are 'xmlrpcvals', 'phpvals' or 'xml'.
+ * Decides the content of Response objects returned by calls to send() and multicall().
+ * Valid values are 'xmlrpcvals', 'phpvals' or 'xml'.
+ *
+ * Determines whether the value returned inside an Response object as results of calls to the send() and multicall()
+ * methods will be a Value object, a plain php value or a raw xml string.
+ * Allowed values are 'xmlrpcvals' (the default), 'phpvals' and 'xml'.
+ * To allow the user to differentiate between a correct and a faulty response, fault responses will be returned as
+ * Response objects in any case.
+ * Note that the 'phpvals' setting will yield faster execution times, but some of the information from the original
+ * response will be lost. It will be e.g. impossible to tell whether a particular php string value was sent by the
+ * server as an xmlrpc string or base64 value.
*/
public $return_type = 'xmlrpcvals';
+
/**
* Sent to servers in http headers.
*/
public $user_agent;
/**
- * @param string $path either the complete server URL or the PATH part of the xmlrc server URL, e.g. /xmlrpc/server.php
+ * @param string $path either the PATH part of the xmlrpc server URL, or complete server URL (in which case you
+ * should use and empty string for all other parameters)
+ * e.g. /xmlrpc/server.php
+ * e.g. http://phpxmlrpc.sourceforge.net/server.php
+ * e.g. https://james:bond@secret.service.com:443/xmlrpcserver?agent=007
* @param string $server the server name / ip address
- * @param integer $port the port the server is listening on, defaults to 80 or 443 depending on protocol used
- * @param string $method the http protocol variant: defaults to 'http', 'https' and 'http11' can be used if CURL is installed
+ * @param integer $port the port the server is listening on, when omitted defaults to 80 or 443 depending on
+ * protocol used
+ * @param string $method the http protocol variant: defaults to 'http'; 'https' and 'http11' can be used if CURL is
+ * installed. The value set here can be overridden in any call to $this->send().
*/
public function __construct($path, $server = '', $port = '', $method = '')
{
}
/**
- * Enables/disables the echoing to screen of the xmlrpc responses received.
+ * Enable/disable the echoing to screen of the xmlrpc responses received. The default is not no output anything.
+ *
+ * The debugging information at level 1 includes the raw data returned from the XML-RPC server it was querying
+ * (including bot HTTP headers and the full XML payload), and the PHP value the client attempts to create to
+ * represent the value returned by the server
+ * At level2, the complete payload of the xmlrpc request is also printed, before being sent t the server.
+ *
+ * This option can be very useful when debugging servers as it allows you to see exactly what the client sends and
+ * the server returns.
*
* @param integer $in values 0, 1 and 2 are supported (2 = echo sent msg too, before received response)
*/
- public function setDebug($in)
+ public function setDebug($level)
{
- $this->debug = $in;
+ $this->debug = $level;
}
/**
- * Add some http BASIC AUTH credentials, used by the client to authenticate.
+ * Sets the username and password for authorizing the client to the server.
*
- * @param string $u username
- * @param string $p password
- * @param integer $t auth type. See curl_setopt man page for supported auth types. Defaults to CURLAUTH_BASIC (basic auth)
+ * With the default (HTTP) transport, this information is used for HTTP Basic authorization.
+ * Note that username and password can also be set using the class constructor.
+ * With HTTP 1.1 and HTTPS transport, NTLM and Digest authentication protocols are also supported. To enable them use
+ * the constants CURLAUTH_DIGEST and CURLAUTH_NTLM as values for the auth type parameter.
+ *
+ * @param string $user username
+ * @param string $password password
+ * @param integer $authType auth type. See curl_setopt man page for supported auth types. Defaults to CURLAUTH_BASIC
+ * (basic auth). Note that auth types NTLM and Digest will only work if the Curl php
+ * extension is enabled.
*/
- public function setCredentials($u, $p, $t = 1)
+ public function setCredentials($user, $password, $authType = 1)
{
- $this->username = $u;
- $this->password = $p;
- $this->authtype = $t;
+ $this->username = $user;
+ $this->password = $password;
+ $this->authtype = $authType;
}
/**
- * Add a client-side https certificate.
+ * Set the optional certificate and passphrase used in SSL-enabled communication with a remote server.
*
- * @param string $cert
- * @param string $certPass
+ * Note: to retrieve information about the client certificate on the server side, you will need to look into the
+ * environment variables which are set up by the webserver. Different webservers will typically set up different
+ * variables.
+ *
+ * @param string $cert the name of a file containing a PEM formatted certificate
+ * @param string $certPass the password required to use it
*/
- public function setCertificate($cert, $certPass)
+ public function setCertificate($cert, $certPass = '')
{
$this->cert = $cert;
$this->certpass = $certPass;
}
/**
- * Add a CA certificate to verify server with (see man page about
- * CURLOPT_CAINFO for more details).
+ * Add a CA certificate to verify server with in SSL-enabled communication when SetSSLVerifypeer has been set to TRUE.
+ *
+ * See the php manual page about CURLOPT_CAINFO for more details.
*
* @param string $caCert certificate file name (or dir holding certificates)
* @param bool $isDir set to true to indicate cacert is a dir. defaults to false
}
/**
- * Set attributes for SSL communication: private SSL key
- * NB: does not work in older php/curl installs
+ * Set attributes for SSL communication: private SSL key.
+ *
+ * NB: does not work in older php/curl installs.
* Thanks to Daniel Convissor.
*
* @param string $key The name of a file containing a private SSL key
}
/**
- * Set attributes for SSL communication: verify server certificate.
+ * Set attributes for SSL communication: verify the remote host's SSL certificate, and cause the connection to fail
+ * if the cert verification fails.
+ *
+ * By default, verification is enabled.
+ * To specify custom SSL certificates to validate the server with, use the setCaCertificate method.
*
* @param bool $i enable/disable verification of peer certificate
*/
}
/**
- * Set attributes for SSL communication: verify match of server cert w. hostname.
+ * Set attributes for SSL communication: verify the remote host's SSL certificate's common name (CN).
*
- * @param int $i
+ * Note that support for value 1 has been removed in cURL 7.28.1
+ *
+ * @param int $i Set to 1 to only the existence of a CN, not that it matches
*/
public function setSSLVerifyHost($i)
{
/**
* Set proxy info.
*
+ * NB: CURL versions before 7.11.10 cannot use a proxy to communicate with https servers.
+ *
* @param string $proxyHost
* @param string $proxyPort Defaults to 8080 for HTTP and 443 for HTTPS
* @param string $proxyUsername Leave blank if proxy has public access
* @param string $proxyPassword Leave blank if proxy has public access
- * @param int $proxyAuthType set to constant CURLAUTH_NTLM to use NTLM auth with proxy
+ * @param int $proxyAuthType defaults to CURLAUTH_BASIC (Basic authentication protocol); set to constant CURLAUTH_NTLM
+ * to use NTLM auth with proxy (has effect only when the client uses the HTTP 1.1 protocol)
*/
public function setProxy($proxyHost, $proxyPort, $proxyUsername = '', $proxyPassword = '', $proxyAuthType = 1)
{
/**
* Enables/disables reception of compressed xmlrpc responses.
- * Note that enabling reception of compressed responses merely adds some standard
- * http headers to xmlrpc requests. It is up to the xmlrpc server to return
- * compressed responses when receiving such requests.
+ *
+ * This requires the "zlib" extension to be enabled in your php install. If it is, by default xmlrpc_client
+ * instances will enable reception of compressed content.
+ * Note that enabling reception of compressed responses merely adds some standard http headers to xmlrpc requests.
+ * It is up to the xmlrpc server to return compressed responses when receiving such requests.
*
* @param string $compMethod either 'gzip', 'deflate', 'any' or ''
*/
/**
* Enables/disables http compression of xmlrpc request.
- * Take care when sending compressed requests: servers might not support them
- * (and automatic fallback to uncompressed requests is not yet implemented).
+ *
+ * This requires the "zlib" extension to be enabled in your php install.
+ * Take care when sending compressed requests: servers might not support them (and automatic fallback to
+ * uncompressed requests is not yet implemented).
*
* @param string $compMethod either 'gzip', 'deflate' or ''
*/
}
/**
- * Adds a cookie to list of cookies that will be sent to server.
- * NB: setting any param but name and value will turn the cookie into a 'version 1' cookie:
- * do not do it unless you know what you are doing.
+ * Adds a cookie to list of cookies that will be sent to server with every further request (useful e.g. for keeping
+ * session info outside of the xml-rpc payload).
+ *
+ * NB: By default cookies are sent using the 'original/netscape' format, which is also the same as the RFC 2965;
+ * setting any param but name and value will turn the cookie into a 'version 1' cookie (i.e. RFC 2109 cookie) that
+ * might not be fully supported by the server. Note that RFC 2109 has currently 'historic' status...
*
- * @param string $name
+ * @param string $name nb: will not be escaped in the request's http headers. Take care not to use CTL chars or
+ * separators!
* @param string $value
- * @param string $path
- * @param string $domain
- * @param int $port
+ * @param string $path leave this empty unless the xml-rpc server only accepts RFC 2109 cookies
+ * @param string $domain leave this empty unless the xml-rpc server only accepts RFC 2109 cookies
+ * @param int $port leave this empty unless the xml-rpc server only accepts RFC 2109 cookies
*
- * @todo check correctness of urlencoding cookie value (copied from php way of doing it...)
+ * @todo check correctness of urlencoding cookie value (copied from php way of doing it, but php is generally sending
+ * response not requests. We do the opposite...)
+ * @todo strip invalid chars from cookie name? As per RFC6265, we should follow RFC2616, Section 2.2
*/
public function setCookie($name, $value = '', $path = '', $domain = '', $port = null)
{
}
/**
- * Directly set cURL options, for extra flexibility
+ * Directly set cURL options, for extra flexibility (when in cURL mode).
+ *
* It allows eg. to bind client to a specific IP interface / address.
*
* @param array $options
*/
- public function SetCurlOptions($options)
+ public function setCurlOptions($options)
{
$this->extracurlopts = $options;
}
/**
- * Set user-agent string that will be used by this client instance
- * in http headers sent to the server.
+ * Set user-agent string that will be used by this client instance in http headers sent to the server.
+ *
+ * The default user agent string includes the name of this library and the version number.
*
* @param string $agentString
*/
- public function SetUserAgent($agentString)
+ public function setUserAgent($agentString)
{
$this->user_agent = $agentString;
}
/**
- * Send an xmlrpc request.
+ * Send an xmlrpc request to the server.
+ *
+ * @param Request|Request[]|string $req The Request object, or an array of requests for using multicall, or the
+ * complete xml representation of a request.
+ * When sending an array of Request objects, the client will try to make use of
+ * a single 'system.multicall' xml-rpc method call to forward to the server all
+ * the requests in a single HTTP round trip, unless $this->no_multicall has
+ * been previously set to TRUE (see the multicall method below), in which case
+ * many consecutive xmlrpc requests will be sent. The method will return an
+ * array of Response objects in both cases.
+ * The third variant allows to build by hand (or any other means) a complete
+ * xmlrpc request message, and send it to the server. $req should be a string
+ * containing the complete xml representation of the request. It is e.g. useful
+ * when, for maximal speed of execution, the request is serialized into a
+ * string using the native php xmlrpc functions (see http://www.php.net/xmlrpc)
+ * @param integer $timeout Connection timeout, in seconds, If unspecified, a platform specific timeout will apply.
+ * This timeout value is passed to fsockopen(). It is also used for detecting server
+ * timeouts during communication (i.e. if the server does not send anything to the client
+ * for $timeout seconds, the connection will be closed).
+ * @param string $method valid values are 'http', 'http11' and 'https'. If left unspecified, the http protocol
+ * chosen during creation of the object will be used.
*
- * @param Request|Request[]|string $req The Request object, or an array of requests for using multicall, or the complete xml representation of a request
- * @param integer $timeout Connection timeout, in seconds, If unspecified, a platform specific timeout will apply
- * @param string $method if left unspecified, the http protocol chosen during creation of the object will be used
*
- * @return Response|Response[]
+ * @return Response|Response[] Note that the client will always return a Response object, even if the call fails
*/
public function send($req, $timeout = 0, $method = '')
{
* @param string $method
* @return Response
*/
- protected function sendPayloadHTTP10($req, $server, $port, $timeout = 0,
- $username = '', $password = '', $authType = 1, $proxyHost = '',
- $proxyPort = 0, $proxyUsername = '', $proxyPassword = '', $proxyAuthType = 1,
- $method='http')
+ protected function sendPayloadHTTP10($req, $server, $port, $timeout = 0, $username = '', $password = '',
+ $authType = 1, $proxyHost = '', $proxyPort = 0, $proxyUsername = '', $proxyPassword = '', $proxyAuthType = 1,
+ $method='http')
{
if ($port == 0) {
$port = ( $method === "https" ) ? 443 : 80;
* @param int $sslVersion
* @return Response
*/
- protected function sendPayloadHTTPS($req, $server, $port, $timeout = 0, $username = '',
- $password = '', $authType = 1, $cert = '', $certPass = '', $caCert = '', $caCertDir = '',
- $proxyHost = '', $proxyPort = 0, $proxyUsername = '', $proxyPassword = '', $proxyAuthType = 1,
- $keepAlive = false, $key = '', $keyPass = '', $sslVersion = 0)
+ protected function sendPayloadHTTPS($req, $server, $port, $timeout = 0, $username = '', $password = '',
+ $authType = 1, $cert = '', $certPass = '', $caCert = '', $caCertDir = '', $proxyHost = '', $proxyPort = 0,
+ $proxyUsername = '', $proxyPassword = '', $proxyAuthType = 1, $keepAlive = false, $key = '', $keyPass = '',
+ $sslVersion = 0)
{
return $this->sendPayloadCURL($req, $server, $port, $timeout, $username,
$password, $authType, $cert, $certPass, $caCert, $caCertDir, $proxyHost, $proxyPort,
* @param int $sslVersion
* @return Response
*/
- protected function sendPayloadCURL($req, $server, $port, $timeout = 0, $username = '',
- $password = '', $authType = 1, $cert = '', $certPass = '', $caCert = '', $caCertDir = '',
- $proxyHost = '', $proxyPort = 0, $proxyUsername = '', $proxyPassword = '', $proxyAuthType = 1, $method = 'https',
- $keepAlive = false, $key = '', $keyPass = '', $sslVersion = 0)
+ protected function sendPayloadCURL($req, $server, $port, $timeout = 0, $username = '', $password = '',
+ $authType = 1, $cert = '', $certPass = '', $caCert = '', $caCertDir = '', $proxyHost = '', $proxyPort = 0,
+ $proxyUsername = '', $proxyPassword = '', $proxyAuthType = 1, $method = 'https', $keepAlive = false, $key = '',
+ $keyPass = '', $sslVersion = 0)
{
if (!function_exists('curl_init')) {
$this->errstr = 'CURL unavailable on this install';
/**
* Send an array of requests and return an array of responses.
- * Unless $this->no_multicall has been set to true, it will try first
- * to use one single xmlrpc call to server method system.multicall, and
- * revert to sending many successive calls in case of failure.
+ *
+ * Unless $this->no_multicall has been set to true, it will try first to use one single xmlrpc call to server method
+ * system.multicall, and revert to sending many successive calls in case of failure.
* This failure is also stored in $this->no_multicall for subsequent calls.
- * Unfortunately, there is no server error code universally used to denote
- * the fact that multicall is unsupported, so there is no way to reliably
- * distinguish between that and a temporary failure.
- * If you are sure that server supports multicall and do not want to
- * fallback to using many single calls, set the fourth parameter to FALSE.
+ * Unfortunately, there is no server error code universally used to denote the fact that multicall is unsupported,
+ * so there is no way to reliably distinguish between that and a temporary failure.
+ * If you are sure that server supports multicall and do not want to fallback to using many single calls, set the
+ * fourth parameter to FALSE.
*
* NB: trying to shoehorn extra functionality into existing syntax has resulted
* in pretty much convoluted code...
*
* @param Request[] $reqs an array of Request objects
- * @param integer $timeout connection timeout (in seconds)
- * @param string $method the http protocol variant to be used
- * @param boolean fallback When true, upon receiving an error during multicall, multiple single calls will be attempted
+ * @param integer $timeout connection timeout (in seconds). See the details in the docs for the send() method
+ * @param string $method the http protocol variant to be used. See the details in the docs for the send() method
+ * @param boolean fallback When true, upon receiving an error during multicall, multiple single calls will be
+ * attempted
*
- * @return array
+ * @return Response[]
*/
public function multicall($reqs, $timeout = 0, $method = '', $fallback = true)
{
/**
* Attempt to boxcar $reqs via system.multicall.
- * Returns either an array of xmlrpc reponses, an xmlrpc error response
- * or false (when received response does not respect valid multicall syntax).
+ *
+ * Returns either an array of Response, a single error Response or false (when received response does not respect
+ * valid multicall syntax).
*
* @param Request[] $reqs
* @param int $timeout
* @param string $method
- * @return array|bool|mixed|Response
+ * @return Response[]|bool|mixed|Response
*/
private function _try_multicall($reqs, $timeout, $method)
{
}
/**
- * Convert a string to the correct XML representation in a target charset
- * To help correct communication of non-ascii chars inside strings, regardless
- * of the charset used when sending requests, parsing them, sending responses
- * and parsing responses, an option is to convert all non-ascii chars present in the message
- * into their equivalent 'charset entity'. Charset entities enumerated this way
- * are independent of the charset encoding used to transmit them, and all XML
- * parsers are bound to understand them.
- * Note that in the std case we are not sending a charset encoding mime type
- * along with http headers, so we are bound by RFC 3023 to emit strict us-ascii.
+ * Convert a string to the correct XML representation in a target charset.
+ *
+ * To help correct communication of non-ascii chars inside strings, regardless of the charset used when sending
+ * requests, parsing them, sending responses and parsing responses, an option is to convert all non-ascii chars
+ * present in the message into their equivalent 'charset entity'. Charset entities enumerated this way are
+ * independent of the charset encoding used to transmit them, and all XML parsers are bound to understand them.
+ * Note that in the std case we are not sending a charset encoding mime type along with http headers, so we are
+ * bound by RFC 3023 to emit strict us-ascii.
*
* @todo do a bit of basic benchmarking (strtr vs. str_replace)
* @todo make usage of iconv() or recode_string() or mb_string() where available
use PhpXmlRpc\Helper\Logger;
use PhpXmlRpc\Helper\XMLParser;
+/**
+ * This class provides a representation for a request to an XML-RPC server.
+ * A client sends a PhpXmlrpc\Request to a server, and receives back an PhpXmlrpc\Response.
+ */
class Request
{
/// @todo: do these need to be public?
/**
* @param string $methodName the name of the method to invoke
- * @param Value[] $params array of parameters to be passed to the method (Value objects)
+ * @param Value[] $params array of parameters to be passed to the method (NB: Value objects, not plain php values)
*/
public function __construct($methodName, $params = array())
{
$this->content_type = 'text/xml';
}
$this->payload = $this->xml_header($charsetEncoding);
- $this->payload .= '<methodName>' . Charset::instance()->encodeEntities($this->methodname, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "</methodName>\n";
+ $this->payload .= '<methodName>' . Charset::instance()->encodeEntities(
+ $this->methodname, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "</methodName>\n";
$this->payload .= "<params>\n";
foreach ($this->params as $p) {
$this->payload .= "<param>\n" . $p->serialize($charsetEncoding) .
/**
* Add a parameter to the list of parameters to be used upon method invocation.
*
+ * Checks that $params is actually a Value object and not a plain php value.
+ *
* @param Value $param
*
* @return boolean false on failure
/**
* Given an open file handle, read all data available and parse it as an xmlrpc response.
+ *
* NB: the file handle is not closed by this function.
- * NNB: might have trouble in rare cases to work on network streams, as we
- * check for a read of 0 bytes instead of feof($fp).
- * But since checking for feof(null) returns false, we would risk an
- * infinite loop in that case, because we cannot trust the caller
- * to give us a valid pointer to an open file...
+ * NNB: might have trouble in rare cases to work on network streams, as we check for a read of 0 bytes instead of
+ * feof($fp). But since checking for feof(null) returns false, we would risk an infinite loop in that case,
+ * because we cannot trust the caller to give us a valid pointer to an open file...
*
* @param resource $fp stream pointer
*
/**
* Parse the xmlrpc response contained in the string $data and return a Response object.
*
- * @param string $data the xmlrpc response, eventually including http headers
- * @param bool $headersProcessed when true prevents parsing HTTP headers for interpretation of content-encoding and consequent decoding
- * @param string $returnType decides return type, i.e. content of response->value(). Either 'xmlrpcvals', 'xml' or 'phpvals'
+ * When $this->debug has been set to a value greater than 0, will echo debug messages to screen while decoding.
+ *
+ * @param string $data the xmlrpc response, possibly including http headers
+ * @param bool $headersProcessed when true prevents parsing HTTP headers for interpretation of content-encoding and
+ * consequent decoding
+ * @param string $returnType decides return type, i.e. content of response->value(). Either 'xmlrpcvals', 'xml' or
+ * 'phpvals'
*
* @return Response
*/
use PhpXmlRpc\Helper\Charset;
+/**
+ * This class is used to contain responses to XML-RPC requests.
+ * Server-side, a server method handler will construct a Response and pass it as its return value.
+ * An identical Response object will be returned by the result of an invocation of the send() method of the Client class.
+ */
class Response
{
/// @todo: do these need to be public?
public $val = 0;
- public $valType;
+ public $valtyp;
public $errno = 0;
public $errstr = '';
public $payload;
public $raw_data = '';
/**
- * @param mixed $val either an xmlrpc value obj, a php value or the xml serialization of an xmlrpc value (a string)
- * @param integer $fCode set it to anything but 0 to create an error response
+ * @param mixed $val either a Value object, a php value or the xml serialization of an xmlrpc value (a string)
+ * @param integer $fCode set it to anything but 0 to create an error response. In that case, $val is discarded
* @param string $fString the error string, in case of an error response
- * @param string $valType either 'xmlrpcvals', 'phpvals' or 'xml'
+ * @param string $valType The type of $val passed in. Either 'xmlrpcvals', 'phpvals' or 'xml'. Leave empty to let
+ * the code guess the correct type.
*
* @todo add check that $val / $fCode / $fString is of correct type???
- * NB: as of now we do not do it, since it might be either an xmlrpc value or a plain
- * php val, or a complete xml chunk, depending on usage of Client::send() inside which creator is called...
+ * NB: as of now we do not do it, since it might be either an xmlrpc value or a plain php val, or a complete
+ * xml chunk, depending on usage of Client::send() inside which creator is called...
*/
public function __construct($val, $fCode = 0, $fString = '', $valType = '')
{
}
/**
- * Returns the value received by the server.
+ * Returns the value received by the server. If the Response's faultCode is non-zero then the value returned by this
+ * method should not be used (it may not even be an object).
*
- * @return Value|string|mixed the xmlrpc value object returned by the server. Might be an xml string or php value if the response has been created by specially configured Client objects
+ * @return Value|string|mixed the Value object returned by the server. Might be an xml string or plain php value
+ * depending on the convention adopted when creating the Response
*/
public function value()
{
/**
* Returns an array with the cookies received from the server.
- * Array has the form: $cookiename => array ('value' => $val, $attr1 => $val1, $attr2 = $val2, ...)
+ * Array has the form: $cookiename => array ('value' => $val, $attr1 => $val1, $attr2 => $val2, ...)
* with attributes being e.g. 'expires', 'path', domain'.
- * NB: cookies sent as 'expired' by the server (i.e. with an expiry date in the past)
- * are still present in the array. It is up to the user-defined code to decide
- * how to use the received cookies, and whether they have to be sent back with the next
- * request to the server (using Client::setCookie) or not.
+ * NB: cookies sent as 'expired' by the server (i.e. with an expiry date in the past) are still present in the array.
+ * It is up to the user-defined code to decide how to use the received cookies, and whether they have to be sent back
+ * with the next request to the server (using Client::setCookie) or not.
*
* @return array array of cookies received from the server
*/
/**
* Returns xml representation of the response. XML prologue not included.
*
- * @param string $charsetEncoding the charset to be used for serialization. if null, US-ASCII is assumed
+ * @param string $charsetEncoding the charset to be used for serialization. If null, US-ASCII is assumed
*
* @return string the xml representation of the response
*
* Array defining php functions exposed as xmlrpc methods by this server.
*/
protected $dmap = array();
+
/**
* Defines how functions in dmap will be invoked: either using an xmlrpc request object
* or plain php values.
* Valid strings are 'xmlrpcvals', 'phpvals' or 'epivals'
*/
public $functions_parameters_type = 'xmlrpcvals';
+
/**
* Option used for fine-tuning the encoding the php values returned from
* functions registered in the dispatch map when the functions_parameters_types
* @see Encoder::encode for a list of values
*/
public $phpvals_encoding_options = array('auto_dates');
+
/**
* Controls whether the server is going to echo debugging messages back to the client as comments in response body.
* Valid values: 0,1,2,3
*/
public $debug = 1;
+
/**
* Controls behaviour of server when the invoked user function throws an exception:
* 0 = catch it and return an 'internal error' xmlrpc response (default)
* 2 = allow the exception to float to the upper layers
*/
public $exception_handling = 0;
+
/**
* When set to true, it will enable HTTP compression of the response, in case
* the client has declared its support for compression in the request.
* Set at constructor time.
*/
public $compress_response = false;
+
/**
* List of http compression methods accepted by the server for requests. Set at constructor time.
* NB: PHP supports deflate, gzip compressions out of the box if compiled w. zlib
*/
public $accepted_compression = array();
- /// shall we serve calls to system.* methods?
+
+ /// Shall we serve calls to system.* methods?
public $allow_system_funcs = true;
+
/**
* List of charset encodings natively accepted for requests.
* Set at constructor time.
* UNUSED so far...
*/
public $accepted_charset_encodings = array();
+
/**
- * charset encoding to be used for response.
+ * Charset encoding to be used for response.
* NB: if we can, we will convert the generated response from internal_encoding to the intended one.
* Can be: a supported xml encoding (only UTF-8 and ISO-8859-1 at present, unless mbstring is enabled),
* null (leave unspecified in response, convert output stream to US_ASCII),
* NB: pretty dangerous if you accept every charset and do not have mbstring enabled)
*/
public $response_charset_encoding = '';
+
/**
* Storage for internal debug info.
*/
protected $debug_info = '';
+
/**
* Extra data passed at runtime to method handling functions. Used only by EPI layer
*/
use PhpXmlRpc\Helper\Charset;
+/**
+ * This class enables the creation and encapsulation of values for XML-RPC.
+ */
class Value implements \Countable, \IteratorAggregate, \ArrayAccess
{
public static $xmlrpcI4 = "i4";
/**
* Build an xmlrpc value.
- * When no value or type is passed in, the value is left uninitialized, and the value can be added later
*
- * @param mixed $val
- * @param string $type any valid xmlrpc type name (lowercase). If null, 'string' is assumed
+ * When no value or type is passed in, the value is left uninitialized, and the value can be added later.
+ *
+ * @param mixed $val if passing in an array, all array elements should be PhpXmlRpc\Value themselves
+ * @param string $type any valid xmlrpc type name (lowercase): i4, int, boolean, string, double, dateTime.iso8601,
+ * base64, array, struct, null.
+ * If null, 'string' is assumed.
+ * You should refer to http://www.xmlrpc.com/spec for more information on what each of these mean.
*/
public function __construct($val = -1, $type = '')
{
}
/**
- * Add a single php value to an (uninitialized) xmlrpc value.
+ * Add a single php value to an xmlrpc value.
+ *
+ * If the xmlrpc value is an array, the php value is added as its last element.
+ * If the xmlrpc value is empty (uninitialized), this method makes it a scalar value, and sets that value.
+ * Fails if the xmlrpc value is not an array and already initialized.
*
* @param mixed $val
- * @param string $type
+ * @param string $type allowed values: i4, int, boolean, string, double, dateTime.iso8601, base64, null.
*
* @return int 1 or 0 on failure
*/
}
/**
- * Add an array of xmlrpc values objects to an xmlrpc value.
+ * Add an array of xmlrpc value objects to an xmlrpc value.
+ *
+ * If the xmlrpc value is an array, the elements are appended to the existing ones.
+ * If the xmlrpc value is empty (uninitialized), this method makes it an array value, and sets that value.
+ * Fails otherwise.
*
* @param Value[] $values
*
}
/**
- * Add an array of named xmlrpc value objects to an xmlrpc value.
+ * Merges an array of named xmlrpc value objects into an xmlrpc value.
+ *
+ * If the xmlrpc value is a struct, the elements are merged with the existing ones (overwriting existing ones).
+ * If the xmlrpc value is empty (uninitialized), this method makes it a struct value, and sets that value.
+ * Fails otherwise.
*
* @param Value[] $values
*
}
/**
- * Returns a string containing "struct", "array", "scalar" or "undef" describing the base type of the value.
+ * Returns a string containing either "struct", "array", "scalar" or "undef", describing the base type of the value.
*
* @return string
*/
}
/**
- * Returns xml representation of the value. XML prologue not included.
+ * Returns the xml representation of the value. XML prologue not included.
*
* @param string $charsetEncoding the charset to be used for serialization. if null, US-ASCII is assumed
*
/**
* Checks whether a struct member with a given name is present.
+ *
* Works only on xmlrpc values of type struct.
*
* @param string $key the name of the struct member to be looked up
}
/**
- * Returns the value of a scalar xmlrpc value.
+ * Returns the value of a scalar xmlrpc value (base 64 decoding is automatically handled here)
*
* @return mixed
*/
/**
* Returns the type of the xmlrpc value.
+ *
* For integers, 'int' is always returned in place of 'i4'.
*
* @return string
}
/**
- * Returns the m-th member of an xmlrpc value of struct type.
+ * Returns the m-th member of an xmlrpc value of array type.
*
* @param integer $key the index of the value to be retrieved (zero based)
*
/**
* Returns the number of members in an xmlrpc value:
* - 0 for uninitialized values
- * - 1 for scalars
- * - the number of elements for structs and arrays
+ * - 1 for scalar values
+ * - the number of elements for struct and array values
*
* @return integer
*/
git://git.onelab.eu / plcapi.git / commitdiff