{
    "mode": "perldoc",
    "parameter": "SOAP::SOM",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/SOAP%3A%3ASOM/json",
    "generated": "2026-06-09T12:05:25Z",
    "sections": {
        "NAME": {
            "content": "SOAP::SOM - provides access to the values contained in SOAP Response\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Objects from the SOAP::SOM class aren't generally instantiated directly by an application.\nRather, they are handed back by the deserialization of a message. In other words, developers\nwill almost never do this:\n\n$som = SOAP::SOM->new;\n\nSOAP::SOM objects are returned by a SOAP::Lite call in a client context. For example:\n\nmy $client = SOAP::Lite\n->readable(1)\n->uri($NS)\n->proxy($HOST)\n$som = $client->someMethod();\n",
            "subsections": []
        },
        "METHODS": {
            "content": "",
            "subsections": [
                {
                    "name": "new",
                    "content": "$som = SOAP::SOM->new($messageasxml);\n\nAs said, the need to actually create an object of this class should be very rare. However,\nif the need arises, the syntax must be followed. The single argument to new must be a valid\nXML document the parser will understand as a SOAP response.\n\nThe following group of methods provide general data retrieval from the SOAP::SOM object. The\nmodel for this is an abbreviated form of XPath. Following this group are methods that are geared\ntowards specific retrieval of commonly requested elements.\n"
                },
                {
                    "name": "match",
                    "content": "$som->match('/Envelope/Body/[1]');\n\nThis method sets the internal pointers within the data structure so that the retrieval\nmethods that follow will have access to the desired data. In the example path, the match is\nbeing made against the method entity, which is the first child tag of the body in a SOAP\nresponse. The enumeration of container children starts at 1 in this syntax, not 0. The\nreturned value is dependent on the context of the call. If the call is made in a boolean\ncontext (such as \"if ($som->match($path))\"), the return value is a boolean indicating\nwhether the requested path matched at all. Otherwise, an object reference is returned. The\nreturned object is also a SOAP::SOM instance but is smaller, containing the subset of the\ndocument tree matched by the expression.\n"
                },
                {
                    "name": "valueof",
                    "content": "$res = $som->valueof('[1]');\n\nWhen the SOAP::SOM object has matched a path internally with the match method, this method\nallows retrieval of the data within any of the matched nodes. The data comes back as native\nPerl data, not a class instance (see dataof). In a scalar context, this method returns just\nthe first element from a matched node set. In an array context, all elements are returned.\nAssuming that the earlier call happens after the earlier call to match, it retrieves the\nresult entity from the method response that is contained in $som, as this is the first child\nelement in a method-response tag.\n"
                },
                {
                    "name": "dataof",
                    "content": "$resobj = $som->dataof('[1]');\n\nPerforms the same operation as the earlier valueof method, except that the data is left in\nits SOAP::Data form, rather than being deserialized. This allows full access to all the\nattributes that were serialized along with the data, such as namespace and encoding.\n"
                },
                {
                    "name": "headerof",
                    "content": "$resobj = $som->headerof('[1]');\n\nActs much like dataof, except that it returns an object of the SOAP::Header class (covered\nlater in this chapter), rather than SOAP::Data. This is the preferred interface for\nmanipulating the header entities in a message.\n"
                },
                {
                    "name": "namespaceuriof",
                    "content": "$ns = $som->namespaceof('[1]');\n\nRetrieves the namespace URI that governs the requested node. Note that namespaces are\ninherited, so this method will return the relevant value, even if it derives from a parent\nor other ancestor node.\n\nThe following methods provide more direct access to the message envelope. All these methods\nreturn some form of a Perl value, most often a hash reference, when called. Context is also\nrelevant: in a scalar context only the first matching node is returned, while in an array\ncontext, all matching nodes are. When called as a static method or as a regular function (such\nas \"SOAP::SOM::envelope\"), any of the following methods returns the XPath string that is used\nwith the match method to retrieve the data.\n\nroot\n$root = $som->root;\n\nReturns the value of the root element as a hash reference. It behaves exactly as\n\"$som-\"valueof('/')> does.\n\nenvelope\n$envelope = $som->envelope;\n\nRetrieves the \"Envelope\" element of the message, returning it and its data as a hash\nreference. Keys in the hash will be Header and Body (plus any optional elements that may be\npresent in a SOAP 1.1 envelope), whose values will be the serialized header and body,\nrespectively.\n\nheader\n$header = $som->header;\n\nRetrieves the header portion of the envelope as a hash reference. All data within it will\nhave been deserialized. If the attributes of the header are desired, the static form of the\nmethod can be combined with match to fetch the header as a SOAP::Data object:\n\n$header = $som->match(SOAP::SOM::header)->dataof;\n\nheaders\n@hdrs = $som->headers;\n\nRetrieves the node set of values with deserialized headers from within the Header container.\nThis is different from the earlier header method in that it returns the whole header as a\nsingle structure, and this returns the child elements as an array. In other words, the\nfollowing expressions yield the same data structure:\n\n$header = ($som->headers)[0];\n$header = $som->valueof(SOAP::SOM::header.'/[1]');\n\nbody\n$body = $som->body;\n\nRetrieves the message body as a hash reference. The entity tags act as keys, with their\ndeserialized content providing the values.\n\nfault\nif ($som->fault) { die $som->fault->faultstring }\n\nActs both as a boolean test whether a fault occurred, and as a way to retrieve the Fault\nentity itself from the message body as a hash reference. If the message contains a fault,\nthe next four methods (faultcode, faultstring, faultactor, and faultdetail) may be used to\nretrieve the respective parts of the fault (which are also available on the hash reference\nas keys). If fault in a boolean context is true, the \"result\", \"paramsin\", \"paramsout\", and\n\"method\" methods all return \"undef\".\n\nfaultcode\n$code = $som->faultcode;\n\nReturns the faultcode element of the fault if there is a fault; undef otherwise.\n\nfaultstring\n$string = $som->faultstring;\n\nReturns the faultstring element of the fault if there is a fault; undef otherwise.\n\nfaultactor\n$actor = $som->faultactor;\n\nReturns the faultactor element of the fault, if there is a fault and if the actor was\nspecified within it. The faultactor element is optional in the serialization of a fault, so\nit may not always be present. This element is usually a string.\n\nfaultdetail\n$detail = $som->faultdetail;\n\nReturns the content of the detail element of the fault, if there is a fault and if the\ndetail element was provided. Note that the name of the element isn't the same as the method,\ndue to the possibility for confusion had the method been called simply, detail. As with the\nfaultactor element, this isn't always a required component of a fault, so it isn't\nguaranteed to be present. The specification for the detail portion of a fault calls for it\nto contain a series of element tags, so the application may expect a hash reference as a\nreturn value when detail information is available (and undef otherwise).\n\nmethod\n$method = $som->method\n\nRetrieves the \"method\" element of the message, as a hash reference. This includes all input\nparameters when called on a request message or all result/output parameters when called on a\nresponse message. If there is a fault present in the message, it returns undef.\n\nresult\n$value = $som->result;\n\nReturns the value that is the result of a SOAP response. The value will be already\ndeserialized into a native Perl datatype.\n\nparamsin\n@list = $som->paramsin;\n\nRetrieves the parameters being passed in on a SOAP request. If called in a scalar context,\nthe first parameter is returned. When called in a list context, the full list of all\nparameters is returned. Each parameter is a hash reference, following the established\nstructure for such return values.\n\nparamsout\n@list = $som->paramsout;\n\nReturns the output parameters from a SOAP response. These are the named parameters that are\nreturned in addition to the explicit response entity itself. It shares the same scalar/list\ncontext behavior as the paramsin method.\n\nparamsall\n@list = $som->paramsall;\n\nReturns all parameters from a SOAP response, including the result entity itself, as one\narray.\n"
                },
                {
                    "name": "parts",
                    "content": "Return an array of \"MIME::Entity\"'s if the current payload contains attachments, or returns\nundefined if payload is not MIME multipart.\n"
                },
                {
                    "name": "is_multipart",
                    "content": "Returns true if payload is MIME multipart, false otherwise.\n"
                }
            ]
        },
        "EXAMPLES": {
            "content": "ACCESSING ELEMENT VALUES\nSuppose for the following SOAP Envelope:\n\n<Envelope>\n<Body>\n<fooResponse>\n<bar>abcd</bar>\n</fooResponse>\n</Body>\n</Envelope>\n\nAnd suppose you wanted to access the value of the bar element, then use the following code:\n\nmy $soap = SOAP::Lite\n->uri($SOMENS)\n->proxy($SOMEHOST);\nmy $som = $soap->foo();\nprint $som->valueof('//fooResponse/bar');\n\nACCESSING ATTRIBUTE VALUES\nSuppose the following SOAP Envelope:\n\n<Envelope>\n<Body>\n<c2fResponse>\n<convertedTemp test=\"foo\">98.6</convertedTemp>\n</c2fResponse>\n</Body>\n</Envelope>\n\nThen to print the attribute 'test' use the following code:\n\nprint \"The attribute is: \" .\n$som->dataof('//c2fResponse/convertedTemp')->attr->{'test'};\n\nITERATING OVER AN ARRAY\nSuppose for the following SOAP Envelope:\n\n<Envelope>\n<Body>\n<catalog>\n<product>\n<title>Programming Web Service with Perl</title>\n<price>$29.95</price>\n</product>\n<product>\n<title>Perl Cookbook</title>\n<price>$49.95</price>\n</product>\n</catalog>\n</Body>\n</Envelope>\n\nIf the SOAP Envelope returned contained an array, use the following code to iterate over the\narray:\n\nfor my $t ($som->valueof('//catalog/product')) {\nprint $t->{title} . \" - \" . $t->{price} . \"\\n\";\n}\n\nDETECTING A SOAP FAULT\nA SOAP::SOM object is returned by a SOAP::Lite client regardless of whether the call succeeded\nor not. Therefore, a SOAP Client is responsible for determining if the returned value is a fault\nor not. To do so, use the fault() method which returns 1 if the SOAP::SOM object is a fault and\n0 otherwise.\n\nmy $som = $client->someMethod(@parameters);\n\nif ($som->fault) {\nprint $som->faultdetail;\n} else {\n# do something\n}\n\nPARSING ARRAYS OF ARRAYS\nThe most efficient way To parse and to extract data out of an array containing another array\nencoded in a SOAP::SOM object is the following:\n\n$xml = <<ENDXML;\n<foo>\n<person>\n<foo>123</foo>\n<foo>456</foo>\n</person>\n<person>\n<foo>789</foo>\n<foo>012</foo>\n</person>\n</foo>\nENDXML\n\nmy $som = SOAP::Deserializer->deserialize($xml);\nmy $i = 0;\nforeach my $a ($som->dataof(\"//person/*\")) {\n$i++;\nmy $j = 0;\nforeach my $b ($som->dataof(\"//person/[$i]/*\")) {\n$j++;\n# do something\n}\n}\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "SOAP::Data, SOAP::Serializer\n",
            "subsections": []
        },
        "ACKNOWLEDGEMENTS": {
            "content": "Special thanks to O'Reilly publishing which has graciously allowed SOAP::Lite to republish and\nredistribute large excerpts from *Programming Web Services with Perl*, mainly the SOAP::Lite\nreference found in Appendix B.\n",
            "subsections": []
        },
        "COPYRIGHT": {
            "content": "Copyright (C) 2000-2004 Paul Kulchenko. All rights reserved.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
            "subsections": []
        },
        "AUTHORS": {
            "content": "Paul Kulchenko (paulclinger@yahoo.com)\n\nRandy J. Ray (rjray@blackperl.com)\n\nByrne Reese (byrne@majordojo.com)\n",
            "subsections": []
        }
    },
    "summary": "SOAP::SOM - provides access to the values contained in SOAP Response",
    "flags": [],
    "examples": [
        "ACCESSING ELEMENT VALUES",
        "Suppose for the following SOAP Envelope:",
        "<Envelope>",
        "<Body>",
        "<fooResponse>",
        "<bar>abcd</bar>",
        "</fooResponse>",
        "</Body>",
        "</Envelope>",
        "And suppose you wanted to access the value of the bar element, then use the following code:",
        "my $soap = SOAP::Lite",
        "->uri($SOMENS)",
        "->proxy($SOMEHOST);",
        "my $som = $soap->foo();",
        "print $som->valueof('//fooResponse/bar');",
        "ACCESSING ATTRIBUTE VALUES",
        "Suppose the following SOAP Envelope:",
        "<Envelope>",
        "<Body>",
        "<c2fResponse>",
        "<convertedTemp test=\"foo\">98.6</convertedTemp>",
        "</c2fResponse>",
        "</Body>",
        "</Envelope>",
        "Then to print the attribute 'test' use the following code:",
        "print \"The attribute is: \" .",
        "$som->dataof('//c2fResponse/convertedTemp')->attr->{'test'};",
        "ITERATING OVER AN ARRAY",
        "Suppose for the following SOAP Envelope:",
        "<Envelope>",
        "<Body>",
        "<catalog>",
        "<product>",
        "<title>Programming Web Service with Perl</title>",
        "<price>$29.95</price>",
        "</product>",
        "<product>",
        "<title>Perl Cookbook</title>",
        "<price>$49.95</price>",
        "</product>",
        "</catalog>",
        "</Body>",
        "</Envelope>",
        "If the SOAP Envelope returned contained an array, use the following code to iterate over the",
        "array:",
        "for my $t ($som->valueof('//catalog/product')) {",
        "print $t->{title} . \" - \" . $t->{price} . \"\\n\";",
        "DETECTING A SOAP FAULT",
        "A SOAP::SOM object is returned by a SOAP::Lite client regardless of whether the call succeeded",
        "or not. Therefore, a SOAP Client is responsible for determining if the returned value is a fault",
        "or not. To do so, use the fault() method which returns 1 if the SOAP::SOM object is a fault and",
        "0 otherwise.",
        "my $som = $client->someMethod(@parameters);",
        "if ($som->fault) {",
        "print $som->faultdetail;",
        "} else {",
        "# do something",
        "PARSING ARRAYS OF ARRAYS",
        "The most efficient way To parse and to extract data out of an array containing another array",
        "encoded in a SOAP::SOM object is the following:",
        "$xml = <<ENDXML;",
        "<foo>",
        "<person>",
        "<foo>123</foo>",
        "<foo>456</foo>",
        "</person>",
        "<person>",
        "<foo>789</foo>",
        "<foo>012</foo>",
        "</person>",
        "</foo>",
        "ENDXML",
        "my $som = SOAP::Deserializer->deserialize($xml);",
        "my $i = 0;",
        "foreach my $a ($som->dataof(\"//person/*\")) {",
        "$i++;",
        "my $j = 0;",
        "foreach my $b ($som->dataof(\"//person/[$i]/*\")) {",
        "$j++;",
        "# do something"
    ],
    "see_also": []
}