From d955a8984d0cc151784f4e28360cad3d97bd6278 Mon Sep 17 00:00:00 2001 From: John Jawed Date: Thu, 2 Aug 2012 18:56:18 +0000 Subject: [PATCH] Adding ext/xcom docs git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@326948 c90b9560-bf6c-de11-be94-00142212c4b1 --- appendices/extensions.xml | 3 + reference/x-commerce/book.developer.xml | 76 +++++++++ reference/x-commerce/book.xml | 43 +++++ reference/x-commerce/configure.xml | 37 +++++ reference/x-commerce/constants.xml | 28 ++++ reference/x-commerce/entities.xcom.xml | 8 + reference/x-commerce/reference.xml | 28 ++++ reference/x-commerce/setup.xml | 63 +++++++ reference/x-commerce/versions.xml | 49 ++++++ reference/x-commerce/xcom.xml | 85 ++++++++++ reference/x-commerce/xcom/construct.xml | 77 +++++++++ reference/x-commerce/xcom/decode.xml | 102 ++++++++++++ reference/x-commerce/xcom/encode.xml | 107 ++++++++++++ reference/x-commerce/xcom/getdebugoutput.xml | 87 ++++++++++ reference/x-commerce/xcom/getlastresponse.xml | 81 +++++++++ .../x-commerce/xcom/getlastresponseinfo.xml | 57 +++++++ reference/x-commerce/xcom/send.xml | 157 ++++++++++++++++++ reference/x-commerce/xcom/sendasync.xml | 146 ++++++++++++++++ 18 files changed, 1234 insertions(+) create mode 100644 reference/x-commerce/book.developer.xml create mode 100644 reference/x-commerce/book.xml create mode 100644 reference/x-commerce/configure.xml create mode 100644 reference/x-commerce/constants.xml create mode 100644 reference/x-commerce/entities.xcom.xml create mode 100644 reference/x-commerce/reference.xml create mode 100644 reference/x-commerce/setup.xml create mode 100644 reference/x-commerce/versions.xml create mode 100644 reference/x-commerce/xcom.xml create mode 100644 reference/x-commerce/xcom/construct.xml create mode 100644 reference/x-commerce/xcom/decode.xml create mode 100644 reference/x-commerce/xcom/encode.xml create mode 100644 reference/x-commerce/xcom/getdebugoutput.xml create mode 100644 reference/x-commerce/xcom/getlastresponse.xml create mode 100644 reference/x-commerce/xcom/getlastresponseinfo.xml create mode 100644 reference/x-commerce/xcom/send.xml create mode 100644 reference/x-commerce/xcom/sendasync.xml diff --git a/appendices/extensions.xml b/appendices/extensions.xml index 4cd667cb48..44cabdd166 100644 --- a/appendices/extensions.xml +++ b/appendices/extensions.xml @@ -224,6 +224,7 @@ + @@ -454,6 +455,7 @@ + @@ -572,6 +574,7 @@ + diff --git a/reference/x-commerce/book.developer.xml b/reference/x-commerce/book.developer.xml new file mode 100644 index 0000000000..502c3bcc1d --- /dev/null +++ b/reference/x-commerce/book.developer.xml @@ -0,0 +1,76 @@ + + + + + + + +%xhtml-lat1; +%xhtml-symbol; +%xhtml-special; +%isopub; + + + + + + +%language-defs.default; +%extensions.default; +%language-snippets.default; + + + + + + + + + +%global.entities; +%file.entities; +%frontpage.entities; +]> + + + X.commerce + X.commerce + + + &reftitle.intro; + + + + + + &reference.x-commerce.setup; + &reference.x-commerce.constants; + &reference.x-commerce.examples; + &reference.x-commerce.reference; + + + + + diff --git a/reference/x-commerce/book.xml b/reference/x-commerce/book.xml new file mode 100644 index 0000000000..25e2350fc2 --- /dev/null +++ b/reference/x-commerce/book.xml @@ -0,0 +1,43 @@ + + + + + X.commerce + X.commerce + + + &reftitle.intro; + + This extension provides X.commerce bindings and avro helper methods. + X.commerce provides developers + and merchants an ecosystem to build as well as utilize commerce API's built + by others. It supports multi-tenancy, asynchronous/synchronous calls, + and service onboarding. + + + + &reference.x-commerce.setup; + &reference.x-commerce.xcom; + + + + diff --git a/reference/x-commerce/configure.xml b/reference/x-commerce/configure.xml new file mode 100644 index 0000000000..28685d68a0 --- /dev/null +++ b/reference/x-commerce/configure.xml @@ -0,0 +1,37 @@ + + + +
+ &reftitle.install; + + + Use when compiling PHP. + + + + Windows users should include php_x-commerce.dll into &php.ini; + + +
+ + + diff --git a/reference/x-commerce/constants.xml b/reference/x-commerce/constants.xml new file mode 100644 index 0000000000..6ce60a4616 --- /dev/null +++ b/reference/x-commerce/constants.xml @@ -0,0 +1,28 @@ + + + + + &reftitle.constants; + &no.constants; + + + diff --git a/reference/x-commerce/entities.xcom.xml b/reference/x-commerce/entities.xcom.xml new file mode 100644 index 0000000000..3b5c5477f0 --- /dev/null +++ b/reference/x-commerce/entities.xcom.xml @@ -0,0 +1,8 @@ +&reference.x-commerce.xcom.construct; +&reference.x-commerce.xcom.decode; +&reference.x-commerce.xcom.encode; +&reference.x-commerce.xcom.getdebugoutput; +&reference.x-commerce.xcom.getlastresponse; +&reference.x-commerce.xcom.getlastresponseinfo; +&reference.x-commerce.xcom.send; +&reference.x-commerce.xcom.sendasync; diff --git a/reference/x-commerce/reference.xml b/reference/x-commerce/reference.xml new file mode 100644 index 0000000000..96a2295fac --- /dev/null +++ b/reference/x-commerce/reference.xml @@ -0,0 +1,28 @@ + + + + + X.commerce &Functions; + + + + diff --git a/reference/x-commerce/setup.xml b/reference/x-commerce/setup.xml new file mode 100644 index 0000000000..52c6a2677a --- /dev/null +++ b/reference/x-commerce/setup.xml @@ -0,0 +1,63 @@ + + + + + &reftitle.setup; + +
+ &reftitle.required; + + ext/xcom requires PHP 5.1 or newer. + + + ext/xcom requires libcurl (which must be built with HTTPS + support). + + + ext/xcom requires libavro (which comes bundled in the package + but the installation will prefer the system libavro if available). + +
+ +
+ &reftitle.install; + + &pecl.info; + &url.pear.package;xcom + +
+ +
+ &reftitle.runtime; + &no.config; +
+ +
+ &reftitle.resources; + + + +
+ +
+ + diff --git a/reference/x-commerce/versions.xml b/reference/x-commerce/versions.xml new file mode 100644 index 0000000000..dac6387715 --- /dev/null +++ b/reference/x-commerce/versions.xml @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/reference/x-commerce/xcom.xml b/reference/x-commerce/xcom.xml new file mode 100644 index 0000000000..fc6e4a4bfc --- /dev/null +++ b/reference/x-commerce/xcom.xml @@ -0,0 +1,85 @@ + + + + + + The Xcom class + Xcom + + + + +
+ &reftitle.intro; + + + +
+ + +
+ &reftitle.classsynopsis; + + + + Xcom + + + + + Xcom + + + + + Properties + + public + __debug + + + &Methods; + + + + +
+ +
+ &reftitle.properties; + + + __debug + + Set this to a non-FALSE value to enable debug mode + + + +
+ +
+ + &reference.x-commerce.entities.xcom; + +
+ + diff --git a/reference/x-commerce/xcom/construct.xml b/reference/x-commerce/xcom/construct.xml new file mode 100644 index 0000000000..b40030dcf5 --- /dev/null +++ b/reference/x-commerce/xcom/construct.xml @@ -0,0 +1,77 @@ + + + + + + Xcom::__construct + Create a new Xcom object + + + + &reftitle.description; + + public Xcom::__construct + stringfabric_url + stringfabric_token + stringcapability_token + + + Creates a new Xcom object + + + + + &reftitle.parameters; + + + + fabric_url + + + The fabric endpoint (XCOM_FABRIC_PRODUCTION for + production and XCOM_FABRIC_SANDBOX for sandbox). + + + + + fabric_token + + + The fabric token provided to you, pass an empty string if you only send messages. + + + + + capability_token + + + The capability token, it is used when sending messages. + + + + + + + + + + diff --git a/reference/x-commerce/xcom/decode.xml b/reference/x-commerce/xcom/decode.xml new file mode 100644 index 0000000000..3a036d711a --- /dev/null +++ b/reference/x-commerce/xcom/decode.xml @@ -0,0 +1,102 @@ + + + + + + Xcom::decode + Decodes an avro-encoded message + + + + &reftitle.description; + + public objectXcom::decode + stringavro_msg + stringjson_schema + + + This method decodes an avro message. + + + + + &reftitle.parameters; + + + avro_message + + + The binary avro message to be decoded. + + + + + json_schema + + + The avro JSON schema (avpr) to be used in decoding the message. + + + + + + + + &reftitle.returnvalues; + + Returns a stdClass object, or FALSE on failure. + + + + + &reftitle.examples; + + + <function>Xcom::decode</function> example + +decode($avro_payload, $schema); + +?> +]]> + + + + + + + &reftitle.seealso; + + + Xcom::encode + + + + + + + + diff --git a/reference/x-commerce/xcom/encode.xml b/reference/x-commerce/xcom/encode.xml new file mode 100644 index 0000000000..a2e126d885 --- /dev/null +++ b/reference/x-commerce/xcom/encode.xml @@ -0,0 +1,107 @@ + + + + + + Xcom::encode + Encode an avro message + + + + &reftitle.description; + + public stringXcom::encode + stdClassdata + stringavro_schema + + + This method encodes a stdClass object to an + avro binary encoded blob. + + + + + + &reftitle.parameters; + + + data + + + A stdClass compatible object to encode. + + + + + avro_schema + + + The avro JSON schema to encode the data against. + + + + + + + + &reftitle.returnvalues; + + Returns an avro-encoded string or FALSE on failure. + + + + + &reftitle.examples; + + + <function>Xcom::encode</function> example + +orderID = "foo1234"; + +$schema = file_get_contents('http://api.x.com/ocl/com.x.example.v1/OrderFulfillment/OrderShipped/1.2.0/'); +$xcom = new Xcom(); +$xcom->encode($data, $schema); + +?> +]]> + + + + + + + &reftitle.seealso; + + + Xcom::decode + + + + + + + + diff --git a/reference/x-commerce/xcom/getdebugoutput.xml b/reference/x-commerce/xcom/getdebugoutput.xml new file mode 100644 index 0000000000..3c0e736c7b --- /dev/null +++ b/reference/x-commerce/xcom/getdebugoutput.xml @@ -0,0 +1,87 @@ + + + + + + Xcom::getDebugOutput + Get the debug output + + + + &reftitle.description; + + public stringXcom::getDebugOutput + + + + Get the full request/response headers and body from the previous + message (if Xcom::__debug was set to a + non-FALSE value before the + Xcom::send). This call does not work for + messages which are sent using Xcom::sendAsync. + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a string containing request/response debug information. + + + + + &reftitle.examples; + + + <function>Xcom::getDebugOutput</function> example + +orderID = "123495585343"; + +$xcom = new Xcom(XCOM_FABRIC_SANDBOX, "fabric_token", "capability_token"); + +$xcom->send("/com.x.example.v1/OrderFulfillment/OrderShipped", $data, $schema); + +echo "Debug output: " . $xcom->getDebugOutput(); + +?> +]]> + + + + + + + + + diff --git a/reference/x-commerce/xcom/getlastresponse.xml b/reference/x-commerce/xcom/getlastresponse.xml new file mode 100644 index 0000000000..2bc54237c5 --- /dev/null +++ b/reference/x-commerce/xcom/getlastresponse.xml @@ -0,0 +1,81 @@ + + + + + + Xcom::getLastResponse + Get the last response body + + + + &reftitle.description; + + public stringXcom::getLastResponse + + + + Fetch the body of the last response. Mostly useful when debugging + error messages, often times the reason for a failure is documentated + in the response body (ie, Invalid Token, bad HTTP method, etc.) + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns a string containing the last response. + + + + + &reftitle.examples; + + + <function>Xcom::getLastResponse</function> example + +send("/com.x.example.v1/OrderFulfillment/OrderShipped", $data); + +echo "I failed because: " . $xcom->getLastResponse(); + +?> +]]> + + + + + + + + diff --git a/reference/x-commerce/xcom/getlastresponseinfo.xml b/reference/x-commerce/xcom/getlastresponseinfo.xml new file mode 100644 index 0000000000..ac8d64bf2d --- /dev/null +++ b/reference/x-commerce/xcom/getlastresponseinfo.xml @@ -0,0 +1,57 @@ + + + + + + Xcom::getLastResponseInfo + Gets the last response HTTP information + + + + &reftitle.description; + + public arrayXcom::getLastResponseInfo + + + + Get the last response information such as HTTP response code, latencies, + and redirect URL's. + + + + + + &reftitle.parameters; + &no.function.parameters; + + + + &reftitle.returnvalues; + + Returns an array containing HTTP response information. + + + + + + + diff --git a/reference/x-commerce/xcom/send.xml b/reference/x-commerce/xcom/send.xml new file mode 100644 index 0000000000..e1662009a7 --- /dev/null +++ b/reference/x-commerce/xcom/send.xml @@ -0,0 +1,157 @@ + + + + + + Xcom::send + Send a message + + + + &reftitle.description; + + public intXcom::send + stringtopic + mixeddata + stringjson_schema + arrayhttp_headers + + + Send a message to a capability (API provider) for a topic. + + + + + &reftitle.parameters; + + If json_schema is specified, the data + must be an object and is encoded as an avro-encoded message. + + + If json_schema is not specified, the data + will be converted to a string and sent. + + + + + topic + + + The topic path (ie, /store/get/orders). + + + + + data + + + The data to be sent. + + + + + json_schema + + + The avro JSON schema if data is an object, + if left empty there is no avro encoding. + + + + + http_headers + + + HTTP client headers (such as User-Agent, Accept, etc.) + + + + + + + + + &reftitle.returnvalues; + + Returns the HTTP response code, or FALSE on failure. + + + + + &reftitle.examples; + + + <function>Xcom::send</function> example (avro) + +orderID = "123495585343"; + +$xcom = new Xcom(XCOM_FABRIC_SANDBOX, "fabric_token", "capability_token"); + +var_dump($xcom->send("/com.x.example.v1/OrderFulfillment/OrderShipped", $data, $schema)); + +/* +* Output: +* int(200) +*/ +?> +]]> + + + + <function>Xcom::send</function> example (arbitrary payload) + +send("/get/profile", 'request-payload')); + +/* +* Output: +* int(200) +*/ +?> +]]> + + + + + + + &reftitle.seealso; + + + Xcom::sendAsync + + + + + + + diff --git a/reference/x-commerce/xcom/sendasync.xml b/reference/x-commerce/xcom/sendasync.xml new file mode 100644 index 0000000000..7b1c8493b5 --- /dev/null +++ b/reference/x-commerce/xcom/sendasync.xml @@ -0,0 +1,146 @@ + + + + + + Xcom::sendAsync + Send a message asynchronously + + + + &reftitle.description; + + public intXcom::sendAsync + stringtopic + mixeddata + stringjson_schema + arrayhttp_headers + + + Send a message to a capability (API provider) for a topic asynchronously (using pthreads). + + + + + &reftitle.parameters; + + If json_schema is specified, the data + must be an object and is encoded as an avro-encoded message. + + + If json_schema is not specified, the data + will be converted to a string and sent. + + + + + topic + + + The topic path (ie, /store/get/orders). + + + + + data + + + The data to be sent. + + + + + json_schema + + + The avro JSON schema if data is an object, + if left empty there is no avro encoding. + + + + + http_headers + + + HTTP client headers (such as User-Agent, Accept, etc.) + + + + + + + + + &reftitle.returnvalues; + + Returns 0. + + + + + &reftitle.examples; + + + <function>Xcom::sendAsync</function> example (avro) + +orderID = "123495585343"; + +$xcom = new Xcom(XCOM_FABRIC_SANDBOX, "fabric_token", "capability_token"); + +$xcom->sendAsync("/com.x.example.v1/OrderFulfillment/OrderShipped", $data, $schema); +?> +]]> + + + + <function>Xcom::send</function> example (arbitrary payload) + +sendAsync("/get/profile", 'request-payload'); +?> +]]> + + + + + + + &reftitle.seealso; + + + Xcom::send + + + + + + +