Moodle PHP Documentation 4.3
Moodle 4.3.5 (Build: 20240610) (7dcfaa79f78)
|
Public Member Functions | |
__construct ($path, $server='', $port='', $method='') | |
& | __get ($name) |
__isset ($name) | |
__set ($name, $value) | |
__unset ($name) | |
getOption ($name) | |
getOptions () | |
Returns the complete list of Client options, with their value. | |
getUrl ($component=null) | |
multicall ($reqs, $timeout=0, $method='', $fallback=true) | |
Send an array of requests and return an array of responses. | |
send ($req, $timeout=0, $method='') | |
Send an xml-rpc request to the server. | |
setAcceptedCompression ($compMethod) | |
Enables/disables reception of compressed xml-rpc responses. | |
setCaCertificate ($caCert, $isDir=false) | |
Add a CA certificate to verify server with in SSL-enabled communication when SetSSLVerifypeer has been set to TRUE. | |
setCertificate ($cert, $certPass='') | |
Set the optional certificate and passphrase used in SSL-enabled communication with a remote server. | |
setCookie ($name, $value='', $path='', $domain='', $port=null) | |
Adds a cookie to list of cookies that will be sent to server with every further request (useful e.g. | |
setCredentials ($user, $password, $authType=1) | |
Sets the username and password for authorizing the client to the server. | |
setCurlOptions ($options) | |
Directly set cURL options, for extra flexibility (when in cURL mode). | |
setDebug ($level) | |
Enable/disable the echoing to screen of the xml-rpc responses received. | |
setKey ($key, $keyPass) | |
Set attributes for SSL communication: private SSL key. | |
setOption ($name, $value) | |
setOptions ($options) | |
setProxy ($proxyHost, $proxyPort, $proxyUsername='', $proxyPassword='', $proxyAuthType=1) | |
Set proxy info. | |
setRequestCompression ($compMethod) | |
Enables/disables http compression of xml-rpc request. | |
setSSLVerifyHost ($i) | |
Set attributes for SSL communication: verify the remote host's SSL certificate's common name (CN). | |
setSSLVerifyPeer ($i) | |
Set attributes for SSL communication: verify the remote host's SSL certificate, and cause the connection to fail if the cert verification fails. | |
setSSLVersion ($i) | |
Set attributes for SSL communication: SSL version to use. | |
setUseCurl ($useCurlMode) | |
setUserAgent ($agentString) | |
Set user-agent string that will be used by this client instance in http headers sent to the server. | |
Protected Member Functions | |
createCURLHandle ($req, $method, $server, $port, $path, $opts) | |
prepareCurlHandle ($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) | |
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) | |
sendPayloadHTTP10 ($req, $server, $port, $timeout=0, $username='', $password='', $authType=1, $proxyHost='', $proxyPort=0, $proxyUsername='', $proxyPassword='', $proxyAuthType=1, $method='http') | |
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) | |
sendPayloadSocket ($req, $server, $port, $timeout=0, $username='', $password='', $authType=1, $cert='', $certPass='', $caCert='', $caCertDir='', $proxyHost='', $proxyPort=0, $proxyUsername='', $proxyPassword='', $proxyAuthType=1, $method='http', $key='', $keyPass='', $sslVersion=0) | |
sendViaCURL ($req, $method, $server, $port, $path, $opts) | |
Contributed by Justin Miller Requires curl to be built into PHP NB: CURL versions before 7.11.10 cannot use proxy to talk to https servers! | |
sendViaSocket ($req, $method, $server, $port, $path, $opts) | |
Protected Attributes | |
string[] | $accepted_charset_encodings = array() |
Charset encodings that can be decoded without problems by the client. | |
array | $accepted_compression = array() |
List of http compression methods accepted by the client for responses. | |
int | $authtype = 1 |
string | $cacert = '' |
string | $cacertdir = '' |
string | $cert = '' |
string | $certpass = '' |
array | $cookies = array() |
int | $debug = 0 |
int | $errno |
string | $errstr |
array | $extracurlopts = array() |
array | $extrasockopts = array() |
bool | $keepalive = false |
Whether to use persistent connections for http 1.1 and https. | |
string | $key = '' |
string | $keypass = '' |
string | $method = 'http' |
bool | $no_multicall = false |
This determines whether the multicall() method will try to take advantage of the system.multicall xml-rpc method to dispatch to the server an array of requests in a single http roundtrip or simply execute many consecutive http calls. | |
string | $password = '' |
string | $path |
int | $port = 0 |
string | $proxy = '' |
int | $proxy_authtype = 1 |
string | $proxy_pass = '' |
string | $proxy_user = '' |
int | $proxyport = 0 |
string | $request_charset_encoding = '' |
The charset encoding that will be used for serializing request sent by the client. | |
string null | $request_compression = '' |
Name of compression scheme to be used for sending requests. | |
string | $return_type = XMLParser::RETURN_XMLRPCVALS |
Decides the content of Response objects returned by calls to send() and multicall(). | |
string | $server |
int | $sslversion = 0 |
int | $timeout = 0 |
int | $use_curl = self::USE_CURL_AUTO |
string | $user_agent |
Sent to servers in http headers. | |
string | $username = '' |
int | $verifyhost = 2 |
bool | $verifypeer = true |
Static Protected Attributes | |
static array | $options |
static string | $requestClass = '\\PhpXmlRpc\\Request' |
static string | $responseClass = '\\PhpXmlRpc\\Response' |
PhpXmlRpc\Client::__construct | ( | $path, | |
$server = '', | |||
$port = '', | |||
$method = '' ) |
string | $path | either the PATH part of the xml-rpc server URL, or complete server URL (in which case you should use an 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:444/xmlrpcserver?agent=007 e.g. h2://fast-and-secure-services.org/endpoint |
string | $server | the server name / ip address |
integer | $port | the port the server is listening on, when omitted defaults to 80 or 443 depending on protocol used |
string | $method | the http protocol variant: defaults to 'http'; 'https', 'http11', 'h2' and 'h2c' can be used if CURL is installed. The value set here can be overridden in any call to $this->send(). Use 'h2' to make the lib attempt to use http/2 over a secure connection, and 'h2c' for http/2 without tls. Note that 'h2c' will not use the h2c 'upgrade' method, and be thus incompatible with any server/proxy not supporting http/2. This is because POST request are not compatible with h2c upgrade. |
|
protected |
Request | $req | |
string | $method | |
string | $server | |
int | $port | |
string | $path | |
array | $opts | the keys/values match self\getOptions |
CurlHandle|resource|false |
PhpXmlRpc\Client::getOption | ( | $name | ) |
string | $name | see all the OPT_ constants |
mixed |
ValueErrorException | on unsupported option |
PhpXmlRpc\Client::getOptions | ( | ) |
Returns the complete list of Client options, with their value.
array |
PhpXmlRpc\Client::getUrl | ( | $component = null | ) |
null | int | $component | allowed values: PHP_URL_SCHEME, PHP_URL_HOST, PHP_URL_PORT, PHP_URL_PATH |
string|int | Notes: the path component will include query string and fragment; NULL is a valid value for port (in which case the default port for http/https will be used); |
ValueErrorException | on unsupported component |
PhpXmlRpc\Client::multicall | ( | $reqs, | |
$timeout = 0, | |||
$method = '', | |||
$fallback = true ) |
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 xml-rpc 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 2np parameter to FALSE.
NB: trying to shoehorn extra functionality into existing syntax has resulted in pretty much convoluted code...
Request[] | $reqs | an array of Request objects |
bool | $noFallback | When true, upon receiving an error during multicall, multiple single calls will not be attempted. Deprecated alternative, was: int - "connection timeout (in seconds). See the details in the docs for the send() method". Please use setOption instead to set a timeout |
string | $method | deprecated. Was: "the http protocol variant to be used. See the details in the docs for the send() method." Please use the constructor to set an http protocol variant. |
boolean | $fallback | deprecated. Was: "w"hen true, upon receiving an error during multicall, multiple single calls will be attempted" |
Response[] |
|
protected |
$req | |
$server | |
$port | |
$timeout | |
$username | |
$password | |
$authType | |
$cert | |
$certPass | |
$caCert | |
$caCertDir | |
$proxyHost | |
$proxyPort | |
$proxyUsername | |
$proxyPassword | |
$proxyAuthType | |
$method | |
$keepAlive | |
$key | |
$keyPass | |
$sslVersion |
false|CurlHandle|resource |
PhpXmlRpc\Client::send | ( | $req, | |
$timeout = 0, | |||
$method = '' ) |
Send an xml-rpc request to the server.
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 xml-rpc 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 xml-rpc 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 xml-rpc functions (see http://www.php.net/xmlrpc) |
integer | $timeout | deprecated. Connection timeout, in seconds, If unspecified, the timeout set with setOption will be used. If that is 0, 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). |
string | $method | deprecated. Use the same value in the constructor instead. Valid values are 'http', 'http11', 'https', 'h2' and 'h2c'. If left empty, the http protocol chosen during creation of the object will be used. Use 'h2' to make the lib attempt to use http/2 over a secure connection, and 'h2c' for http/2 without tls. Note that 'h2c' will not use the h2c 'upgrade' method, and be thus incompatible with any server/proxy not supporting http/2. This is because POST request are not compatible with h2c upgrade. |
Response|Response[] | Note that the client will always return a Response object, even if the call fails |
allow throwing exceptions instead of returning responses in case of failed calls and/or Fault responses
refactor: we now support many options besides connection timeout and http version to use. Why only privilege those?
|
protected |
Request | $req | |
string | $server | |
int | $port | |
int | $timeout | |
string | $username | |
string | $password | |
int | $authType | |
string | $cert | |
string | $certPass | |
string | $caCert | |
string | $caCertDir | |
string | $proxyHost | |
int | $proxyPort | |
string | $proxyUsername | |
string | $proxyPassword | |
int | $proxyAuthType | |
string | $method | 'http' (let curl decide), 'http10', 'http11', 'https', 'h2c' or 'h2' |
bool | $keepAlive | |
string | $key | |
string | $keyPass | |
int | $sslVersion |
Response |
|
protected |
Request | $req | |
string | $server | |
int | $port | |
int | $timeout | |
string | $username | |
string | $password | |
int | $authType | |
string | $proxyHost | |
int | $proxyPort | |
string | $proxyUsername | |
string | $proxyPassword | |
int | $proxyAuthType | |
string | $method |
Response |
|
protected |
Request | $req | |
string | $server | |
int | $port | |
int | $timeout | |
string | $username | |
string | $password | |
int | $authType | |
string | $cert | |
string | $certPass | |
string | $caCert | |
string | $caCertDir | |
string | $proxyHost | |
int | $proxyPort | |
string | $proxyUsername | |
string | $proxyPassword | |
int | $proxyAuthType | |
bool | $keepAlive | |
string | $key | |
string | $keyPass | |
int | $sslVersion |
Response |
|
protected |
Request | $req | |
string | $server | |
int | $port | |
int | $timeout | |
string | $username | |
string | $password | |
int | $authType | only value supported is 1 |
string | $cert | |
string | $certPass | |
string | $caCert | |
string | $caCertDir | |
string | $proxyHost | |
int | $proxyPort | |
string | $proxyUsername | |
string | $proxyPassword | |
int | $proxyAuthType | only value supported is 1 |
string | $method | 'http' (synonym for 'http10'), 'http10' or 'https' |
string | $key | |
string | $keyPass |
int | $sslVersion |
Response |
|
protected |
Contributed by Justin Miller Requires curl to be built into PHP NB: CURL versions before 7.11.10 cannot use proxy to talk to https servers!
Request | $req | |
string | $method | |
string | $server | |
int | $port | |
string | $path | |
array | $opts | the keys/values match self\getOptions |
Response |
|
protected |
Request | $req | |
string | $method | |
string | $server | |
int | $port | |
string | $path | |
array | $opts |
Response |
PhpXmlRpc\Client::setAcceptedCompression | ( | $compMethod | ) |
Enables/disables reception of compressed xml-rpc responses.
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 xml-rpc requests. It is up to the xml-rpc server to return compressed responses when receiving such requests.
string | $compMethod | either 'gzip', 'deflate', 'any' or '' |
$this |
PhpXmlRpc\Client::setCaCertificate | ( | $caCert, | |
$isDir = false ) |
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.
string | $caCert | certificate file name (or dir holding certificates) |
bool | $isDir | set to true to indicate cacert is a dir. defaults to false |
$this |
PhpXmlRpc\Client::setCertificate | ( | $cert, | |
$certPass = '' ) |
Set the optional certificate and passphrase used in SSL-enabled communication with a remote server.
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.
string | $cert | the name of a file containing a PEM formatted certificate |
string | $certPass | the password required to use it |
$this |
PhpXmlRpc\Client::setCookie | ( | $name, | |
$value = '', | |||
$path = '', | |||
$domain = '', | |||
$port = null ) |
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 the xml-rpc payload).
NB: by default all cookies set via this method are sent to the server, regardless of path/domain/port. Taking advantage of those values is left to the single developer.
string | $name | nb: will not be escaped in the request's http headers. Take care not to use CTL chars or separators! |
string | $value | |
string | $path | |
string | $domain | |
int | $port | do not use! Cookies are not separated by port |
$this |
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...)
strip invalid chars from cookie name? As per RFC6265, we should follow RFC2616, Section 2.2
drop/rename $port parameter. Cookies are not isolated by port!
feature-creep allow storing 'expires', 'secure', 'httponly' and 'samesite' cookie attributes (we could do as php, and allow $path to be an array of attributes...)
PhpXmlRpc\Client::setCredentials | ( | $user, | |
$password, | |||
$authType = 1 ) |
Sets the username and password for authorizing the client to the 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 auth type parameter.
string | $user | username |
string | $password | password |
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. |
$this |
PhpXmlRpc\Client::setCurlOptions | ( | $options | ) |
Directly set cURL options, for extra flexibility (when in cURL mode).
It allows e.g. to bind client to a specific IP interface / address.
array | $options |
$this |
PhpXmlRpc\Client::setDebug | ( | $level | ) |
Enable/disable the echoing to screen of the xml-rpc responses received.
The default is not to 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 level 2, the complete payload of the xml-rpc request is also printed, before being sent to the server. At level -1, the Response objects returned by send() calls will not carry information about the http response's cookies, headers and body, which might save some memory
This option can be very useful when debugging servers as it allows you to see exactly what the client sends and the server returns. Never leave it enabled for production!
integer | $level | values -1, 0, 1 and 2 are supported |
$this |
PhpXmlRpc\Client::setKey | ( | $key, | |
$keyPass ) |
Set attributes for SSL communication: private SSL key.
NB: does not work in older php/curl installs. Thanks to Daniel Convissor.
string | $key | The name of a file containing a private SSL key |
string | $keyPass | The secret password needed to use the private SSL key |
$this |
PhpXmlRpc\Client::setOption | ( | $name, | |
$value ) |
string | $name | see all the OPT_ constants |
mixed | $value |
$this |
ValueErrorException | on unsupported option |
PhpXmlRpc\Client::setOptions | ( | $options | ) |
array | $options | key: any valid option (see all the OPT_ constants) |
$this |
ValueErrorException | on unsupported option |
PhpXmlRpc\Client::setProxy | ( | $proxyHost, | |
$proxyPort, | |||
$proxyUsername = '', | |||
$proxyPassword = '', | |||
$proxyAuthType = 1 ) |
Set proxy info.
NB: CURL versions before 7.11.10 cannot use a proxy to communicate with https servers.
string | $proxyHost | |
string | $proxyPort | Defaults to 8080 for HTTP and 443 for HTTPS |
string | $proxyUsername | Leave blank if proxy has public access |
string | $proxyPassword | Leave blank if proxy has public access |
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) |
$this |
PhpXmlRpc\Client::setRequestCompression | ( | $compMethod | ) |
Enables/disables http compression of xml-rpc request.
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).
string | $compMethod | either 'gzip', 'deflate' or '' |
$this |
PhpXmlRpc\Client::setSSLVerifyHost | ( | $i | ) |
Set attributes for SSL communication: verify the remote host's SSL certificate's common name (CN).
Note that support for value 1 has been removed in cURL 7.28.1
int | $i | Set to 1 to only the existence of a CN, not that it matches |
$this |
PhpXmlRpc\Client::setSSLVerifyPeer | ( | $i | ) |
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.
bool | $i | enable/disable verification of peer certificate |
$this |
PhpXmlRpc\Client::setSSLVersion | ( | $i | ) |
Set attributes for SSL communication: SSL version to use.
Best left at 0 (default value): let cURL decide
int | $i | see CURL_SSLVERSION_ constants |
$this |
PhpXmlRpc\Client::setUseCurl | ( | $useCurlMode | ) |
int | $useCurlMode | self\USE_CURL_ALWAYS, self\USE_CURL_AUTO or self\USE_CURL_NEVER |
$this |
PhpXmlRpc\Client::setUserAgent | ( | $agentString | ) |
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.
string | $agentString |
$this |
|
protected |
Charset encodings that can be decoded without problems by the client.
Value set at constructor time
|
protected |
List of http compression methods accepted by the client for responses.
NB: PHP supports deflate, gzip compressions out of the box if compiled w. zlib.
NNB: you can set it to any non-empty array for HTTP11 and HTTPS, since in those cases it will be up to CURL to decide the compression methods it supports. You might check for the presence of 'zlib' in the output of curl_version() to determine whether compression is supported or not
|
protected |
|
protected |
|
protected |
Whether to use persistent connections for http 1.1 and https.
Value set at constructor time.
|
protected |
|
protected |
This determines whether the multicall() method will try to take advantage of the system.multicall xml-rpc 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.
|
protected |
The charset encoding that will be used for serializing request sent by the client.
It defaults to NULL, which means using US-ASCII and encoding all characters outside the ASCII printable 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'. For the fastest mode of operation, set your both your app internal encoding and this to UTF-8.
|
protected |
Name of compression scheme to be used for sending requests.
Either null, 'gzip' or 'deflate'.
|
protected |
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 a 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 xml-rpc string or base64 value.
|
protected |
Sent to servers in http headers.
Value set at constructor time.