From f4978078febfc4289bb4f45db6ca3f9e6c8c4f94 Mon Sep 17 00:00:00 2001 From: gggeek Date: Sun, 24 Jan 2016 19:42:03 +0000 Subject: [PATCH] Move api docs to phpdoc (wip); fix wrong property name in Response class --- NEWS | 8 + demo/vardemo.php | 10 +- doc/manual/phpxmlrpc_manual.adoc | 654 +------------------------------ src/Client.php | 256 ++++++++---- src/Helper/Charset.php | 17 +- src/Request.php | 30 +- src/Response.php | 35 +- src/Server.php | 15 +- src/Value.php | 47 ++- 9 files changed, 289 insertions(+), 783 deletions(-) diff --git a/NEWS b/NEWS index 4fd0aad..4d11f6e 100644 --- a/NEWS +++ b/NEWS @@ -1,3 +1,11 @@ +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. diff --git a/demo/vardemo.php b/demo/vardemo.php index b1ab3c0..3c9812a 100644 --- a/demo/vardemo.php +++ b/demo/vardemo.php @@ -14,10 +14,12 @@ print "
" . htmlentities($v->serialize()) . "
"; $v = new PhpXmlRpc\Value("What are you saying? >> << &&"); print "
" . htmlentities($v->serialize()) . "
"; -$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" ); diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc index 0a78d0c..0e8f2c4 100644 --- a/doc/manual/phpxmlrpc_manual.adoc +++ b/doc/manual/phpxmlrpc_manual.adoc @@ -215,20 +215,6 @@ If you've benefited from the effort that has been put into writing this software == 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 @@ -276,7 +262,7 @@ There is no support for encoding ++null++ [[xmlrpcval-creation]] -==== Creation +==== Xmlrpcval creation The constructor is the normal way to create an xmlrpcval. The constructor can take these @@ -353,248 +339,9 @@ $myStruct = new xmlrpcval( 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 <>. - -[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 <>). - -==== 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 <>. - -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 <>). - -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: @@ -640,403 +387,6 @@ The transport parameter is optional, and 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 <>), - and response is an instance of - xmlrpcresp (see <>). - -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 <> 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 <>), and response is an - array of xmlrpcresp objects (see <>). - -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 <> 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 diff --git a/src/Client.php b/src/Client.php index 8fce704..c884a25 100644 --- a/src/Client.php +++ b/src/Client.php @@ -4,6 +4,9 @@ namespace PhpXmlRpc; 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? @@ -39,6 +42,14 @@ class Client 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; /** @@ -51,37 +62,65 @@ class Client * 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 = '') { @@ -152,44 +191,64 @@ class Client } /** - * 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 @@ -204,8 +263,9 @@ class Client } /** - * 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 @@ -218,7 +278,11 @@ class Client } /** - * 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 */ @@ -228,9 +292,11 @@ class Client } /** - * 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) { @@ -250,11 +316,14 @@ class Client /** * 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) { @@ -267,9 +336,11 @@ class Client /** * 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 '' */ @@ -286,8 +357,10 @@ class Client /** * 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 '' */ @@ -297,17 +370,23 @@ class Client } /** - * 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) { @@ -323,35 +402,54 @@ class Client } /** - * 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 = '') { @@ -456,10 +554,9 @@ class Client * @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; @@ -635,10 +732,10 @@ class Client * @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, @@ -673,10 +770,10 @@ class Client * @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'; @@ -894,25 +991,25 @@ class Client /** * 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) { @@ -965,13 +1062,14 @@ class Client /** * 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) { diff --git a/src/Helper/Charset.php b/src/Helper/Charset.php index 9000ffb..0ec7de4 100644 --- a/src/Helper/Charset.php +++ b/src/Helper/Charset.php @@ -68,15 +68,14 @@ class Charset } /** - * 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 diff --git a/src/Request.php b/src/Request.php index 52a3b97..42ed075 100644 --- a/src/Request.php +++ b/src/Request.php @@ -7,6 +7,10 @@ use PhpXmlRpc\Helper\Http; 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? @@ -21,7 +25,7 @@ class Request /** * @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()) { @@ -53,7 +57,8 @@ class Request $this->content_type = 'text/xml'; } $this->payload = $this->xml_header($charsetEncoding); - $this->payload .= '' . Charset::instance()->encodeEntities($this->methodname, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "\n"; + $this->payload .= '' . Charset::instance()->encodeEntities( + $this->methodname, PhpXmlRpc::$xmlrpc_internalencoding, $charsetEncoding) . "\n"; $this->payload .= "\n"; foreach ($this->params as $p) { $this->payload .= "\n" . $p->serialize($charsetEncoding) . @@ -96,6 +101,8 @@ class Request /** * 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 @@ -136,12 +143,11 @@ class Request /** * 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 * @@ -161,9 +167,13 @@ class Request /** * 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 */ diff --git a/src/Response.php b/src/Response.php index 7e2ebb6..16ff0a8 100644 --- a/src/Response.php +++ b/src/Response.php @@ -4,11 +4,16 @@ namespace PhpXmlRpc; 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; @@ -18,14 +23,15 @@ class Response 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 = '') { @@ -73,9 +79,11 @@ class Response } /** - * 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() { @@ -84,12 +92,11 @@ class Response /** * 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 */ @@ -101,7 +108,7 @@ class Response /** * 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 * diff --git a/src/Server.php b/src/Server.php index 07cfb9b..b098d68 100644 --- a/src/Server.php +++ b/src/Server.php @@ -11,12 +11,14 @@ class Server * 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 @@ -24,11 +26,13 @@ class Server * @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) @@ -36,27 +40,32 @@ class Server * 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), @@ -65,10 +74,12 @@ class Server * 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 */ diff --git a/src/Value.php b/src/Value.php index f0d331a..c9fc614 100644 --- a/src/Value.php +++ b/src/Value.php @@ -4,6 +4,9 @@ namespace PhpXmlRpc; 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"; @@ -38,10 +41,14 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess /** * 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 = '') { @@ -79,10 +86,14 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess } /** - * 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 */ @@ -131,7 +142,11 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess } /** - * 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 * @@ -158,7 +173,11 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess } /** - * 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 * @@ -185,7 +204,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess } /** - * 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 */ @@ -298,7 +317,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess } /** - * 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 * @@ -318,6 +337,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess /** * 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 @@ -368,7 +388,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess } /** - * 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 */ @@ -382,6 +402,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess /** * Returns the type of the xmlrpc value. + * * For integers, 'int' is always returned in place of 'i4'. * * @return string @@ -398,7 +419,7 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess } /** - * 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) * @@ -438,8 +459,8 @@ class Value implements \Countable, \IteratorAggregate, \ArrayAccess /** * 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 */ -- 2.43.0