perldoc > SOAP::Lite

man perldoc info pydoc3 ri search

📛 NAME

SOAP::Lite - Perl's Web Services Toolkit

🚀 Quick Reference

Use Case	Command	Description
📦 Create a SOAP client	my $soap = SOAP::Lite->new( proxy => $url );	🔧 Instantiate a new client with a proxy endpoint
🌐 Set namespace	$soap->default_ns('urn:HelloWorld');	📛 Set default namespace for request elements
📞 Call a remote method	my $som = $soap->call('sayHello', 'Kutter', 'Martin');	📲 Invoke a method with positional parameters
📄 Use WSDL service	my $soap = SOAP::Lite->service("file:service.wsdl");	📋 Load WSDL and generate stubs
📎 Send attachments	$soap->parts([ $mime_entity ]);	📎 Attach MIME entities to request
🔍 Enable debug output	use SOAP::Lite +trace;	🐛 Turn on tracing for debugging
⚙️ Set custom SOAPAction	$soap->on_action( sub { join '/', @_ } );	🎯 Override default SOAPAction header
📦 Create a server	SOAP::Transport::HTTP::CGI->dispatch_to('MyModule')->handle;	🖥️ Deploy a CGI-based SOAP server

📖 DESCRIPTION

SOAP::Lite is a collection of Perl modules which provides a simple and lightweight interface to the Simple Object Access Protocol (SOAP) both on client and server side.

⚠️ PERL VERSION WARNING

As of version 1.05, no perl versions before 5.8 will be supported. SOAP::Lite 0.71 will be the last version running on perl 5.005. Future versions will require at least perl 5.6.0. If you have not had the time to upgrade your perl, you should consider this now.

📚 OVERVIEW OF CLASSES AND PACKAGES

📁 lib/SOAP/Lite.pm

• SOAP::Lite - Main class provides all logic
• SOAP::Transport - Transport backend
• SOAP::Data - Data objects
• SOAP::Header - Header Data Objects
• SOAP::Serializer - Serializes data structures to SOAP messages
• SOAP::Deserializer - Deserializes SOAP messages into SOAP::SOM objects
• SOAP::SOM - SOAP Message objects
• SOAP::Constants - Provides access to common constants and defaults
• SOAP::Trace - Tracing facilities
• SOAP::Schema - Provides access and stub(s) for schema(s)
• SOAP::Schema::WSDL - WSDL implementation for SOAP::Schema
• SOAP::Server - Handles requests on server side
• SOAP::Server::Object - Handles objects-by-reference
• SOAP::Fault - Provides support for Faults on server side
• SOAP::Utils - A set of private and public utility subroutines

📁 lib/SOAP/Packager.pm

• SOAP::Packager - Abstract class for implementing custom packagers
• SOAP::Packager::MIME - MIME support
• SOAP::Packager::DIME - DIME support

📁 lib/SOAP/Transport/HTTP.pm

• SOAP::Transport::HTTP::Client - Client interface to HTTP transport
• SOAP::Transport::HTTP::Server - Server interface to HTTP transport
• SOAP::Transport::HTTP::CGI - CGI implementation
• SOAP::Transport::HTTP::Daemon - Daemon implementation
• SOAP::Transport::HTTP::Apache - mod_perl implementation

📁 Other Transport Modules

• SOAP::Transport::POP3::Server - POP3 protocol
• SOAP::Transport::MAILTO::Client - SMTP/sendmail
• SOAP::Transport::LOCAL::Client - Local transport
• SOAP::Transport::TCP::Server - TCP server
• SOAP::Transport::TCP::Client - TCP client
• SOAP::Transport::IO::Server - IO transport

🔧 METHODS

All accessor methods return the current value when called with no arguments, while returning the object reference itself when called with a new value (chaining).

new(optional key/value pairs)

$client = SOAP::Lite->new(proxy => $endpoint)

🔨 Constructor. Many accessor methods may be initialized at creation by providing their name as a key, followed by the desired value.

transport(optional transport object)

$transp = $client->transport( );

🚚 Gets or sets the transport object for sending/receiving SOAP messages. See SOAP::Transport.

serializer(optional serializer object)

$serial = $client->serializer( )

📝 Gets or sets the serializer object for creating XML messages. See SOAP::Serializer.

packager(optional packager object)

$packager = $client->packager( )

📦 Provides access to the SOAP::Packager object for managing attachments. Default packager is MIME. See SOAP::Packager.

proxy(endpoint, optional extra arguments)

$client->proxy('http://soap.xml.info/ endPoint');

🌐 Sets the server endpoint. Alias to transport->proxy(...). Extra parameters can be passed:

• compress_threshold - See COMPRESSION in HTTP::Transport.
• All initialization options from the underlying transport layer - e.g., cookie_jar, timeout.

Example with timeout:

my $soap = SOAP::Lite
 ->uri($uri)
 ->proxy($proxyUrl, timeout => 5 );

endpoint(optional new endpoint address)

$client->endpoint('http://soap.xml.info/ newPoint')

🔗 Change the endpoint without reloading transport code. Must have called proxy() first.

service(service URL)

$client->service('http://svc.perl.org/Svc.wsdl');

📄 Loads a WSDL schema and generates method stubs. Currently only WSDL support is in place.

outputxml(boolean)

$client->outputxml('true');

🔙 When set to true, returns raw XML instead of a SOAP::SOM object.

autotype(boolean)

$client->autotype(0);

🔢 Shortcut for serializer->autotype(boolean). Disables automatic type deduction.

readable(boolean)

$client->readable(1);

🔍 Shortcut for serializer->readable(boolean). Adds whitespace for human-readable XML.

headerattr(hash reference of attributes)

$obj->headerattr({ attr1 => 'value' });

🧩 Sets arbitrary attributes on the SOAP header element. Attributes must be namespace-qualified if not native.

bodyattr(hash reference of attributes)

$obj->bodyattr({ attr1 => 'value' });

🧩 Sets arbitrary attributes on the SOAP body element. See headerattr.

default_ns($uri)

📛 Sets the default namespace for the request. Elements are serialized without a prefix:

<soap:Envelope>
  <soap:Body>
    <myMethod xmlns="http://www.someuri.com">
      <foo />
    </myMethod>
  </soap:Body>
</soap:Envelope>

Some .NET web services require this idiom.

ns($uri,$prefix=undef)

🌐 Sets namespace URI and optional prefix. If prefix omitted, one is generated. Elements serialized with prefix:

<soap:Envelope>
  <soap:Body>
    <my:myMethod xmlns:my="http://www.someuri.com">
      <my:foo />
    </my:myMethod>
  </soap:Body>
</soap:Envelope>

use_prefix(boolean) (Deprecated)

Shortcut for serializer->use_prefix(). When false, elements are serialized without prefix (useful for .NET interop).

soapversion(optional value)

$client->soapversion('1.2');

📌 Gets or sets SOAP version (1.1 or 1.2).

envprefix(QName)

$client->envprefix('env');

🏷️ Shortcut for serializer->envprefix(QName). Gets or sets namespace prefix for SOAP envelope (default: SOAP).

encprefix(QName)

$client->encprefix('enc');

🏷️ Shortcut for serializer->encprefix(QName). Gets or sets namespace prefix for encoding (default: SOAP-ENC).

encoding(encoding URN)

$client->encoding($soap_12_encoding_URN);

🔢 Shortcut for serializer->encoding(args). Sets the URN for encoding scheme.

typelookup

$client->typelookup;

🔍 Shortcut for serializer->typelookup. Provides access to the type-lookup table.

uri(service specifier) (Deprecated)

$client->uri($service_uri);

⚠️ Deprecated. Use ns() or default_ns(). Sets the service specifier/namespace for the request.

multirefinplace(boolean)

$client->multirefinplace(1);

🔗 Shortcut for serializer->multirefinplace(boolean). Controls where multi-referenced data is serialized (inline vs. separate).

parts( ARRAY )

📎 Specifies an array of MIME::Entity's to attach to the transmitted SOAP message. Access returned attachments via SOAP::SOM::parts().

self

$ref = SOAP::Lite->self;

🔁 Returns reference to the default global object that processes arguments on the use line.

call(arguments)

$client->call($method => @arguments);

📞 Invokes a remote method with full control over details. Useful for methods with special characters or namespace control.

📡 Event Handlers

on_action(callback)

$client->on_action(sub { qq("$_[0]") });

🎯 Triggered when setting SOAPAction header. Callback receives URI and method. .NET expects uri/method:

$client->on_action( sub { join '/', @_ } );

on_fault(callback)

$client->on_fault(sub { popup_dialog($_[1]) });

⚠️ Triggered when a fault response is received. Callback receives client object and fault object.

on_nonserialized(callback)

$client->on_nonserialized(sub { die "$_[0]?!?" });

⚠️ Triggered when serializer encounters data it cannot serialize. Return value is used as fallback.

on_debug(callback) (Deprecated)

$client->on_debug(sub { print @_ });

🐛 Deprecated. Use global +trace facilities in SOAP::Trace.

✍️ WRITING A SOAP CLIENT

This chapter guides you through writing a SOAP client by example, using a "Hello World" service that accepts name and givenName and returns "Hello $given_name $name".

📨 SOAP Message Styles

• rpc/encoded - Typed, positional parameters. Widely used in scripting languages.
• rpc/literal - As-is, positional parameters. Types defined by interface definition.
• document/encoded - Specified message with typed elements. Rarely used.
• document/literal - Specified message with as-is elements. Predominant since 2008.

💻 Example Implementations

RPC/ENCODED

Client using positional parameters:

use SOAP::Lite;
my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
$soap->default_ns('urn:HelloWorld');
my $som = $soap->call('sayHello', 'Kutter', 'Martin');
die $som->faultstring if ($som->fault);
print $som->result, "\n";

With WSDL and named parameters:

use SOAP::Lite;
my $soap = SOAP::Lite->service("file:say_hello_rpcenc.wsdl");
eval { my $result = $soap->sayHello('Kutter', 'Martin'); };
if ($@) { die $@; }
print $som->result();

One-liner:

perl -MSOAP::Lite -e 'print SOAP::Lite->service("file:say_hello_rpcenc.wsdl")->sayHello('Kutter', 'Martin'), "\n";'

Without service description, using SOAP::Data:

use SOAP::Lite;
my $soap = SOAP::Lite->new( proxy => 'http://localhost:81/soap-wsdl-test/helloworld.pl');
$soap->default_ns('urn:HelloWorld');
my $som = $soap->call('sayHello',
   SOAP::Data->name('name')->value('Kutter'),
   SOAP::Data->name('givenName')->value('Martin')
);
die $som->faultstring if ($som->fault);
print $som->result, "\n";

RPC/LITERAL

Client using SOAP::Data with a wrapper:

use SOAP::Lite +trace;
my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
$soap->on_action( sub { "urn:HelloWorld#sayHello" });
$soap->autotype(0)->readable(1);
$soap->default_ns('urn:HelloWorld');
my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
   \SOAP::Data->value([
       SOAP::Data->name('name')->value( 'Kutter' ),
       SOAP::Data->name('givenName')->value('Martin'),
   ]))
);
die $som->fault->{ faultstring } if ($som->fault);
print $som->result, "\n";

DOCUMENT/LITERAL

use SOAP::Lite;
my $soap = SOAP::Lite->new( proxy => 'http://localhost:80/helloworld.pl');
$soap->on_action( sub { "urn:HelloWorld#sayHello" });
$soap->autotype(0);
$soap->default_ns('urn:HelloWorld');
my $som = $soap->call("sayHello",
   SOAP::Data->name('name')->value( 'Kutter' ),
   SOAP::Data->name('givenName')->value('Martin'),
);
die $som->fault->{ faultstring } if ($som->fault);
print $som->result, "\n";

🔍 Differences between implementations

From SOAP::Lite's point of view, the only difference between rpc/literal and document/literal is that parameters are always named. In rpc/encoded, the example already used named parameters via WSDL messages.

Note the idiom for passing a list of named parameters in rpc/literal:

my $som = $soap->call('sayHello', SOAP::Data->name('parameters')->value(
   \SOAP::Data->value([
       SOAP::Data->name('name')->value( 'Kutter' ),
       SOAP::Data->name('givenName')->value('Martin'),
   ]))
);

While SOAP::Data provides full control, passing hash-like structures requires additional coding.

🖥️ WRITING A SOAP SERVER

See SOAP::Server and SOAP::Transport for details.

🌟 FEATURES

📎 ATTACHMENTS

Supports SOAP with Attachments specification (MIME only, DIME not fully functional).

Client sending an attachment

use SOAP::Lite;
use MIME::Entity;
my $ent = build MIME::Entity
  Type        => "image/gif",
  Encoding    => "base64",
  Path        => "somefile.gif",
  Filename    => "saveme.gif",
  Disposition => "attachment";
my $som = SOAP::Lite
  ->uri($SOME_NAMESPACE)
  ->parts([ $ent ])
  ->proxy($SOME_HOST)
  ->some_method(SOAP::Data->name("foo" => "bar"));

Client retrieving an attachment

use SOAP::Lite;
use MIME::Entity;
my $soap = SOAP::Lite
  ->uri($NS)
  ->proxy($HOST);
my $som = $soap->foo();
foreach my $part (${$som->parts}) {
  print $part->stringify;
}

Server receiving an attachment

package Attachment;
use SOAP::Lite;
use MIME::Entity;
use strict;
use vars qw(@ISA);
@ISA = qw(SOAP::Server::Parameters);
sub someMethod {
  my $self = shift;
  my $envelope = pop;
  foreach my $part (@{$envelope->parts}) {
    print "AttachmentService: attachment found! (".ref($part).")\n";
  }
  # do something
}

Server responding with an attachment

package Attachment;
use SOAP::Lite;
use MIME::Entity;
use strict;
use vars qw(@ISA);
@ISA = qw(SOAP::Server::Parameters);
sub someMethod {
  my $self = shift;
  my $envelope = pop;
  my $ent = build MIME::Entity
  'Id'          => "<1234>",
  'Type'        => "text/xml",
  'Path'        => "some.xml",
  'Filename'    => "some.xml",
  'Disposition' => "attachment";
  return SOAP::Data->name("foo" => "blah blah blah"),$ent;
}

⚙️ DEFAULT SETTINGS

You can specify default settings for all SOAP::Lite objects using use SOAP::Lite ...:

use SOAP::Lite
  proxy => 'http://localhost/cgi-bin/soap.cgi',
  uri => 'http://my.own.com/My/Examples';

my $soap1 = new SOAP::Lite; # inherits proxy/uri
my $soap2 = SOAP::Lite->new; # same
my $soap3 = SOAP::Lite->proxy('http://localhost/'); # overrides

You can also set event handlers globally:

use SOAP::Lite
  on_action => sub {sprintf '%s#%s', @_};

To change global settings at runtime: SOAP::Lite->self->proxy(...).

⚠️ Note: use is executed at compile time. Use eval for runtime.

📏 SETTING MAXIMUM MESSAGE SIZE

use SOAP::Transport::HTTP;
use MIME::Entity;
$SOAP::Constants::MAX_CONTENT_SIZE = 10000;
SOAP::Transport::HTTP::CGI
  ->dispatch_to('TemperatureService')
  ->handle;

🔄 IN/OUT, OUT PARAMETERS AND AUTOBINDING

Parameters are accessible via result() and paramsout(). Autobinding maps output parameters with same signature back to input.

Example: If server returns return (1,2,3), result is 1, out parameters are 2 and 3. If server returns return [1,2,3], result is an array reference, paramsout is undef.

Autobinding example:

# Server code
sub mymethod {
  shift; my $param1 = shift;
  my $param2 = SOAP::Data->name('myparam' => shift() * 2);
  return $param1, $param2;
}
# Client code
$a = 10;
$b = SOAP::Data->name('myparam' => 12);
$result = $soap->mymethod($a, $b);
# After: $result == 10, $b->value == 24

See the PingPong example for object autobinding.

📦 STATIC AND DYNAMIC SERVICE DEPLOYMENT

Static deployment: Preload modules and use dispatch_to('MODULE').

use SOAP::Transport::HTTP;
use My::Examples;
SOAP::Transport::HTTP::CGI
  -> dispatch_to('My::Examples')
  -> handle;

Dynamic deployment: Modules loaded on demand from specified paths.

use SOAP::Transport::HTTP;
SOAP::Transport::HTTP::CGI
  -> dispatch_to('/Your/Path/To/Deployed/Modules', 'My::Examples')
  -> handle;

dispatch_with (experimental): Bind URL or SOAPAction to a module/object.

dispatch_with({
  URI => MODULE,
  SOAPAction => MODULE,
  URI => object,
})

URI is checked before SOAPAction. dispatch_with has higher precedence than dispatch_to.

🗜️ COMPRESSION

Transparent compression over HTTP. Set compress_threshold in kilobytes.

Client:

print SOAP::Lite
  ->uri('http://localhost/My/Parameters')
  ->proxy('http://localhost/', options => {compress_threshold => 10000})
  ->echo(1 x 10000)
  ->result;

Server:

my $server = SOAP::Transport::HTTP::CGI
  ->dispatch_to('My::Parameters')
  ->options({compress_threshold => 10000})
  ->handle;

🔒 SECURITY

With dynamic deployment, @INC is disabled for security. Options to access other modules:

1. Switch to static linking: use MODULE; $server->dispatch_to('MODULE');
2. Change use to require (path available during execution).
3. Wrap use in eval.
4. Set include path in BEGIN { @INC = qw(my_directory); use MODULE }.

🤝 INTEROPERABILITY

Microsoft .NET client with SOAP::Lite Server

Use fully qualified names for return values:

return SOAP::Data->name('myname')
                 ->type('string')
                 ->uri($MY_NAMESPACE)
                 ->value($output);

SOAP::Lite client with .NET Server

• Declare proper soapAction: on_action( sub { 'http://www.myuri.com/WebService.aspx#someMethod'; } )
• Disable charset in Content-type: $SOAP::Constants::DO_NOT_USE_CHARSET = 1;
• Use fully qualified parameter names: SOAP::Data->name(Query => 'biztalk')->uri('http://tempuri.org/')
• Place method in default namespace: SOAP::Data->name('add')->attr({xmlns => 'http://tempuri.org/'})
• Disable namespace prefixes: $soap->use_prefix(0)
• Modify .NET server (if possible): Add [SoapRpcService] attribute.

Special thanks to Petr Janata, Stefan Pharies, Brian Jepson, and others for .NET interop details.

🔧 TROUBLESHOOTING

• Serializing "18373" as integer instead of string: Force type with SOAP::Data->type('string') or modify typelookup.
• +autodispatch doesn't work in Perl 5.8: Use dispatch_from instead.
• COM Interface problems: Register Lite.dll with regsvr32; ensure correct Perl path.
• Dynamic libraries not found: Add PassEnv LD_LIBRARY_PATH to httpd.conf.
• Apache crashes with segfaults: Configure Apache with --disable-rule=EXPAT or use system malloc.
• CGI scripts don't work under IIS: Use .pl extension.
• Java SAX parser unable to parse: Known bug in ParserAdapter; attribute order not significant per XML spec.

⚡ PERFORMANCE

Processing XML-encoded fragments can be slow due to expat's character callback. For large XML strings, consider encoding as base64:

SOAP::Data->type(base64 => $string)

To globally change string encoding to base64:

*SOAP::Serializer::as_string = \&SOAP::XMLSchema2001::Serializer::as_base64Binary;

🐛 BUGS AND LIMITATIONS

• No support for multidimensional, partially transmitted and sparse arrays (arrays of arrays supported).
• Limited WSDL schema support.
• XML::Parser::Lite relies on Unicode support and doesn't do entity decoding.
• Limited support for mustUnderstand and Actor attributes.

💻 PLATFORM SPECIFICS

MacOS

Information and compiled XML::Parser for MacPerl available at:

• http://bumppo.net/...
• http://www.perl.com/...

🔗 RELATED MODULES

Transport Modules

• SOAP::Transport::HTTP::Nginx - nginx transport module

📦 AVAILABILITY

Download from CPAN: http://search.cpan.org/search?dist=SOAP-Lite

🙏 ACKNOWLEDGEMENTS

Special thanks to Randy J. Ray, O'Reilly publishing, and all developers who contributed patches, ideas, and help.

🛠️ HACKING

Latest development on GitHub: git@github.com:redhotpenguin/perl-soaplite.git. See HACKING file. Actively recruiting maintainers.

🐞 REPORTING BUGS

Please use rt.cpan.org or GitHub. Pull requests preferred.

©️ COPYRIGHT

Copyright (C) 2000-2007 Paul Kulchenko. All rights reserved.
Copyright (C) 2007-2008 Martin Kutter
Copyright (C) 2013 Fred Moyer

📜 LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Documentation available under Creative Commons Attribution-NoDerivs 2.0 license: http://creativecommons.org/licenses/by-nd/2.0/

👤 AUTHORS

• Paul Kulchenko (paulclinger@yahoo.com)
• Randy J. Ray (rjray@blackperl.com)
• Byrne Reese (byrne@majordojo.com)
• Martin Kutter (martin.kutter@fen-net.de)
• Fred Moyer (fred@redhotpenguin.com)

📛 NAME 🚀 Quick Reference 📖 DESCRIPTION ⚠️ PERL VERSION WARNING 📚 OVERVIEW OF CLASSES AND PACKAGES 🔧 METHODS ✍️ WRITING A SOAP CLIENT 🖥️ WRITING A SOAP SERVER 🌟 FEATURES 🔒 SECURITY 🤝 INTEROPERABILITY 🔧 TROUBLESHOOTING ⚡ PERFORMANCE 🐛 BUGS AND LIMITATIONS 💻 PLATFORM SPECIFICS 🔗 RELATED MODULES 📦 AVAILABILITY 🙏 ACKNOWLEDGEMENTS 🛠️ HACKING 🐞 REPORTING BUGS ©️ COPYRIGHT 📜 LICENSE 👤 AUTHORS