cvs: pear /SOAP Base.php Client.php Fault.php Header.php Message.php Parser.php Value.php

shane Sat Apr 27 14:33:25 2002 EDT Modified files: /pear/SOAP Base.php Client.php Fault.php Header.php Message.php Parser.php Value.php Log: work on code documentation

Index: pear/SOAP/Base.php diff -u pear/SOAP/Base.php:1.6 pear/SOAP/Base.php:1.7 --- pear/SOAP/Base.php:1.6 Mon Apr 8 03:11:51 2002 +++ pear/SOAP/Base.php Sat Apr 27 14:33:25 2002 @@ -17,21 +17,21 @@ // | Authors: Dietrich Ayala <dietrich@ganx4.com> Original Author | // +----------------------------------------------------------------------+ // -// $Id: Base.php,v 1.6 2002/04/08 07:11:51 shane Exp $ +// $Id: Base.php,v 1.7 2002/04/27 18:33:25 shane Exp $ // +require_once 'PEAR.php'; +#require_once 'SOAP/Fault.php'; + /** +* SOAP_Base * Common base class of all Soap lclasses -* -* @version $Id: Base.php,v 1.6 2002/04/08 07:11:51 shane Exp $ +* +* @access public +* @version $Id: Base.php,v 1.7 2002/04/27 18:33:25 shane Exp $ * @package SOAP::Client -* @author Shane Caraveo <Shane@Caraveo.com> Port to PEAR and more -* @author Dietrich Ayala <dietrich@ganx4.com> Original Author +* @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates */ - -require_once 'PEAR.php'; -#require_once 'SOAP/Fault.php'; - class SOAP_Base extends PEAR { @@ -68,7 +68,7 @@ /** - * ??? + * Constructor * * @param string error code * @see $debug_data, debug() @@ -129,6 +129,15 @@ } +/** +* QName +* class used to handle QNAME values in XML +* +* @access public +* @version $Id: Base.php,v 1.7 2002/04/27 18:33:25 shane Exp $ +* @package SOAP::Client +* @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates +*/ class QName { var $name = ''; Index: pear/SOAP/Client.php diff -u pear/SOAP/Client.php:1.27 pear/SOAP/Client.php:1.28 --- pear/SOAP/Client.php:1.27 Wed Apr 24 03:41:18 2002 +++ pear/SOAP/Client.php Sat Apr 27 14:33:25 2002 @@ -17,7 +17,7 @@ // | Authors: Dietrich Ayala <dietrich@ganx4.com> Original Author | // +----------------------------------------------------------------------+ // -// $Id: Client.php,v 1.27 2002/04/24 07:41:18 shane Exp $ +// $Id: Client.php,v 1.28 2002/04/27 18:33:25 shane Exp $ // require_once 'SOAP/Value.php'; @@ -38,7 +38,7 @@ * originaly based on SOAPx4 by Dietrich Ayala http://dietrich.ganx4.com/soapx4 * * @access public -* @version $Id: Client.php,v 1.27 2002/04/24 07:41:18 shane Exp $ +* @version $Id: Client.php,v 1.28 2002/04/27 18:33:25 shane Exp $ * @package SOAP::Client * @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates * @author Stig Bakken <ssb@fast.no> Conversion to PEAR @@ -64,7 +64,9 @@ var $endpoint = ''; /** - * + * portname + * + * @var string contains the SOAP PORT name that is used by the client */ var $portName = ''; @@ -83,10 +85,25 @@ */ var $wsdl = NULL; + /** + * wire + * + * @var string contains outoing and incoming data stream for debugging. + */ var $wire = NULL; + /** + * soapmsg + * + * @var SOAP_Message The soap message class that is used for outgoing calls. + */ var $soapmsg = NULL; + /** + * encoding + * + * @var string Contains the character encoding used for XML parser, etc. + */ var $encoding = SOAP_DEFAULT_ENCODING; /** * SOAP_Client constructor @@ -113,6 +130,16 @@ } } + /** + * setEncoding + * + * set the character encoding, limited to 'UTF-8', 'US_ASCII' and 'ISO-8859-1' + * + * @param string encoding + * + * @return mixed returns NULL or SOAP_Fault + * @access public + */ function setEncoding($encoding) { global $SOAP_Encodings; @@ -123,6 +150,16 @@ return $this->raiseSoapFault('Invalid Encoding'); } + /** + * addHeader + * + * To add headers to the envelop, you use this function, sending it a + * SOAP_Header class instance. + * + * @param SOAP_Header a soap value to send as a header + * + * @access public + */ function addHeader($soap_value) { if (!$this->soapmsg) { @@ -152,17 +189,20 @@ * to provide backwards compatibility with current clients, but * may be removed in the future. * - * OLD parameters - * @param string method - * @param array params - * @param string namespace (not required if using wsdl) - * @param string soapAction (not required if using wsdl) - * - * NEW parameters * @param string method * @param array params * @param array options (hash with namespace, soapaction, timeout, from, subject, etc.) * + * The options parameter can have a variety of values added. The currently supported + * values are: + * namespace + * soapaction + * timeout (http socket timeout) + * from (smtp) + * transfer-encoding (smtp, sets the Content-Transfer-Encoding header) + * subject (smtp, subject header) + * headers (smtp, array-hash of extra smtp headers) + * * @return array of results * @access public */ @@ -324,6 +364,15 @@ return $returnArray; } + /** + * setSchemaVersion + * + * sets the schema version used in the soap message + * + * @param string (see globals.php) + * + * @access private + */ function setSchemaVersion($schemaVersion) { global $SOAP_namespaces; Index: pear/SOAP/Fault.php diff -u pear/SOAP/Fault.php:1.5 pear/SOAP/Fault.php:1.6 --- pear/SOAP/Fault.php:1.5 Wed Apr 24 03:41:18 2002 +++ pear/SOAP/Fault.php Sat Apr 27 14:33:25 2002 @@ -17,32 +17,34 @@ // | Authors: Dietrich Ayala <dietrich@ganx4.com> Original Author | // +----------------------------------------------------------------------+ // -// $Id: Fault.php,v 1.5 2002/04/24 07:41:18 shane Exp $ +// $Id: Fault.php,v 1.6 2002/04/27 18:33:25 shane Exp $ // require_once('PEAR.php'); require_once('SOAP/Message.php'); /** -* define('SOAP_DEBUG', false); -* -* @package SOAP -* @access public -* @author Shane Caraveo <Shane@Caraveo.com> Port to PEAR and more -* @author Dietrich Ayala <dietrich@ganx4.com> Original Author -* @version $Id: Fault.php,v 1.5 2002/04/24 07:41:18 shane Exp $ -*/ + * SOAP_Fault + * PEAR::Error wrapper used to match SOAP Faults to PEAR Errors + * + * @package SOAP + * @access public + * @author Shane Caraveo <Shane@Caraveo.com> Port to PEAR and more + * @author Dietrich Ayala <dietrich@ganx4.com> Original Author + * @version $Id: Fault.php,v 1.6 2002/04/27 18:33:25 shane Exp $ + */ class SOAP_Fault extends PEAR_Error { /** - * - * - * @param string - * @param mixed - * @param mixed - * @param mixed - * @param mixed - */ + * Constructor + * + * @param string message string for fault + * @param mixed the faultcode + * @param mixed see PEAR::ERROR + * @param mixed see PEAR::ERROR + * @param array the userinfo array is used to pass in the + * SOAP actor and detail for the fault + */ function SOAP_Fault($message = 'unknown error', $code = null, $mode = null, $options = null, $userinfo = null) { @@ -58,26 +60,37 @@ } - // set up a fault + /** + * message + * + * returns a SOAP_Message class that can be sent as a server response + * + * @return SOAP_Message + * @access public + */ function message() { $msg = new SOAP_Message(); $msg->method('Fault', - array( - new SOAP_Value('faultcode', 'QName', 'SOAP-ENV:'.$this->code), - #'faultcode' => $this->code, - new SOAP_Value('faultstring', 'string', $this->message), - #'faultstring' => $this->message, - new SOAP_Value('faultactor', 'anyURI', $this->error_message_prefix), - #'faultactor' => $this->error_message_prefix, - new SOAP_Value('detail', 'string', $this->userinfo) - #'faultdetail' => $this->userinfo - ), - SOAP_ENVELOP - ); + array( + new SOAP_Value('faultcode', 'QName', 'SOAP-ENV:'.$this->code), + new SOAP_Value('faultstring', 'string', $this->message), + new SOAP_Value('faultactor', 'anyURI', $this->error_message_prefix), + new SOAP_Value('detail', 'string', $this->userinfo) + ), + SOAP_ENVELOP + ); return $msg; } + /** + * getFault + * + * returns a simple native php array containing the fault data + * + * @return array + * @access public + */ function getFault() { return array( @@ -88,11 +101,27 @@ ); } + /** + * getActor + * + * returns the SOAP actor for the fault + * + * @return string + * @access public + */ function getActor() { return $this->error_message_prefix; } + /** + * getDetail + * + * returns the fault detail + * + * @return string + * @access public + */ function getDetail() { return $this->userinfo; Index: pear/SOAP/Header.php diff -u pear/SOAP/Header.php:1.1 pear/SOAP/Header.php:1.2 --- pear/SOAP/Header.php:1.1 Sat Mar 30 18:13:21 2002 +++ pear/SOAP/Header.php Sat Apr 27 14:33:25 2002 @@ -17,38 +17,41 @@ // | Authors: Dietrich Ayala <dietrich@ganx4.com> Original Author | // +----------------------------------------------------------------------+ // -// $Id: Header.php,v 1.1 2002/03/30 23:13:21 shane Exp $ +// $Id: Header.php,v 1.2 2002/04/27 18:33:25 shane Exp $ // require_once 'SOAP/Base.php'; require_once 'SOAP/globals.php'; require_once 'SOAP/Value.php'; /** -* SOAP::Value -* this class converts values between PHP and SOAP -* -* originaly based on SOAPx4 by Dietrich Ayala http://dietrich.ganx4.com/soapx4 -* -* @access public -* @version $Id: Header.php,v 1.1 2002/03/30 23:13:21 shane Exp $ -* @package SOAP::Client -* @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates -* @author Dietrich Ayala <dietrich@ganx4.com> Original Author -*/ + * SOAP::Header + * this class converts values between PHP and SOAP + * it is a simple wrapper around SOAP_Value, adding support for + * soap actor and mustunderstand parameters + * + * originaly based on SOAPx4 by Dietrich Ayala http://dietrich.ganx4.com/soapx4 + * + * @access public + * @version $Id: Header.php,v 1.2 2002/04/27 18:33:25 shane Exp $ + * @package SOAP::Client + * @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates + * @author Dietrich Ayala <dietrich@ganx4.com> Original Author + */ class SOAP_Header extends SOAP_Value { var $actor = NULL; var $mustunderstand = 0; /** - * - * - * @param string name of the soap-value <value_name> - * @param mixed soap header value - * @param int namespace - * @param mixed actor - * @param mixed wsdl - */ + * Constructor + * + * @param string name of the soap-value <value_name> + * @param mixed soap header value + * @param string namespace + * @param int mustunderstand (zero or one) + * @param string actor + * @param SOAP_WSDL wsdl + */ function SOAP_Header($name = '', $type, $value = NULL, $namespace = NULL, $mustunderstand = 0, $actor = 'http://schemas.xmlsoap.org/soap/actor/next', Index: pear/SOAP/Message.php diff -u pear/SOAP/Message.php:1.13 pear/SOAP/Message.php:1.14 --- pear/SOAP/Message.php:1.13 Mon Apr 15 02:45:39 2002 +++ pear/SOAP/Message.php Sat Apr 27 14:33:25 2002 @@ -17,7 +17,7 @@ // | Authors: Dietrich Ayala <dietrich@ganx4.com> Original Author | // +----------------------------------------------------------------------+ // -// $Id: Message.php,v 1.13 2002/04/15 06:45:39 shane Exp $ +// $Id: Message.php,v 1.14 2002/04/27 18:33:25 shane Exp $ // require_once 'SOAP/globals.php'; @@ -27,25 +27,25 @@ require_once 'SOAP/Header.php'; /** -* SOAP Message Class -* this class serializes and deserializes soap messages for transport (see SOAP::Transport) -* -* originaly based on SOAPx4 by Dietrich Ayala http://dietrich.ganx4.com/soapx4 -* -* @access public -* @version $Id: Message.php,v 1.13 2002/04/15 06:45:39 shane Exp $ -* @package SOAP::Message -* @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates -* @author Dietrich Ayala <dietrich@ganx4.com> Original Author -*/ + * SOAP Message Class + * this class serializes and deserializes soap messages for transport (see SOAP::Transport) + * + * originaly based on SOAPx4 by Dietrich Ayala http://dietrich.ganx4.com/soapx4 + * + * @access public + * @version $Id: Message.php,v 1.14 2002/04/27 18:33:25 shane Exp $ + * @package SOAP::Message + * @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates + * @author Dietrich Ayala <dietrich@ganx4.com> Original Author + */ class SOAP_Message extends SOAP_Base { /** - * XML payload - * - * @var string - */ + * XML payload + * + * @var string + */ var $payload = ''; /** @@ -56,26 +56,26 @@ var $namespaces; /** - * SOAP value - * - * @var object SOAP_value - */ + * SOAP value + * + * @var object SOAP_value + */ var $value = ''; var $headers = array(); /** - * SOAP::Message constructor - * - * initializes a soap structure containing the method signature and parameters - * - * @param string $method soap data (in xml) - * @param array(SOAP::Value) $params soap data (in xml) - * @param string $method_namespace soap data (in xml) - * @param array of string $new_namespaces soap data (in xml) - * - * @access public - */ + * SOAP::Message constructor + * + * initializes a soap structure containing the method signature and parameters + * + * @param string $method soap data (in xml) + * @param array(SOAP::Value) $params soap data (in xml) + * @param string $method_namespace soap data (in xml) + * @param array of string $new_namespaces soap data (in xml) + * + * @access public + */ function SOAP_Message($new_namespaces = NULL, $wsdl = NULL) { parent::SOAP_Base('Message'); @@ -90,11 +90,31 @@ } } + /** + * addHeader + * + * adds a new header to the envelope + * + * @param SOAP_Header $soap_value + * + * @access public + */ function addHeader($soap_value) { $this->headers[] = $soap_value; } + /** + * method + * + * adds the method call to the soap envelope + * + * @param string $method_name + * @param mixed $params + * @param string $method_namespace (defaults to NULL) + * + * @access public + */ function method($method, $params, $method_namespace = NULL) { // make method struct @@ -102,12 +122,12 @@ } /** - * wraps the soap payload with the soap envelop data - * - * @param string $payload soap data (in xml) - * @return string xml_soap_data - * @access private - */ + * wraps the soap payload with the soap envelop data + * + * @param string $payload soap data (in xml) + * @return string xml_soap_data + * @access private + */ function _makeEnvelope($header, $body, $encoding) { global $SOAP_namespaces; @@ -121,13 +141,13 @@ } /** - * wraps the soap Header - * - * @param string $payload soap data (in xml) - * - * @return string xml_soap_data - * @access private - */ + * wraps the soap Header + * + * @param string $payload soap data (in xml) + * + * @return string xml_soap_data + * @access private + */ function _makeHeader() { $payload = ''; @@ -139,23 +159,24 @@ } /** - * wraps the soap body - * - * @param string $payload soap data (in xml) - * - * @return string xml_soap_data - * @access private - */ + * wraps the soap body + * + * @param string $payload soap data (in xml) + * + * @return string xml_soap_data + * @access private + */ function _makeBody($payload) { return "<SOAP-ENV:Body>\r\n$payload\r\n</SOAP-ENV:Body>\r\n"; } /** - * creates an xml string representation of the soap message data - * - * @access private - */ + * creates an xml string representation of the soap message data + * + * @param string $encoding character encoding for the message + * @access private + */ function _createPayload($encoding) { $body = $this->value?$this->_makeBody($this->value->serialize()):NULL; @@ -164,11 +185,12 @@ } /** - * serializes this classes data into xml - * - * @return string xml_soap_data - * @access public - */ + * serializes this classes data into xml + * + * @param string character encoding for the message + * @return string xml_soap_data + * @access public + */ function serialize($encoding = SOAP_DEFAULT_ENCODING) { if ($this->payload == '') { @@ -179,13 +201,13 @@ } /** - * parses a soap message - * - * @param string $data soap message (in xml) - * - * @return SOAP::Value - * @access public - */ + * parses a soap message + * + * @param string $data soap message (in xml) + * + * @return SOAP::Value + * @access public + */ function parseResponse($data) { // parse response Index: pear/SOAP/Parser.php diff -u pear/SOAP/Parser.php:1.20 pear/SOAP/Parser.php:1.21 --- pear/SOAP/Parser.php:1.20 Tue Apr 16 03:41:11 2002 +++ pear/SOAP/Parser.php Sat Apr 27 14:33:25 2002 @@ -17,7 +17,7 @@ // | Authors: Dietrich Ayala <dietrich@ganx4.com> Original Author | // +----------------------------------------------------------------------+ // -// $Id: Parser.php,v 1.20 2002/04/16 07:41:11 shane Exp $ +// $Id: Parser.php,v 1.21 2002/04/27 18:33:25 shane Exp $ // require_once 'SOAP/globals.php'; @@ -31,7 +31,7 @@ * originaly based on SOAPx4 by Dietrich Ayala http://dietrich.ganx4.com/soapx4 * * @access public -* @version $Id: Parser.php,v 1.20 2002/04/16 07:41:11 shane Exp $ +* @version $Id: Parser.php,v 1.21 2002/04/27 18:33:25 shane Exp $ * @package SOAP::Parser * @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates * @author Dietrich Ayala <dietrich@ganx4.com> Original Author @@ -63,6 +63,12 @@ var $XMLSchemaVersion; var $bodyDepth; // used to handle non-root elements before root body element + /** + * SOAP_Parser constructor + * + * @param string xml content + * @param string xml character encoding, defaults to 'UTF-8' + */ function SOAP_Parser($xml, $encoding = SOAP_DEFAULT_ENCODING) { parent::SOAP_Base('Parser'); @@ -107,6 +113,13 @@ } } + /** + * setSchemaVersion + * sets the schema for the resulting message + * + * @param string schema version + * @access private + */ function setSchemaVersion($schemaVersion) { global $SOAP_namespaces; @@ -117,7 +130,12 @@ $SOAP_namespaces = array_flip($tmpNS); } - // recurse to build a multi-dim array + /** + * domulti + * recurse to build a multi-dim array, used by buildResponse + * + * @access private + */ function domulti($d, &$ar, &$r, &$v, $ad=0) { if ($d) { @@ -127,7 +145,14 @@ } } - // loop through msg, building response structures + /** + * buildResponse + * loop through msg, building response structures + * + * @param int position + * @return SOAP_Value + * @access private + */ function buildResponse($pos) { $response = NULL; @@ -187,7 +212,12 @@ return $response; } - // start-element handler + /** + * startElement + * start-element handler used with xml parser + * + * @access private + */ function startElement($parser, $name, $attrs) { global $SOAP_XMLSchema; @@ -340,7 +370,12 @@ } } - // end-element handler + /** + * endElement + * end-element handler used with xml parser + * + * @access private + */ function endElement($parser, $name) { // position of current element is equal to the last value left in depth_array for my depth @@ -400,14 +435,27 @@ } } - // element content handler + /** + * characterData + * element content handler used with xml parser + * + * @access private + */ function characterData($parser, $data) { $pos = $this->depth_array[$this->depth]; $this->message[$pos]['cdata'] .= $data; } - // have this return a soap_val object + /** + * getResponse + * + * returns an array of responses + * after parsing a soap message, use this to get the response + * + * @return array + * @access public + */ function getResponse() { if ($this->soapresponse) { @@ -416,7 +464,15 @@ return $this->raiseSoapFault("couldn't build response"); } - // have this return a soap_val object + /** + * getHeaders + * + * returns an array of header responses + * after parsing a soap message, use this to get the response + * + * @return array + * @access public + */ function getHeaders() { if ($this->soapheaders) { @@ -427,6 +483,15 @@ return NULL; } + /** + * decodeEntities + * + * removes entities from text + * + * @param string + * @return string + * @access private + */ function decodeEntities($text) { $trans_tbl = array_flip($this->entities); Index: pear/SOAP/Value.php diff -u pear/SOAP/Value.php:1.27 pear/SOAP/Value.php:1.28 --- pear/SOAP/Value.php:1.27 Wed Apr 17 03:42:52 2002 +++ pear/SOAP/Value.php Sat Apr 27 14:33:25 2002 @@ -17,7 +17,7 @@ // | Authors: Dietrich Ayala <dietrich@ganx4.com> Original Author | // +----------------------------------------------------------------------+ // -// $Id: Value.php,v 1.27 2002/04/17 07:42:52 shane Exp $ +// $Id: Value.php,v 1.28 2002/04/27 18:33:25 shane Exp $ // require_once 'SOAP/Base.php'; require_once 'SOAP/globals.php'; @@ -31,7 +31,7 @@ * originaly based on SOAPx4 by Dietrich Ayala http://dietrich.ganx4.com/soapx4 * * @access public -* @version $Id: Value.php,v 1.27 2002/04/17 07:42:52 shane Exp $ +* @version $Id: Value.php,v 1.28 2002/04/27 18:33:25 shane Exp $ * @package SOAP::Client * @author Shane Caraveo <shane@php.net> Conversion to PEAR and updates * @author Dietrich Ayala <dietrich@ganx4.com> Original Author @@ -173,13 +173,14 @@ } /** - * - * - * @param - * @param - * @param - * @return boolean - */ + * + * + * @param + * @param + * @param + * @return boolean + * @access private + */ function addScalar($value, $type, $name = '') { if ($type == 'string') {