Skip to content

Commit

Permalink
Merge branch 'fix/zend.soap' of https://github.com/robertbasic/zf2-do…
Browse files Browse the repository at this point in the history 
…cumentation into hotfix/339
  • Loading branch information
@weierophinney
weierophinney committed Oct 2, 2012
2 parents 51db57a + d4172fc commit 771b057
Show file tree
Hide file tree
Showing 5 changed files with 164 additions and 209 deletions.
14 changes: 14 additions & 0 deletions docs/languages/en/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,10 @@
modules/zend.server.reflection
modules/zend.service-manager.intro
modules/zend.service-manager.quick-start
modules/zend.soap.server
modules/zend.soap.client
modules/zend.soap.wsdl
modules/zend.soap.auto-discovery
modules/zend.stdlib.hydrator
modules/zend.tag.introduction
modules/zend.tag.cloud
Expand Down Expand Up @@ -516,6 +520,16 @@ Zend\\ServiceManager
* :doc:`modules/zend.service-manager.intro`
* :doc:`modules/zend.service-manager.quick-start`

.. _zend.soap:

Zend\\Soap
^^^^^^^^^^

* :doc:`modules/zend.soap.server`
* :doc:`modules/zend.soap.client`
* :doc:`modules/zend.soap.wsdl`
* :doc:`modules/zend.soap.auto-discovery`

.. _zend.stdlib:

Zend\\Stdlib
Expand Down
81 changes: 32 additions & 49 deletions docs/languages/en/modules/zend.soap.auto-discovery.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,11 @@ communications more simple.

There are three configurations for *SOAP* applications where Zend Framework may be utilized:

- SOAP server *PHP* application <---> *SOAP* client *PHP* application

- SOAP server non-PHP application <---> *SOAP* client *PHP* application

. SOAP server *PHP* application <---> *SOAP* client *PHP* application

. SOAP server non-PHP application <---> *SOAP* client *PHP* application

. SOAP server *PHP* application <---> *SOAP* client non-PHP application

- SOAP server *PHP* application <---> *SOAP* client non-PHP application


We always have to know, which functionality is provided by *SOAP* server to operate with it. `WSDL`_ is used to
Expand All @@ -39,12 +36,9 @@ generates correct WSDL using this information.

There are two ways for using Zend Framework for *SOAP* server application:

- Use separated class.


- Use separated class.

- Use set of functions

- Use set of functions.


Both methods are supported by Zend Framework Autodiscovery functionality.
Expand Down Expand Up @@ -112,34 +106,27 @@ If a class is used to provide SOAP server functionality, then the same class sho
The following rules are used while WSDL generation:


- Generated WSDL describes an RPC/Encoded style Web Service. If you want to use a document/literal server use the
``setBindingStyle()`` and ``setOperationBodyStyle()`` methods.

- Generated WSDL describes an RPC/Encoded style Web Service. If you want to use a document/literal server use
the ``setBindingStyle()`` and ``setOperationBodyStyle()`` methods.

- Class name is used as a name of the Web Service being described unless ``setServiceName()`` is used explicitly
to set the name. When only functions are used for generation the service name has to be set explicitly or an
exception is thrown during generation of the WSDL document.
- Class name is used as a name of the Web Service being described unless ``setServiceName()`` is used explicitly to
set the name. When only functions are used for generation the service name has to be set explicitly or an exception
is thrown during generation of the WSDL document.

- You can set the endpoint of the actual SOAP Server via the ``setUri()`` method. This is a required option.
- You can set the endpoint of the actual SOAP Server via the ``setUri()`` method. This is a required option.

It's also used as a target namespace for all service related names (including described complex types).
It's also used as a target namespace for all service related names (including described complex types).

- Class methods are joined into one `Port Type`_.
- Class methods are joined into one `Port Type`_. *$serviceName . 'Port'* is used as Port Type name.

*$serviceName . 'Port'* is used as Port Type name.

- Each class method/function is registered as a corresponding port operation.

- Only the "longest" available method prototype is used for generation of the WSDL.

- WSDL autodiscover utilizes the *PHP* docblocks provided by the developer to determine the parameter and return
types. In fact, for scalar types, this is the only way to determine the parameter types, and for return types,
this is the only way to determine them.

That means, providing correct and fully detailed docblocks is not only best practice, but is required for
discovered class.
- Each class method/function is registered as a corresponding port operation.

- Only the "longest" available method prototype is used for generation of the WSDL.

- WSDL autodiscover utilizes the *PHP* docblocks provided by the developer to determine the parameter and return
types. In fact, for scalar types, this is the only way to determine the parameter types, and for return types,
this is the only way to determine them. That means, providing correct and fully detailed docblocks is not only
best practice, but is required for discovered class.

.. _zend.soap.autodiscovery.functions:

Expand Down Expand Up @@ -168,28 +155,25 @@ Autodiscovering Datatypes

Input/output datatypes are converted into network service types using the following mapping:

- PHP strings <-> *xsd:string*.

- PHP integers <-> *xsd:int*.

- PHP strings <-> *xsd:string*.
- PHP floats and doubles <-> *xsd:float*.

- PHP integers <-> *xsd:int*.
- PHP booleans <-> *xsd:boolean*.

- PHP floats and doubles <-> *xsd:float*.
- PHP arrays <-> *soap-enc:Array*.

- PHP booleans <-> *xsd:boolean*.
- PHP object <-> *xsd:struct*.

- PHP arrays <-> *soap-enc:Array*.
- *PHP* class <-> based on complex type strategy (See: :ref:`this section <zend.soap.wsdl.types.add_complex>`) [#]_.

- PHP object <-> *xsd:struct*.
- type[] or object[] (ie. int[]) <-> based on complex type strategy

- *PHP* class <-> based on complex type strategy (See: :ref:`this section <zend.soap.wsdl.types.add_complex>`)
[#]_.
- PHP void <-> empty type.

- type[] or object[] (ie. int[]) <-> based on complex type strategy

- PHP void <-> empty type.

- If type is not matched to any of these types by some reason, then *xsd:anyType* is used.
- If type is not matched to any of these types by some reason, then *xsd:anyType* is used.

Where *xsd:* is "http://www.w3.org/2001/XMLSchema" namespace, *soap-enc:* is a
"http://schemas.xmlsoap.org/soap/encoding/" namespace, *tns:* is a "target namespace" for a service.
Expand Down Expand Up @@ -225,7 +209,6 @@ Therefore you can set the styles before you call any *setClass* or *addFunction*
$wsdl = $autodiscover->generate();
.. _`WSDL`: http://www.w3.org/TR/wsdl
.. _`http://www.w3.org/TR/wsdl`: http://www.w3.org/TR/wsdl
.. _`XSD types`: http://www.w3.org/TR/xmlschema-2/
Expand All @@ -234,6 +217,6 @@ Therefore you can set the styles before you call any *setClass* or *addFunction*
.. [#] ``Zend\Soap\AutoDiscover`` will be created with the
``Zend\Soap\Wsdl\ComplexTypeStrategy\DefaultComplexType`` class as detection algorithm for complex
types. The first parameter of the AutoDiscover constructor takes any complex type strategy implementing
``Zend\Soap\Wsdl\ComplexTypeStrategy\Interface`` or a string with the name of the class. See the
:ref:`Zend\\Soap\\Wsdl manual on adding complex <zend.soap.wsdl.types.add_complex>` types for more
information.
``Zend\Soap\Wsdl\ComplexTypeStrategy\ComplexTypeStrategyInterface`` or a string with the name of the class.
See the :ref:`Zend\\Soap\\Wsdl manual on adding complex <zend.soap.wsdl.types.add_complex>` types for more
information.
95 changes: 44 additions & 51 deletions docs/languages/en/modules/zend.soap.client.rst
View file
Original file line number Diff line number Diff line change
@@ -1,30 +1,28 @@
.. _zend.soap.client:

Zend_Soap_Client
================
Zend\\Soap\\Client
==================

The ``Zend_Soap_Client`` class simplifies *SOAP* client development for *PHP* programmers.
The ``Zend\Soap\Client`` class simplifies *SOAP* client development for *PHP* programmers.

It may be used in WSDL or non-WSDL mode.

Under the WSDL mode, the ``Zend_Soap_Client`` component uses a WSDL document to define transport layer options.
Under the WSDL mode, the ``Zend\Soap\Client`` component uses a WSDL document to define transport layer options.

The WSDL description is usually provided by the web service the client will access. If the WSDL description is not
made available, you may want to use ``Zend_Soap_Client`` in non-WSDL mode. Under this mode, all *SOAP* protocol
options have to be set explicitly on the ``Zend_Soap_Client`` class.
made available, you may want to use ``Zend\Soap\Client`` in non-WSDL mode. Under this mode, all *SOAP* protocol
options have to be set explicitly on the ``Zend\Soap\Client`` class.

.. _zend.soap.client.constructor:

Zend_Soap_Client Constructor
----------------------------
Zend\\Soap\\Client Constructor
------------------------------

The ``Zend_Soap_Client`` constructor takes two parameters:
The ``Zend\Soap\Client`` constructor takes two parameters:

- ``$wsdl``- the *URI* of a WSDL file.


- ``$wsdl``- the *URI* of a WSDL file.

- ``$options``- options to create *SOAP* client object.
- ``$options``- options to create *SOAP* client object.

Both of these parameters may be set later using ``setWsdl($wsdl)`` and ``setOptions($options)`` methods
respectively.
Expand All @@ -33,68 +31,63 @@ respectively.

**Important!**

If you use ``Zend_Soap_Client`` component in non-WSDL mode, you **must** set the 'location' and 'uri' options.
If you use ``Zend\Soap\Client`` component in non-WSDL mode, you **must** set the 'location' and 'uri' options.

The following options are recognized:

- 'soap_version' ('soapVersion') - soap version to use (SOAP_1_1 or *SOAP*\ _1_2).

- 'classmap' ('classMap') - can be used to map some WSDL types to *PHP* classes. The option must be an array with
WSDL types as keys and names of *PHP* classes as values.

- 'soap_version' ('soapVersion') - soap version to use (SOAP_1_1 or *SOAP*\ _1_2).

- 'classmap' ('classMap') - can be used to map some WSDL types to *PHP* classes.

The option must be an array with WSDL types as keys and names of *PHP* classes as values.
- 'encoding' - internal character encoding (UTF-8 is always used as an external encoding).

- 'encoding' - internal character encoding (UTF-8 is always used as an external encoding).
- 'wsdl' which is equivalent to ``setWsdl($wsdlValue)`` call. Changing this option may switch ``Zend\Soap\Client``
object to or from WSDL mode.

- 'wsdl' which is equivalent to ``setWsdl($wsdlValue)`` call.
- 'uri' - target namespace for the *SOAP* service (required for non-WSDL-mode, doesn't work for WSDL mode).

Changing this option may switch ``Zend_Soap_Client`` object to or from WSDL mode.
- 'location' - the *URL* to request (required for non-WSDL-mode, doesn't work for WSDL mode).

- 'uri' - target namespace for the *SOAP* service (required for non-WSDL-mode, doesn't work for WSDL mode).
- 'style' - request style (doesn't work for WSDL mode): ``SOAP_RPC`` or ``SOAP_DOCUMENT``.

- 'location' - the *URL* to request (required for non-WSDL-mode, doesn't work for WSDL mode).
- 'use' - method to encode messages (doesn't work for WSDL mode): ``SOAP_ENCODED`` or ``SOAP_LITERAL``.

- 'style' - request style (doesn't work for WSDL mode): ``SOAP_RPC`` or ``SOAP_DOCUMENT``.
- 'login' and 'password' - login and password for an *HTTP* authentication.

- 'use' - method to encode messages (doesn't work for WSDL mode): ``SOAP_ENCODED`` or ``SOAP_LITERAL``.
- 'proxy_host', 'proxy_port', 'proxy_login', and 'proxy_password' - an *HTTP* connection through a proxy server.

- 'login' and 'password' - login and password for an *HTTP* authentication.
- 'local_cert' and 'passphrase' -*HTTPS* client certificate authentication options.

- 'proxy_host', 'proxy_port', 'proxy_login', and 'proxy_password' - an *HTTP* connection through a proxy server.
- 'compression' - compression options; it's a combination of ``SOAP_COMPRESSION_ACCEPT``, ``SOAP_COMPRESSION_GZIP``
and ``SOAP_COMPRESSION_DEFLATE`` options which may be used like this:

- 'local_cert' and 'passphrase' -*HTTPS* client certificate authentication options.

- 'compression' - compression options; it's a combination of ``SOAP_COMPRESSION_ACCEPT``,
``SOAP_COMPRESSION_GZIP`` and ``SOAP_COMPRESSION_DEFLATE`` options which may be used like this:

.. code-block:: php
:linenos:
// Accept response compression
$client = new Zend_Soap_Client("some.wsdl",
array('compression' => SOAP_COMPRESSION_ACCEPT));
...
.. code-block:: php
:linenos:
// Compress requests using gzip with compression level 5
$client = new Zend_Soap_Client("some.wsdl",
array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5));
...
// Accept response compression
$client = new Zend\Soap\Client("some.wsdl",
array('compression' => SOAP_COMPRESSION_ACCEPT));
...
// Compress requests using deflate compression
$client = new Zend_Soap_Client("some.wsdl",
array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_DEFLATE));
// Compress requests using gzip with compression level 5
$client = new Zend\Soap\Client("some.wsdl",
array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP | 5));
...
// Compress requests using deflate compression
$client = new Zend\Soap\Client("some.wsdl",
array('compression' => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_DEFLATE));
.. _zend.soap.client.calls:

Performing SOAP Requests
------------------------

After we've created a ``Zend_Soap_Client`` object we are ready to perform *SOAP* requests.
After we've created a ``Zend\Soap\Client`` object we are ready to perform *SOAP* requests.

Each web service method is mapped to the virtual ``Zend_Soap_Client`` object method which takes parameters with
Each web service method is mapped to the virtual ``Zend\Soap\Client`` object method which takes parameters with
common *PHP* types.

Use it like in the following example:
Expand Down Expand Up @@ -130,7 +123,7 @@ Use it like in the following example:
// ...
// }
// ...
// $server = new Zend_Soap_Server(null, $options);
// $server = new Zend\Soap\Server(null, $options);
// $server->setClass('MyClass');
// ...
// $server->handle();
Expand All @@ -139,7 +132,7 @@ Use it like in the following example:
// End of server code
//****************************************************************
$client = new Zend_Soap_Client("MyService.wsdl");
$client = new Zend\Soap\Client("MyService.wsdl");
...
// $result1 is a string
Expand Down
Loading

0 comments on commit 771b057

Please sign in to comment.