Пишем SOAP клиент-серверное приложение на PHP. Отправляем сложные объекты

Лирическая часть.

Представьте что у вас реализована или реализуется некая система, которая должна быть доступна извне. Т.е. есть некий сервер, с которым вам надо общаться. Например веб-сервер.

Этот сервер может выполнять множество действий, работать с базой, выполнять какие-то сторонние запросы к другим серверам, заниматься каким-то вычислениями и т.д. жить и возможно развиваться по ему известному сценарию (т.е. по сценарию разработчиков). С таким сервером общаться человеку неинтересно, потому что он может не уметь/не хотеть отдавать красивые странички с картинками и прочим юзер-френдли контентом. Он написан и работает чтобы работать и выдавать на запросы к нему данные, не заботясь, чтоб они были человекочитаемые, клиент сам с ними разберется.

Другие системы, обращаясь к этому серверу уже могут распоряжаться полученными от этого сервера данными по своему усмотрению - обрабатывать, накапливать, выдавать своим клиентам и т.д.

Ну вот, один из вариантов общения с такими серверами - это SOAP. SOAP протокол обмена xml-сообщениями.

Практическая часть.

Веб-сервис (так называется то, что предоставляет сервер и то, что используют клиенты) дает возможность общения с сервером четко структурированными сообщениями. Дело в том, что веб-сервис не принимает абы какие данные. На любое сообщение, которое не соответствует правилам, веб-сервис ответит ошибкой. Ошибка будет, кстати, тоже в виде xml с четкой структурой (чего нельзя сказать правда о тексте сообщения).

WSDL (Web Services Description Language). Правила, по которым составляются сообщения для веб-сервиса описываются так же с помощью xml и также имеют четкую структуру. Т.е. если веб-сервис предоставляет возможность вызова какого-то метода, он должен дать возможность клиентам узнать какие параметры для данного метода используются. Если веб-сервис ждет строку для метода Method1 в качестве параметра и строка должна иметь имя Param1, то в описании веб-сервиса эти правила будут указаны.

В качестве параметров могут передаваться не только простые типы, но и объекты, коллекции объектов. Описание объекта сводится к описанию каждой составляющей объекта. Если объект состоит из нескольких полей, значит описывается каждое поле какой у него тип, название (какие возможные значения). Поля также могут быть сложного типа и так далее пока описание типов не закончится на простых - строка, булево, число, дата... Впрочем простыми могут оказаться какие-то специфические типы, важно чтоб клиенты могли понять какие значения могут в них содержаться.

Для клиентов достаточно знать url веб-сервиса, wsdl всегда будет рядом, по которому можно получить представление о методах и их параметрах, которые предоставляет этот веб-сервис.

Какие плюсы у всех этих наворотов:

  • В большинстве систем описание методов и типов происходит в автоматическом режиме. Т.е. программисту на сервере достаточно сказать, что данный метод можно вызывать через веб-сервис, и wsdl-описание будет сгенерировано автоматом.

    • Описание, имеющее четкую структуру, читается любым soap-клиентом. Т.е. какой бы ни был веб-сервис, клиент поймет какие данные веб-сервис принимает. По этому описанию клиент может построить свою внутреннюю структуру классов объектов, т.н. binding"и. В итоге программисту, использующему веб-сервис, остается написать что-то типа (псевдокод):

    NewUser:=TSoapUser.Create("Вася","Пупкин","odmin"); soap.AddUser(NewUser);

  • Автоматическая валидация.

    • xml-валидация. xml должен быть well-formed. невалидный xml - сразу ошибка клиенту, пусть разбирается.
    • schema-валидация. xml должен иметь определенную структуру. xml не соответствует схеме - сразу ошибка клиенту, пусть разбирается.
    • проверка данных осуществляется soap-сервером, чтобы типы данных, ограничения соответствовали описанию.
  • Авторизация и аутентификация может быть реализована отдельным методом. нативно. либо, используя http-авторизацию.
  • Веб-сервисы могут работать как по soap-протоколу, так и по http, то есть через get-запросы. То есть, если в качестве параметров идут простые данные (без структуры), то можно вызвать просто обычный get www.site.com/users.asmx/GetUser?Name=Vasia или post. Впрочем это не везде и не всегда.
  • ... см. в википедии

Минусов тоже полно:

  • Неоправданно большой размер сообщений. Ну тут сама природа xml такова, что формат избыточный, чем больше тэгов, тем больше неполезной информации. Плюс soap добавляет своей избыточности. Для intranet-систем вопрос трафика стоит менее остро, чем для internet, поэтому soap для локальных сетей более востребован, в частности у Sharepoint есть soap веб-сервис, с которым с успехом (и некоторыми ограничениями) можно общаться.
  • Автоматическая смена описания веб-сервиса может сломать все клиенты. Ну это как бы для любой системы так, если не поддерживается обратная совместимость со старыми методами, все отвалится...
  • Не минус, но недостаток. Все действия по вызову методов должны быть атомарными. Например, работая с субд мы можем начать транзакцию, выполнить несколько запросов, потом откатиться или закоммитить. В soap транзакций нет. Один запрос-один ответ, разговор закончен.
  • Разбираться с описанием, что на стороне сервера (все ли правильно описано у меня?), что на клиенте (что мне тут наописывали?) бывает довольно сложно. Было несколько раз, когда мне приходилось разбираться с клиентской стороны, и убеждать серверного программера, что у него неверно описаны данные, а он в них вообще ничего понять не мог, ибо автоматическая генерация и он как бы и не должен, это дело софта. А ошибка естественно была в коде метода, программер ее не видел просто.
  • Практика показывает, что разработчики веб-сервисов страшно далеки от народа, использующего эти веб-сервисы. В ответ на какой-либо запрос (валидный со стороны) может прийти невразумительная ошибка "Ошибка 5. Все плохо". Все зависит от совести разработчиков:)
  • еще наверняка что-то не вспомнил...

В качестве примера есть открытый веб-сервис belavia:

  • http://86.57.245.235/TimeTable/Service.asmx - точка входа, там же текстовое описание методов для сторонних разработчиков.
  • http://86.57.245.235/TimeTable/Service.asmx?WSDL - wsdl описание методов и типов принимаемых и возращаемых данных.
  • http://86.57.245.235/TimeTable/Service.asmx?op=GetAirportsList - описание конкретного метода с примером вида xml-запроса и xml-ответа.

Можете вручную создать и послать запрос типа:

POST /TimeTable/Service.asmx HTTP/1.1 Host: 86.57.245.235 Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://webservices.belavia.by/GetAirportsList" ru

в ответ придет:

HTTP/1.1 200 OK Date: Mon, 30 Sep 2013 00:06:44 GMT Server: Microsoft-IIS/6.0 X-Powered-By: ASP.NET X-AspNet-Version: 4.0.30319 Cache-Control: private, max-age=0 Content-Type: text/xml; charset=utf-8 Content-Length: 2940

ЗЫ Раньше был открыт веб-сервис аэрофлота, но после того как 1C добавили поддержку soap в 8ку, куча 1с-бета-тестеров с успехом положили его. Сейчас что-то там поменяли (адреса не знаю, можно поискать, если интересно).
ЗЗЫ Дисклеймер. Рассказал на бытовом уровне. Пинать можно.

Here at LeaseWeb, we work a lot with SOAP web-services to integrate our internal applications with each other. Especially during development and testing of our applications as we need the ability to practice with SOAP API’s.

$ curl -sS http://leaseweb.github.io/php-soap-client/installer | php

This will download the phar file to the current working directory and make it executable so you can use start using it right away by invoking:

$ ./soap_client

To install the latest master version you can get the source code directly from GitHub , package your own .phar file and install it — using GNU Make .
In order to be able to create the .phar file you need to have composer installed. To read more about composer refer to their excellent documentation .

# Install php soap client $ git clone https://github.com/LeaseWeb/php-soap-client.git $ cd php-soap-client $ composer.phar install $ make $ sudo make install

If you are getting a Failed to compile phar exception while running make you need to set phar.readonly = Off in your php.ini . On a development machine this is fine to do but please be ware of the security risks when setting phar.readonly to Off .

The above make install command will install the soap_client application to /usr/local/bin and make it executable so you can easily call it like this:

$ soap_client php-soap-client version 2.1.3 Usage: command Options: ... Available commands: call Call the remote service with the `method` specified and output the reponse to stdout. help Displays help for a command list Lists commands list-methods Get a list of available methods to call on the remote. request Generate an xml formatted SOAP request for the given method and output to stdout. wsdl Get the WSDL of a soap service.

From this point onwards we assume you have installed the soap_client.phar on your system in /usr/local/bin/soap_client and that the directory /urs/local/bin is in your $PATH .

Lets say we would like to see what methods are available on the remote service http://www.webservicex.net/ConvertTemperature.asmx . We could issue the following command:

$ soap_client --endpoint="http://www.webservicex.net/ConvertTemperature.asmx?WSDL" list-methods

Which will output the following:

ConvertTemp

If you run the above command with the -vvv option you will get more verbose output.
In this case the only available method is ConvertTemp . Let’s see how a SOAP XML request looks like for this method:

$ soap_client --endpoint="http://www.webservicex.net/ConvertTemperature.asmx?WSDL" request ConvertTemp 0

If you want to make a SOAP request to the ConvertTemp method on the remote service use the call sub command:

$ soap_client --endpoint="http://www.webservicex.net/ConvertTemperature.asmx?WSDL" call --editor ConvertTemp

Notice the --editor option after the call sub command. If you use the --editor flag soap_client will open up the editor specified in your environment variable $EDITOR so you are able to modify the request XML before sending it.

If you issue the same request multiple times, you could save a soap request as a local XML file and pass it to /dev/stdin of the soap_client call command:

# Get the request xml and store it locally $ soap_client --endpoint="http://www.webservicex.net/ConvertTemperature.asmx?WSDL" request ConvertTemp > my_sample_request.xml # Now edit my_sample_request.xml # Now you can call the ConvertTemp method with this pre-prepared request $ soap_client --endpoint="http://www.webservicex.net/ConvertTemperature.asmx?WSDL" call ConvertTemp < my_sample_request.xml

Since you will be repeating soap_client commands frequently in a short time while exploring a remote web service you can save yourself some time by setting an environment variable SOAPCLIENT_ENDPOINT that contains the URL to the WSDL. When this environment variable is set you can omit the --endpoint command line option. Let’s do this now and call the ConvertTemp method:

$ export SOAPCLIENT_ENDPOINT="http://www.webservicex.net/ConvertTemperature.asmx?WSDL" $ soap_client call ConvertTemp < my_sample_request.xml

I wanted to know how much 107.6 degrees Fahrenheit is in Celsius, so my my_sample_request.xml contains:

$ cat my_sample_request.xml 107.6 degreeFahrenheit degreeCelsius

$ soap_client call ConvertTemp < my_sample_request.xml stdClass Object ( => 42)

The answer is 42.

If you rather see the responses in XML format you can use the --xml command line option:

$ soap_client call --xml ConvertTemp < my_sample_request.xml 42

This tutorial should give you enough information to get started with exploring, testing and/or developing SOAP API’s.
In a future blog post, I will continue the topic of the php soap client . We are currently working on packing the .phar archive for the web.

Tips for Users:

    If you know the WSDL file, you can setup a quick link to the client forms using
    http://www.?template=/clientform.html&fn=soapform
    &SoapTemplate=none&SoapWSDL=Your_WSDL_File
    or
    http://www..html?SoapWSDL=Your_WSDL_File

    The server caches WSDL files in normal operations to improve performance. If you make any changes to a WSDL file, select the No checkbox.

Tips for Developers:

    Use <documentation > whenever possible in your WSDL file to provide instructions. It will be displayed in the client form.

    Use enumeration type if an element has fix number of values. They will be displayed as dropdown boxes.

Key Features:

    Support both 1999 and 2001 XML schema. The tool uses the schema defined in the WSDL file for constructing SOAP requests.

    Support array and array of structs. Only single dimensional arrays are supported. Sorry, no sparse arrays.

    Capable of serializing complex data types and array of complex data types, even multi-level embedded structs.

    Handling ID/HREF in both SOAP messages and schema definitions.

    Support both SOAP section 5/7 and document/literal encodings..

Technical Details -- Dynamic Binding of SOAP Services

A binding is a contract between the client logic and server logic. There are two types of bindings in SOAP: Object binding (or SOAP binding) and parameter binding. Most of the SOAP toolkits perform static object bindings by generating client side proxy objects. The problem is that, unlike the traditional programming module where objects/interfaces are stable, web services are subject to change at any moment without notice, because they are often owned/controlled by a third party. Another problem occurs when the number of web services to be accessed increases, the generated source code could quickly becomes a maintenance nightmare. Finally, when the web services to be accessed are unknown, which is more often then likely, early binding becomes impossible, or at least difficult. Generating a proxy object for a service to be built in the future is an interesting research project.

The generic SOAP client demonstrates dynamic bindings (or run-time bindings) of SOAP services and parameters. An object is generated at execution time when WSDL file is specified, and parameter values are associated with a SOAP message just before delivery. The late binding (or delayed binding) technique could greatly reduces maintenance cost, because a single client can be used to access many web services.

Всем привет!
Так случилось, что в последнее время я стал заниматься разработкой веб-сервисов. Но сегодня топик не обо мне, а о том, как нам написать свой XML Web Service основанный на протоколе SOAP 1.2.

Я надеюсь, что после прочтения топика вы сможете самостоятельно:

  • написать свою собственную серверную реализацию веб-приложения;
  • написать свою собственную клиентскую реализацию веб-приложения;
  • написать свое собственное описание веб-сервиса (WSDL);
  • отправлять клиентом массивы однотипных данных на сервер.

Как вы могли догадаться, вся магия будет твориться с использованием PHP и встроенных классов SoapClient и SoapServer. В качестве кролика у нас будет выступать сервис по отправке sms-сообщений.

1 Постановка задачи

1.1 Границы

В начале предлагаю разобраться с тем результатом, которого мы достигнем в конце топика. Как было объявлено выше, мы будем писать сервис по отправке sms-сообщений, а если еще точнее, то к нам будут поступать сообщения из разных источников по протоколу SOAP. После чего, мы будем рассматривать в каком виде они приходят на сервер. Сам процесс постановки сообщений в очередь для их дальнейшей провайдеру, к сожалению, выходит за рамки данного поста по многим причинам.

1.2 Какими данными будем меняться?

Отлично, с границами мы определились! Следующим шагом, который необходимо сделать – решить какими данными мы будем обмениваться между сервером и клиентом. На эту тему предлагаю долго не мудрить и сразу для себя ответить на главные вопросы:

  • Какой минимум данных надо посылать на сервер, чтобы отправить sms-сообщение абоненту?
  • Какой минимум данных надо посылать с сервера, чтобы удовлетворить потребности клиента?

Что-то мне подсказывает, что для этого необходимо посылать следующее:

  • номер мобильного телефона, а также
  • текст sms-сообщения.

В принципе, двух этих характеристик достаточно для отправки, но мне сразу представляется случай, как sms-ка с поздравлением о дне рождения приходит вам в 3 часа утра, или 4! В этот момент я буду всем очень благодарен за то, что про меня не забыли! Поэтому, мы также будем посылать на сервер и

  • дату отправки sms-сообщения.

Следующее, что я бы хотел отправлять на сервер, так это

  • Тип сообщения.

Данный параметр не является обязательным, но он может нам очень сильно пригодиться в случае, если быстро понадобится сказать боссу о том, скольких из наших клиентов мы «обрадовали» своим известием, а также нарисовать какую-нибудь красивую статистику на этот счет.

И все же, я что-то забыл! Если еще немного порефлексировать, то стоит отметить, что клиент за раз может отправить на сервер как одно sms-сообщение, так и некоторое их количество. Другими словами, в одном пакете данных может быть от одного до бесконечности сообщений.

В результате мы получаем, что для отправки sms-сообщения нам необходимы следующие данные:

  • номер мобильного телефона,
  • текст sms-сообщения,
  • время отправки sms-сообщения абоненту,
  • тип сообщения.

На первый вопрос мы ответили, теперь необходимо ответить на второй вопрос. И пожалуй, я позволю себе немного с халтурить. Поэтому, с сервера мы будем присылать только булевы данные, значение которых имеет следующий смысл:

  • TRUE – пакет успешно дошел до сервера, прошел аутентификацию и встал в очередь для отправки sms-провайдеру
  • FALSE – во всех остальных случаях

На этом мы закончили описание постановки задачи! И наконец-то приступим к самому интересному – будем разбираться что за диковинный зверь этот SOAP!

2 С чем есть SOAP?

Вообще, изначально я не планировал ничего писать о том, что такое SOAP и хотел ограничиться ссылками на сайт w3.org с нужными спецификациями, а также ссылками на Wikipedia. Но в самом конце решил написать коротенькую справочку об этом протоколе.

И начну я свое повествование с того, что данный протокол обмена данными относится к подмножеству протоколов основанных на так называемой парадигме RPC (Remote Procedure Call, удалённый вызов процедур) антиподом которой является REST (Representational State Transfer, передача репрезентативного состояния). Более подробно об этом можно прочесть в Wikipedia, ссылки на статьи находятся в самом конце топика. Из этих статей нам надо уяснить следующее: «Подход RPC позволяет использовать небольшое количество сетевых ресурсов с большим количеством методов и сложным протоколом. При подходе REST количество методов и сложность протокола строго ограничены, из-за чего количество отдельных ресурсов может быть большим». Т.е., применительно к нам это означает, что на сайте в случае RPC подхода будет всегда один вход (ссылка) на сервис и какую процедуру вызывать для обработки поступающих данных мы передает вместе с данными, в то время как при REST подходе на нашем сайте есть много входов (ссылок), каждая из которых принимает и обрабатывает только определенные данные. Если кто-то из читающих знает, как еще проще объяснить различие в данных подходах, то обязательно пишите в комментариях!

Следующее, что нам надо узнать про SOAP – данный протокол в качестве транспорта использует тот самый XML, что с одной стороны очень хорошо, т.к. сразу же в наш арсенал попадает вся мощь стека технологий основанных на данном языке разметки, а именно XML-Schema – язык описания структуры XML-документа (спасибо Wikipedia!), который позволяет производит автоматическую валидацию поступающих на сервер данных от клиентов.

И так, теперь мы знаем, что SOAP – протокол используемый для реализации удаленного вызова процедур и в качестве транспорта он использует XML! Если почитать статью на Wikipedia, то оттуда можно узнать еще и о том, что он может использоваться поверх любого протокола прикладного уровня, а не только в паре с HTTP (к сожалению, в данном топике мы будем рассматривать только SOAP поверх HTTP). И знаете, что мне во всем этом больше всего нравится? Если нет никаких догадок, то я дам подсказку – SOAP!… Всеравно не появилось догадок?… Вы точно прочли статью на Wikipedia?… В общем, не буду вас дальше мучить. Поэтому, сразу перейду к ответу: «SOAP (от англ. Simple Object Access Protocol - простой протокол доступа к объектам; вплоть до спецификации 1.2 )». Самое примечательное в этой строчке выделено курсивом! Я не знаю какие выводы сделали вы из всего этого, но мне видится следующее – поскольку данный протокол ну никак нельзя назвать «простым» (и видимо с этим согласны даже в w3), то с версии 1.2 он вообще перестал как-то расшифровываться! И стал называться SOAP, просто SOAP и точка.

Ну да ладно, прошу меня извинить, занесли немного в сторону. Как я писал ранее, в качестве транспорта используется XML, а пакеты, которые курсируют между клиентом и сервером называются SOAP-конвертами. Если рассматривать обобщенную структуру конверта, то он вам покажется очень знакомым, т.к. напоминает разметку HTML-страницы. В нем есть основной раздел – Envelop , который включает разделы Header и Body , либо Fault . В Body передаются данные и он является обязательным разделом конверта, в то время как Header является опциональным. В Header может передаваться авторизация, либо какие-либо иные данные, которые на прямую не относятся к входным данным процедур веб-сервиса. Про Fault особо рассказывать нечего, кроме того, что он приходит в клиент с сервера в случае возникновения каких-либо ошибок.

На этом мой обзорный рассказ про протокол SOAP заканчивается (более детально сами конверты и их структуру мы рассмотрим когда наши клиент и сервер наконец-то научатся запускать их друг в друга) и начинается новый – про компаньона SOAP под названием WSDL (Web Services Description Language). Да-да, это та самая штука, которая отпугивает большинство из нас от самой попытки взять и реализовать свое API на данном протоколе. В результате чего, мы обычно изобретаем свой велосипед с JSON в качестве транспорта. И так, что такое WSDL? WSDL – язык описания веб-сервисов и доступа к ним, основанный на языке XML (с) Wikipedia. Если из этого определения вам не становится понятным весь сакральный смысл данной технологии, то я попытаюсь описать его своими словами!

WSDL предназначен для того, чтобы наши клиенты могли нормально общаться с сервером. Для этого в файле с расширением «*.wsdl» описывается следующая информация:

  • Какие пространства имен использовались,
  • Какие схемы данных использовались,
  • Какие типы сообщений веб-сервис ждет от клиентов,
  • Какие данные принадлежат каким процедурам веб-сервиса,
  • Какие процедуры содержит веб-сервис,
  • Каким образом клиент должен вызывать процедуры веб-сервиса,
  • На какой адрес должны отправляться вызовы клиента.

Как видно, данный файл и есть весь веб-сервис. Указав в клиенте адрес WSDL-файла мы будем знать об любом веб-сервисе все! В результате, нам не надо абсолютно ничего знать о том, где расположен сам веб-сервис. Достаточно знать адрес расположения его WSDL-файла! Скоро мы узнаем, что не так страшен SOAP как его малюют (с) русская пословицы.

3 Введение в XML-Schema

Теперь мы много чего знаем о то, что такое SOAP, что находится у него внутри и имеем обзорное представление о том, какой стек технологий его окружает. Поскольку, прежде всего SOAP представляет собой способ взаимодействия между клиентом и сервером, и в качестве транспорта для него используется язык разметки XML, то в данном разделе мы немного разберемся каким образом происходит автоматическая валидация данных посредством XML-схем.

Основная задачи схемы – описать структуру данных которые мы собираемся обрабатывать. Все данные в XML-схемах делятся на простые (скалярные) и коплексные (структуры) типы. К простым типам относятся такие типы как:

  • строка,
  • число,
  • булево значение,
  • дата.

Что-то очень простое, у чего внутри нет расширений. Их антиподом являются сложные комплексные типы. Самый простой пример комплексного типа, который приходит всем в голову – объекты. Например, книга. Книга состоит из свойств: автор , название , цена , ISBN номер и т.д. И эти свойства, в свою очередь, могут быть как простыми типами, так и комплексными. И задача XML-схемы это описать.

Предлагаю далеко не ходить и написать XML-схему для нашего sms-сообщения! Ниже представлено xml-описание sms-сообщения:

71239876543 Тестовое сообщение 2013-07-20T12:00:00 12

Схема нашего комплексного типа будет выглядеть следующим образом:

Эта запись читается следующим образом: у нас есть переменная «message » типа «Message » и есть комплексный тип с именем «Message », который состоит из последовательного набора элементов «phone » типа string , «text » типа string , «date » типа dateTime , «type » типа decimal . Эти типы простые и уже определены в описании схемы. Поздравляю! Мы только что написали нашу первую XML-схему!

Думаю, что значение элементов «element » и «complexType » вам стало все более-менее понятно, поэтому не будем на них больше заострять внимание и переключимся сразу же на элемент-композитор «sequence ». Когда мы используем элемент-композитор «sequence » мы сообщаем о том, что элементы включенные в него должны всегда располагаться в указанной в схеме последовательности, а также все из них являются обязательными. Но не стоит отчаиваться! В XML-схемах есть еще два элемента-композитора: «choice » и «all ». Композитор «choice » сообщает о том, что должен быть какой-то один из перечисленных в нем элементов, а композитор «all » – любая комбинация перечисленных элементов.

Как вы помните, то в первом разделе топика мы договорились о том, что в пакете может передаваться от одного до бесконечности sms-сообщений. Поэтому предлагаю разобраться как такие данные декларируются в XML-схеме. Общая структура пакета может выглядеть следующим образом:

71239876543 Тестовое сообщение 1 2013-07-20T12:00:00 12 71239876543 Тестовое сообщение N 2013-07-20T12:00:00 12

Схема для такого комплексного типа будет выглядеть так:

В первом блоке идет знакомое нам декларирование комплексного типа «Message ». Если вы заметили, то в каждом простом типе, входящем в «Message », были добавлены новые уточняющие атрибуты «minOccurs » и «maxOccurs ». Как не трудно догадаться из названия, первый (minOccurs ) сообщает о том, что в данной последовательности должно быть минимум по одному элементу типа «phone », «text », «date » и «type », в то время как следующий (maxOccurs ) атрибут нам декларирует, что таких элементов в нашей последовательности максимум по-одному. В результате, когда мы пишем свои схемы для каких-либо данных, нам предоставляется широчайший выбор по их настройке!

Второй блок схемы декларирует элемент «messageList » типа «MessageList ». Видно, что «MessageList » представляет собой комплексный тип, который включает минимум один элемент «message », но максимальное число таких элементов не ограничено!

4 Пишем свой WSDL

Вы помните о том, что WSDL и есть наш веб-сервис? Надеюсь, что помните! Как мы его напишем, так на нем наш маленький веб-сервис и поплывет. Поэтому, предлагаю не халтурить.

Вообще, для того, чтобы у нас все работало правильно нам надо передавать клиенту WSDL-файл с правильным MIME-типом. Для этого необходимо настроить ваш веб-сервер соответствующим образом, а именно – установить для файлов с расширением «*.wsdl» MIME-тип равный следующей строке:

Application/wsdl+xml

Но на практике, я обычно отправлял посредством PHP HTTP-заголовок«text/xml »:

Header("Content-Type: text/xml; charset=utf-8");

и все прекрасно работало!

Хочу сразу предупредить, наш простенький веб-сервис будет иметь довольно внушительное описание, поэтому не пугайтесь, т.к. большая часть текста является обязательной водой и написав ее один раз можно постоянно копировать от одного веб-сервиса к другому!

Поскольку WSDL – это XML, то в самой первой строке необходимо прямо об этом и написать. Корневой элемент файла всегда должен называться «definitions »:

Обычно, WSDL состоит из 4-5 основных блоков. Самый первый блок – определение веб-сервиса или другими словами – точки входа.

Здесь написано, что у нас есть сервис, который называется – «SmsService ». В принципе, все имена в WSDL-файле могут быть вами изменены на какие только пожелаете, т.к. они не играют абсолютно никакой роли.

После этого мы объявляем о том, что в нашем веб-сервисе «SmsService » есть точка входа («port»), которая называется «SmsServicePort ». Именно в эту точку входа и будут отправляться все запросы от клиентов к серверу. И указываем в элементе «address » ссылку на файл-обработчик, который будет принимать запросы.

После того, как мы определили веб-сервис и указали для него точку входа – необходимо привязать к нему поддерживаемые процедуры:

Для этого перечисляется какие операции и в каком виде у будут вызываться. Т.е. для порта «SmsServicePort » определена привязка под именем «SmsServiceBinding », которая имеет тип вызова «rpc » и в качестве протокола передачи (транспорта) используется HTTP. Т.о., мы здесь указали, что будем осуществлять RPC вызов поверх HTTP. После этого мы описываем какие процедуры (operation ) поддерживаются в веб-сервисе. Мы будем поддерживать всего одну процедуру – «sendSms ». Через эту процедуру будут отправляться на сервер наши замечательные сообщения! После того, как была объявлена процедура, необходимо указать в каком виде будут передаваться данные. В данном случае указано, что будут использоваться стандартные SOAP-конверты.

После этого нам необходимо привязать процедуру к сообщениям:

Для этого мы указываем, что наша привязка («binding») имеет тип «SmsServicePortType » и в элементе «portType » с одноименным типу именем указываем привязку процедур к сообщениям. И так, входящее сообщение (от клиента к серверу) будет называться «sendSmsRequest », а исходящее (от сервера к клиенту) «sendSmsResponse ». Как и все имена в WSDL, имена входящих и исходящих сообщения – произвольные.

Теперь нам необходимо описать сами сообщения, т.е. входящие и исходящие:

Для этого мы добавляем элементы «message » с именами «sendSmsRequest » и «sendSmsResponse » соответственно. В них мы указываем, что на вход должен прийти конверт, структура которого соответствует типу данных «Request ». После чего с сервера возвращается конверт содержащий тип данных – «Response ».

Теперь надо сделать самую малость – добавить описание данных типов в наш WSDL-файл! И как вы думаете, как описываются в WSDL входящие и исходящие данные? Думаю, что вы уже все давно поняли и сказали сами себе, что при помощи XML-схем! И вы будете абсолютно правы!

Можно нас поздравить! Наш первый WSDL был написан! И мы еще на один шаг приблизились к достижению поставленной цели.
Далее мы разберемся с тем, что нам предоставляет PHP для разработки собственных распределенных приложений.

5 Наш первый SOAP-сервер

Ранее я писал, что для создания SOAP-сервера на PHP мы будем использовать встроенный класс SoapServer. Для того, чтобы все дальнейшие действия происходили также как и у меня, вам понадобиться немного подкрутить свой PHP. Если быть еще точнее, то необходимо убедиться, что у вас установлено расширение «php-soap». Как его поставить на ваш веб-сервере лучше всего прочитать на официальном сайте PHP (см. список литературы).

После того, как все было установлено и настроено нам необходимо будет создать в корневой папке вашего хостинга файл «smsservice.php » со следующим содержанием:

setClass("SoapSmsGateWay"); //Запускаем сервер $server->handle();

То, что находится выше строчки с функцией «ini_set», надеюсь, что объяснять не надо. Т.к. там определяется какие HTTP-заголовки мы будем отправлять с сервера клиенту и настраивается окружение. В строчке с «ini_set» мы отключаем кеширование WSDL-файла для того, чтобы наши изменения в нем сразу же вступали в действие на клиенте.

Теперь мы подошли к серверу! Как видим, весь SOAP-сервер занимает всего лишь три строки! В первой строке мы создаем новый экземпляр объекта SoapServer и передаем ему в конструктор адрес нашего WSDL-описания веб-сервиса. Теперь мы знаем, что он будет располагаться в корне хостинга в файле с говорящим именем «smsservice.wsdl.php ». Во второй строке мы сообщаем SOAP-серверу какой класс необходимо дергать для того, чтобы обработать поступивший с клиента конверт и вернуть конверт с ответом. Как вы могли догадаться, именно в этом классе будет описан наш единственный метод sendSms . В третьей строке мы запускаем сервер! Все, наш сервер готов! С чем я нас всех и поздравляю!

Теперь нам необходимо создать WSDL-файл. Для этого можно либо просто скопировать его содержимое из предыдущего раздела, либо позволить себе вольности и немного его «шаблонизировать»:

"; ?> /" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:http="http://schemas.xmlsoap.org/wsdl/http/" name="SmsWsdl" xmlns="http://schemas.xmlsoap.org/wsdl/"> /"> /smsservice.php" />

На этом этапе получившийся сервер нас должен устроить полностью, т.к. поступающие к нему конверты мы можем логировать и потом спокойно анализировать приходящие данные. Для того, чтобы мы могли что-либо получать на сервер, нам необходим клиент. Поэтому давайте им и займемся!

6 SOAP-клиент на подходе

Прежде всего нам надо создать файл, в котором будем писать клиент. Как обычно, мы его создадим в корне хоста и назовем «client.php », а внутри напишем следующее:

messageList = new MessageList(); $req->messageList->message = new Message(); $req->messageList->message->phone = "79871234567"; $req->messageList->message->text = "Тестовое сообщение 1"; $req->messageList->message->date = "2013-07-21T15:00:00.26"; $req->messageList->message->type = 15; $client = new SoapClient("http://{$_SERVER["HTTP_HOST"]}/smsservice.wsdl.php", array("soap_version" => SOAP_1_2)); var_dump($client->sendSms($req));

Опишем наши объекты. Когда мы писали WSDL в нем для входящего на сервер конверта описывались три сущности: Request , MessageList и Message . Соответственно классы Request , MessageList и Message являются отражениями этих сущностей в нашем PHP-скрипте.

После того, как мы определили объекты, нам необходимо создать объект ($req ), который будем отправлять на сервер. После чего идут две самые заветные для нас строки! Наш SOAP-клиент! Верите или нет, но этого достаточно для того, чтобы на наш сервер начали сыпаться сообщения от клиента, а также для того, чтобы наш сервер успешно их принимал и обрабатывал! В первой из них мы создаем экземпляр класса SoapClient и передаем в его конструктор адрес расположения WSDL-файла, а в параметрах явно указываем, что работать мы будем по протоколу SOAP версии 1.2. В следующей строке мы вызываем метод sendSms объекта $client и сразу же выводим в браузере результат.
Давайте запусти и посмотрим что-же у нас наконец-то получилось!

Мне с сервера вернулся следующий объект:

Object(stdClass) public "status" => boolean true

И это замечательно, т.к. теперь мы точно знаем о том, что наш сервер работает и не просто работает, но еще и может возвращать на клиент какие-то значения!

Теперь посмотрим на лог, который мы предусмотрительно ведем на серверной стороне! В первой его части мы видим необработанные данные, которые поступили на сервер:

79871234567 Тестовое сообщение 1 2013-07-21T15:00:00.26 15

Это и есть конверт. Теперь вы знаете как он выглядит! Но постоянно на него любоваться нам вряд ли будет интересно, поэтому давайте десереализуем объект из лог-файла и посмотрим все ли у нас хорошо:

Object(stdClass) public "messageList" => object(stdClass) public "message" => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 1" (length=37) public "date" => string "2013-07-21T15:00:00.26" (length=22) public "type" => string "15" (length=2)

Как видим, объект десериализовался правильно, с чем я нас всех хочу поздравить! Далее нас ждет что-то более интересно! А именно – мы будем отправлять клиентом на сервер не одно sms-сообщение, а целую пачку (если быть точнее, то целых три)!

7 Отправляем сложные объекты

Давайте подумаем над тем, как же нам передать целую пачку сообщений на сервер в одном пакете? Наверно, самым простым способом будет организация массива внутри элемента messageList! Давайте это сделаем:

// создаем объект для отправки на сервер $req = new Request(); $req->messageList = new MessageList(); $msg1 = new Message(); $msg1->phone = "79871234567"; $msg1->text = "Тестовое сообщение 1"; $msg1->date = "2013-07-21T15:00:00.26"; $msg1->type = 15; $msg2 = new Message(); $msg2->phone = "79871234567"; $msg2->text = "Тестовое сообщение 2"; $msg2->date = "2014-08-22T16:01:10"; $msg2->type = 16; $msg3 = new Message(); $msg3->phone = "79871234567"; $msg3->text = "Тестовое сообщение 3"; $msg3->date = "2014-08-22T16:01:10"; $msg3->type = 17; $req->messageList->message = $msg1; $req->messageList->message = $msg2; $req->messageList->message = $msg3;

В наших логах числится, что пришел следующий пакет от клиента:

79871234567 Тестовое сообщение 1 2013-07-21T15:00:00.26 15 79871234567 Тестовое сообщение 2 2014-08-22T16:01:10 16 79871234567 Тестовое сообщение 3 2014-08-22T16:01:10 17

Что за ерунда, скажете вы? И будете правы в некотором смысле, т.к. только что мы узнали о том, что какой объект ушел от клиента, то абсолютно в том же виде он пришел к нам на сервер в виде конверта. Правда, sms-сообщения сериализовались в XML не так, как нам было необходимо – они должны были быть обернуты в элементы message , а не в Struct . Теперь посмотрим в каком виде приходит такой объект в метод sendSms :

Object(stdClass) public "messageList" => object(stdClass) public "message" => object(stdClass) public "Struct" => array (size=3) 0 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 1" (length=37) public "date" => string "2013-07-21T15:00:00.26" (length=22) public "type" => string "15" (length=2) 1 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 2" (length=37) public "date" => string "2014-08-22T16:01:10" (length=19) public "type" => string "16" (length=2) 2 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 3" (length=37) public "date" => string "2014-08-22T16:01:10" (length=19) public "type" => string "17" (length=2)

Что нам дает это знание? Только то, что выбранный нами путь не является верным и мы не получили ответа на вопрос – «Как нам на сервере получить правильную структуру данных?». Но я предлагаю не отчаиваться и попробовать привести наш массив к типу объект :

$req->messageList->message = (object)$req->messageList->message;

В этом случае, нам придет уже другой конверт:

79871234567 Тестовое сообщение 1 2013-07-21T15:00:00.26 15 79871234567 Тестовое сообщение 2 2014-08-22T16:01:10 16 79871234567 Тестовое сообщение 3 2014-08-22T16:01:10 17

Пришедший в метод sendSms объект имеет следующую структуру:

Object(stdClass) public "messageList" => object(stdClass) public "message" => object(stdClass) public "BOGUS" => array (size=3) 0 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 1" (length=37) public "date" => string "2013-07-21T15:00:00.26" (length=22) public "type" => string "15" (length=2) 1 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 2" (length=37) public "date" => string "2014-08-22T16:01:10" (length=19) public "type" => string "16" (length=2) 2 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 3" (length=37) public "date" => string "2014-08-22T16:01:10" (length=19) public "type" => string "17" (length=2)

Как по мне, то «от перемены мест слагаемых – сумма не меняется» (с). Что BOGUS , что Struct – цель нами до сих пор не достигнута! А для ее достижения нам необходимо сделать так, чтобы вместо этих непонятных названий отображалось наше родное message . Но как этого добиться, автору пока не известно. Поэтому единственное, что мы можем сделать – избавить от лишнего контейнера. Другими словами, мы сейчас сделаем так, чтобы вместо message стал BOGUS ! Для этого изменим объект следующим образом:

// создаем объект для отправки на сервер $req = new Request(); $msg1 = new Message(); $msg1->phone = "79871234567"; $msg1->text = "Тестовое сообщение 1"; $msg1->date = "2013-07-21T15:00:00.26"; $msg1->type = 15; $msg2 = new Message(); $msg2->phone = "79871234567"; $msg2->text = "Тестовое сообщение 2"; $msg2->date = "2014-08-22T16:01:10"; $msg2->type = 16; $msg3 = new Message(); $msg3->phone = "79871234567"; $msg3->text = "Тестовое сообщение 3"; $msg3->date = "2014-08-22T16:01:10"; $msg3->type = 17; $req->messageList = $msg1; $req->messageList = $msg2; $req->messageList = $msg3; $req->messageList = (object)$req->messageList;

Вдруг нам повезет и из схемы подтянется правильное название? Для этого посмотрим на пришедший конверт:

79871234567 Тестовое сообщение 1 2013-07-21T15:00:00.26 15 79871234567 Тестовое сообщение 2 2014-08-22T16:01:10 16 79871234567 Тестовое сообщение 3 2014-08-22T16:01:10 17

Да, чуда не произошло! BOGUS – не победим! Пришедший в sendSms объект в этом случае будет выглядеть следующим образом:

Object(stdClass) public "messageList" => object(stdClass) public "BOGUS" => array (size=3) 0 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 1" (length=37) public "date" => string "2013-07-21T15:00:00.26" (length=22) public "type" => string "15" (length=2) 1 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 2" (length=37) public "date" => string "2014-08-22T16:01:10" (length=19) public "type" => string "16" (length=2) 2 => object(stdClass) public "phone" => string "79871234567" (length=11) public "text" => string "Тестовое сообщение 3" (length=37) public "date" => string "2014-08-22T16:01:10" (length=19) public "type" => string "17" (length=2)

Как говорится – «Почти»! На этой (немного печальной) ноте предлагаю потихонечку закругляться и сделать некоторые для себя выводы.

8 Заключение

Наконец-то мы добрались сюда! Давайте определимся с тем, что вы теперь умеете делать:

  • вам по силам написать необходимый для вашего веб-сервиса WSDL-файл;
  • вы без всяких проблем можете написать свой собственный клиент способный общаться с сервером по протоколу SOAP;
  • вы можете написать свой собственный сервер общающийся с окружающим миром по SOAP;
  • вы можете отправлять массивы однотипных объектов на сервер со своего клиента (с некоторыми ограничениями).

Также, мы сделали для себя некоторые открытия в ходе нашего небольшого исследования:

  • нативный класс SoapClient не умеет правильно сериализовывать однотипные структуры данных в XML;
  • при сериализации массива в XML он создает лишний элемент с именем Struct ;
  • при сериализации объекта в XML он создает лишний элемент с именем BOGUS ;
  • BOGUS меньшее зло чем Struct из-за того, что конверт получается компактнее (не добавляются лишние namespace"ы в XML заголовке конверта);
  • к сожалению, класс SoapServer автоматически не валидирует данные конверта нашей XML-схемой (возможно, и другие сервера этого не делают).

(PHP 5 >= 5.0.1)

SoapClient::SoapClient — SoapClient constructor

Parameters

wsdl

URI of the WSDL file or NULL if working in non-WSDL mode.

During development, WSDL caching may be disabled by the use of the soap.wsdl_cache_ttl php.ini setting otherwise changes made to the WSDL file will have no effect until soap.wsdl_cache_ttl is expired.

options

An array of options. If working in WSDL mode, this parameter is optional. If working in non-WSDL mode, the location and uri options must be set, where location is the URL of the SOAP server to send the request to, and uri is the target namespace of the SOAP service.

The style and use options only work in non-WSDL mode. In WSDL mode, they come from the WSDL file.

The soap_version option specifies whether to use SOAP 1.1 (default), or SOAP 1.2 client.

For HTTP authentication, the login and password options can be used to supply credentials. For making an HTTP connection through a proxy server, the options proxy_host , proxy_port , proxy_login and proxy_password are also available. For HTTPS client certificate authentication use local_cert and passphrase options. An authentication may be supplied in the authentication option. The authentication method may be either SOAP_AUTHENTICATION_BASIC (default) or SOAP_AUTHENTICATION_DIGEST .

The compression option allows to use compression of HTTP SOAP requests and responses.

The encoding option defines internal character encoding. This option does not change the encoding of SOAP requests (it is always utf-8), but converts strings into it.

The trace option enables tracing of request so faults can be backtraced. This defaults to FALSE

The classmap option can be used to map some WSDL types to PHP classes. This option must be an array with WSDL types as keys and names of PHP classes as values.

Setting the boolean trace option enables use of the methods SoapClient->__getLastRequest , SoapClient->__getLastRequestHeaders , SoapClient->__getLastResponse and SoapClient->__getLastResponseHeaders .

The exceptions option is a boolean value defining whether soap errors throw exceptions of type SoapFault .

The connection_timeout option defines a timeout in seconds for the connection to the SOAP service. This option does not define a timeout for services with slow responses. To limit the time to wait for calls to finish the default_socket_timeout setting is available.

The typemap option is an array of type mappings. Type mapping is an array with keys type_name , type_ns (namespace URI), from_xml (callback accepting one string parameter) and to_xml (callback accepting one object parameter).

The cache_wsdl option is one of WSDL_CACHE_NONE , WSDL_CACHE_DISK , WSDL_CACHE_MEMORY or WSDL_CACHE_BOTH .

The user_agent option specifies string to use in User-Agent header.

The stream_context option is a for context .

The features option is a bitmask of SOAP_SINGLE_ELEMENT_ARRAYS , SOAP_USE_XSI_ARRAY_TYPE , SOAP_WAIT_ONE_WAY_CALLS .

The keep_alive option is a boolean value defining whether to send the Connection: Keep-Alive header or Connection: close .

Changelog

Version Description
5.4.0 New keep_alive option.

Examples

Example #1 SoapClient::SoapClient() example

$client = new SoapClient ("some.wsdl" );

$client = new SoapClient ("some.wsdl" , array("soap_version" => SOAP_1_2 ));

$client = new SoapClient ("some.wsdl" , array("login" => "some_name" ,
"password" => "some_password" ));

$client = new SoapClient ("some.wsdl" , array("proxy_host" => "localhost" ,
"proxy_port" => 8080 ));

$client = new SoapClient ("some.wsdl" , array("proxy_host" => "localhost" ,
"proxy_port" => 8080 ,
"proxy_login" => "some_name" ,
"proxy_password" => "some_password" ));

$client = new SoapClient ("some.wsdl" , array("local_cert" => "cert_key.pem" ));

$client = new SoapClient (null , array("location" =>
"uri" => "http://test-uri/" ));

$client = new SoapClient (null , array("location" => "http://localhost/soap.php" ,
"uri" => "http://test-uri/" ,
"style" => SOAP_DOCUMENT ,
"use" => SOAP_LITERAL ));

$client = new SoapClient ("some.wsdl" ,
array("compression" => SOAP_COMPRESSION_ACCEPT | SOAP_COMPRESSION_GZIP ));

$server = new SoapClient ("some.wsdl" , array("encoding" => "ISO-8859-1" ));

class MyBook {
public $title ;
public $author ;
}

$server = new SoapClient ("books.wsdl" , array("classmap" => array("book" => "MyBook" )));

?>

Chris Gunawardena

To monitor SOAP calls in and out of a unix server:

Sudo tcpdump -nn -vv -A -s 0 -i eth0 dst or src host xxx.xxx.xxx.xxx and port 80

And always use "cache_wsdl" => WSDL_CACHE_NONE

svenr at selfhtml dot org

The "classmap" option actually is a mapping from the "ComplexType" used within the SOAP to your PHP Classes.

Do not confuse the XML tag names returned for your request with these ComplexTypes. SOAP allows them to be different.

I had something like this:
...


FooBar

TagName is not the key you want to put in your classmap, you have to know the name of the ComplexType this TagName refers to. This info is contained inside the WSDL resource.

paulovitorbal at gmail dot com

When using certificates, in the parameter "local_cert", use the file contents, not the name of the file.

New soapclient("http://localhost/index.php?wsdl ", array("local_cert"=>file_get_contents("./key.pem"),"passphrase"=>"password"));

In PHP, you can have private properties defined in the classes you use in your classmap. So if you create a private property $foo in you class, and the SOAP element has a child element , the contents of $foo will be set to the contents of . This way you can control acces to the properties in your classes.

(Note: This does not work in Facebook"s HPHP).

willem dot stuursma at hyves dot nl

If you want to use classes in a different namespace in your classmap, just use the backslash in the the target class name.

Example:
$classmap = array("result" => "MyNamespace\\Result" );
?>

You need to specify the backslash twice because it is the escape character in strings.

simonlang at gmx dot ch

Example for a soap client with HTTP authentication over a proxy:

new SoapClient (
"service.wsdl" ,
array(
// Stuff for development.
"trace" => 1 ,
"exceptions" => true ,
"cache_wsdl" => WSDL_CACHE_NONE ,
"features" => SOAP_SINGLE_ELEMENT_ARRAYS ,

// Auth credentials for the SOAP request.
"login" => "username" ,
"password" => "password" ,

// Proxy url.
"proxy_host" => "example.com" , // Do not add the schema here (http or https). It won"t work.
"proxy_port" => 44300 ,

// Auth credentials for the proxy.
"proxy_login" => NULL ,
"proxy_password" => NULL ,
);
?>
Providing an URL to a WSDL file on the remote server (which as well is protected with HTTP authentication) didn"t work. I downloaded the WSDL and stored it on the local server.

Asaf Meller

A full working php .net soap configuration:
notes
1. web.config on .net server must work with basichttp binding.
2. paramaters to soap functions must be passed as:
array ("parm1_name"=>"parm1_value",
"parm2_name"=>"parm2_value"...)

header ("Content-Type: text/plain" );

Try {
$options = array(
"soap_version" => SOAP_1_1 ,
"exceptions" => true ,
"trace" => 1 ,
"cache_wsdl" => WSDL_CACHE_NONE
);
$client = new SoapClient ("http://www.example.com/end_point.wsdl " , $options );

} catch (Exception $e ) {
echo "

Exception Error!

" ;
echo $e -> getMessage ();
}

Echo "running HelloWorld:" ;

Try {
$response = $client -> HelloWorld ();

}
catch (Exception $e )
{
echo "Caught exception: " , $e -> getMessage (), "\n" ;
}

Print_r ($response );
?>
good luck !
Asaf.

faebu at faebu dot ch

I"m experiencing the same problems when trying to load a WDSL fiel which is protected by basic http authentication, since the parameters login and password are just used for the request but not when reading the wdsl file. I just use the following workaround by downloading the xml file to a non-protected location on my server. Please notice that this doesn"t support any kind of caching.

class SoapAuthClient extends SoapClient {
/**
* Since the PHP SOAP package does not support basic authentication
* this class downloads the WDSL file using the cURL package and
* creates a local copy of the wdsl on your server.
* Make sure you provide the following additional parameter in the
* $options Array:
* wdsl_local_copy => true
*/

Private $cache_dir = "/home/example/htdocs/cache/" ;
private $cache_url = "http://www.example.com/cache/ " ;

Function SoapAuthClient ($wdsl , $options ) {
if (isset($options [ "wdsl_local_copy" ]) &&
$options [ "wdsl_local_copy" ] == true &&
isset($options [ "login" ]) &&
isset($options [ "password" ])) {

$file = md5 (uniqid ()). ".xml" ;

If (($fp = fopen ($this -> cache_dir . $file , "w" )) == false ) {
throw new Exception ("Could not create local WDSL file (" . $this -> cache_dir . $file . ")" );
}

$ch = curl_init ();
$credit = ($options [ "login" ]. ":" . $options [ "password" ]);
curl_setopt ($ch , CURLOPT_URL , $wdsl );
curl_setopt ($ch , CURLOPT_HTTPAUTH , CURLAUTH_BASIC );
curl_setopt ($ch , CURLOPT_USERPWD , $credit );
curl_setopt ($ch , CURLOPT_TIMEOUT , 15 );
curl_setopt ($ch , CURLOPT_FILE , $fp );
if (($xml = curl_exec ($ch )) === false ) {
//curl_close($ch);
fclose ($fp );
unlink ($this -> cache_dir . $file );

Throw new Exception (curl_error ($ch ));
}

Curl_close ($ch );
fclose ($fp );
$wdsl = $this -> cache_url . $file ;
}

Unset($options [ "wdsl_local_copy" ]);
unset($options [ "wdsl_force_local_copy" ]);

Echo $wdsl ;
parent :: __construct ($wdsl , $options );

Unlink ($this -> cache_dir . $file );
}
}
?>

tatupheba at gmail dot com

Hello folks!

A hint for developers:

When programming some soap server set the "soap.wsdl_cache_enabled" directive in php.ini file to 0:

Soap.wsdl_cache_enabled=0

Otherwise it will give a bunch of strange errors saying that your wsdl is incorrect or is missing.

Doing that will save you from a lot of useless pain.

titan at phpdevshell dot org

It should be noted that if you receive a return error: "Object reference not set to an instance of an object.". This could be due to something as simple as passing the incorrect parameters. When you look at this XML:



string
dateTime
dateTime

Your code should look something like this:

try {
$options = array(
"soap_version" => SOAP_1_2 ,
"exceptions" => true ,
"trace" => 1 ,
"cache_wsdl" => WSDL_CACHE_NONE
);
$client = new SoapClient ("http://example.com/doc.asmx?WSDL " , $options );
// Note where "Get" and "request" tags are in the XML
$results = $client -> Get (array("request" =>array("CustomerId" => "1234" )));
} catch (Exception $e ) {
echo "

Exception Error!

" ;
echo $e -> getMessage ();
}

$results = $client -> Get (array("request" =>array("CustomerId" => "842115" )));
?>

If your WSDL file containts a parameter with a base64Binary type, you should not use base64_encode() when passing along your soap vars. When doing the request, the SOAP library automatically base64 encodes your data, so otherwise you"ll be encoding it twice.

WSDL snipplet:

$string = "data_you_want_to_send___like_xml_in_soap" ;
$soap_data = array(
"foo" => "bar" ,
//"content" => base64_encode($string) // don"t do this
"content" => $string //do this
);
$response = $client -> Send ($soap_data );
?>

marcovtwout at hotmail dot com

Being new to SOAP, I was searching for a while to find out why my message was getting a response in soapUI, but not with my php code. The specific service I was addressing gives a HTTP 202 Accepted on success (no response), but returns a SOAP message on errors.

Situation:
Using an (authenticated) client connection, and a WDSL file, SOAP calls with type "One-Way" don"t give a response header, even though a response is expected.

Solution:
When calling the client constructor, set SOAP_WAIT_ONE_WAY_CALLS in the $options["features"].

tim at tdinternet dot com

PHP 5.2.11 seems to not be very picky about the correctness of a WSDL.

Other SOAP clients were complaining about schema and namespace issues, while PHP"s SoapClient worked completely fine. Fixing those issues for the other clients however broke PHP"s SoapClient to the point where objects being passed to the SOAP method were becoming empty arrays on the server side.

Lesson learned: some elements were being prefixed with xsd: and others were not -- make absolutely sure your WSDL is correct and consistent (I"m using a tweaked WSDL_Gen.php).

james dot ellis at gmail dot com

I was having troubles getting responses from a Coldfusion SOAP server, with no obvious issues in the SoapClient used.

Eventually I found that the server was only accepting SOAP 1.1 requests and not 1.2. Not sure if this is a system wide Coldfusion setting but if you hit the same wall, try setting the SoapClient option "soap_version" to the constant SOAP_1_1 (which is the default but mine was defaulting to 1.2 as the client was being reused for another service)

ajcartmell at fonant dot com

There seems to be a problem with specifying empty strings for proxy_host and proxy_port options in recent versions of PHP (from a version later than 5.2.9, and equal to or earlier than 5.2.11).

Supplying empty string values for proxy_host and proxy_port causes "host not found" type errors: supplying NULL or FALSE works fine.

bhargav dot khatana at gmail dot com

It took me longer than a week to figure out how to implement WSSE (Web Service Security) headers in native PHP SOAP. There are no much resource available on this, so thought to add this here for community benefit.

Step1: Create two classes to create a structure for WSSE headers

class clsWSSEAuth {
private $Username ;
private $Password ;
function __construct ($username , $password ) {
$this -> Username = $username ;
$this -> Password = $password ;
}
}

Class clsWSSEToken {
private $UsernameToken ;
function __construct ($innerVal ){
$this -> UsernameToken = $innerVal ;
}
}
?>
Step2: Create Soap Variables for UserName and Password

$username = 1111 ;
$password = 1111 ;

//Check with your provider which security name-space they are using.
$strWSSENS = "http://schemas.xmlsoap.org/ws/2002/07/secext " ;

$objSoapVarUser = new SoapVar ($username , XSD_STRING , NULL , $strWSSENS , NULL , $strWSSENS );
$objSoapVarPass = new SoapVar ($password , XSD_STRING , NULL , $strWSSENS , NULL , $strWSSENS );
?>
Step3: Create Object for Auth Class and pass in soap var

$objWSSEAuth = new clsWSSEAuth ($objSoapVarUser , $objSoapVarPass );
?>
Step4: Create SoapVar out of object of Auth class

$objSoapVarWSSEAuth = new SoapVar ($objWSSEAuth , SOAP_ENC_OBJECT , NULL , $strWSSENS , "UsernameToken" , $strWSSENS );
?>
Step5: Create object for Token Class

$objWSSEToken = new clsWSSEToken ($objSoapVarWSSEAuth );
?>
Step6: Create SoapVar out of object of Token class

$objSoapVarWSSEToken = new SoapVar ($objWSSEToken , SOAP_ENC_OBJECT , NULL , $strWSSENS , "UsernameToken" , $strWSSENS );
?>
Step7: Create SoapVar for "Security" node

$objSoapVarHeaderVal =new SoapVar ($objSoapVarWSSEToken , SOAP_ENC_OBJECT , NULL , $strWSSENS , "Security" , $strWSSENS );
?>
Step8: Create header object out of security soapvar

$objSoapVarWSSEHeader = new SoapHeader ($strWSSENS , "Security" , $objSoapVarHeaderVal , true , "http://abce.com " );

//Third parameter here makes "mustUnderstand=1
//Forth parameter generates "actor="http://abce.com ""
?>
Step9: Create object of Soap Client

$objClient = new SoapClient ($WSDL , $arrOptions );
?>
Step10: Set headers for soapclient object

$objClient -> __setSoapHeaders (array($objSoapVarWSSEHeader ));
?>
Step 11: Final call to method

$objResponse = $objClient -> __soapCall ($strMethod , $requestPayloadString );
?>

peter at webacoustics dot com

I found that WSDL fetching fails when using basic authentication in the soapclient. So I implemented the following workaround using wget. I realize wget may not be an option for some environments, in that case cURL would be the next simplest thing.

$wsdl = get_wsdl ("https://example.com/soap/service?wsdl" );
$this -> client = new SoapClient ($wsdl , array("user" => "someuser" , "password" => "somepassword" ));

Private function get_wsdl ($url ) {
global $g ;
$url = escapeshellarg ($url );
$cache_file = "/tmp/soap.wsdl." . md5 ($url );

//only fetch a new wsdl every hour
if(! file_exists ($cache_file ) || filectime ($cache_file ) < time () - 3600 ) {
$agent = escapeshellarg ("--user-agent= { $g [ "useragent" ]} " );
mwexec ("wget --quiet --timeout=5 { $agent } --no-check-certificate --output-document= { $cache_file } { $url } " );
if(! file_exists ($cache_file )) {
throw new Exception ("Couldn"t load WSDL at { $url } " );
}
}
return $cache_file ;
}
?>

meltir at meltir dot com

To those fighting with NTLM authenticated proxy servers, here"s a solution I"m using atm:

/**
* A child of SoapClient with support for ntlm proxy authentication
*
* @author Meltir
*
*/
class NTLM_SoapClient extends SoapClient {

Public function __construct ($wsdl , $options = array()) {
if (empty($options [ "proxy_login" ]) || empty($options [ "proxy_password" ])) throw new Exception ("Login and password required for NTLM authentication!" );
$this -> proxy_login = $options [ "proxy_login" ];
$this -> proxy_password = $options [ "proxy_password" ];
$this -> proxy_host = (empty($options [ "proxy_host" ]) ? "localhost" : $options [ "proxy_host" ]);
$this -> proxy_port = (empty($options [ "proxy_port" ]) ? 8080 : $options [ "proxy_port" ]);
parent :: __construct ($wsdl , $options );
}

/**
* Call a url using curl with ntlm auth
*
* @param string $url
* @param string $data
* @return string
* @throws SoapFault on curl connection error
*/
protected function callCurl ($url , $data ) {
$handle = curl_init ();
curl_setopt ($handle , CURLOPT_HEADER , false );
curl_setopt ($handle , CURLOPT_URL , $url );
curl_setopt ($handle , CURLOPT_FAILONERROR , true );
curl_setopt ($handle , CURLOPT_HTTPHEADER , Array("PHP SOAP-NTLM Client" ));
curl_setopt ($handle , CURLOPT_RETURNTRANSFER , true );
curl_setopt ($handle , CURLOPT_POSTFIELDS , $data );
curl_setopt ($handle , CURLOPT_PROXYUSERPWD , $this -> proxy_login . ":" . $this -> proxy_password );
curl_setopt ($handle , CURLOPT_PROXY , $this -> proxy_host . ":" . $this -> proxy_port );
curl_setopt ($handle , CURLOPT_PROXYAUTH , CURLAUTH_NTLM );
$response = curl_exec ($handle );
if (empty($response )) {
throw new SoapFault ("CURL error: " . curl_error ($handle ), curl_errno ($handle ));
}
curl_close ($handle );
return $response ;
}

Public function __doRequest ($request , $location , $action , $version , $one_way = 0 ) {
return $this -> callCurl ($location , $request );
}

}
?>

Requires curl and could be extended, but it works for my simple needs.

eric dot caron at gmail dot com

Though pointed out by jan at bestbytes, and discussed in bug #27777, one common source of the "Parsing WSDL: Couldn"t find " error is from trying to access a WSDL that is protected by HTTP authentication. Passing the login/password in the 2nd parameter doesn"t always work; so if you encounter this error message and are trying to access a protected WSDL file, try passing the username and password in with the first parameter.

Anonymous

I had to struggle with a rather strange behavior when trying to consume standard Parlay X web services with no success. However, I found a remedy to my problem.

The problem which I faced was about an erroneous invalid HTTP basic authentication request sent to the web service. Although I was sending the right credentials, I was getting an authentication error. It turns out that PHP was sending HTTP requests to another endpoint which is not exposed directly through the web service and that end point does not require authentication.

My remedy for that issue was by using this simple lines in the example of using sendSms Paraly-X method.

First, creating a soap client without any HTTP authentication options:

$client = new SoapClient ($wsdl_url );
?>

The above request will cache the wsdl in the /tmp directory. Immediately after this construction we create another soap client, this time with HTTP authentication options:

try {
$client = new SoapClient ($wsdl_url , array("login" => "griffin" ,
"password" => "password" ));
} catch (Exception $e ) {
printf ("Error:sendSms: %s\n" , $e -> __toString ());
return false ;
}
?>

Now it should work without any problem. Without the second call, PHP will call sendSms without credentials resulting in a failed attempt due to missing authentication information. I found this procedure to be the simplest.

This process should be done every time the cached wsdl expires, or simply a one can increase the time-to-live for the cached wsdl from php.ini

jon dot gilbert at net-entwicklung dot de

Note that creating a soap client for an invalid URL (you do test what happens, when a service is not available, right?) usually throws an exception which can be caught with try..catch. However, if xdebug is active you will get a fatal error, which obviously cannot be caught.

sloloem at gmail dot com

I had an issue figuring out the use of classmap that took me quite a while to figure out. I was assuming the WSDL type the docs were referring to was the name of the element being returned in the SOAP, so like,

And I was wondering why mapping
"classmap"=>array("node"=>"MyNode")

Did nothing.
That"s because in my WSDL I defined node as:

The classmap I needed was:
"classmap"=>array("nodeType"=>"MyNode")

I was able to find the type names using SoapClient->__getTypes()
Later, I realized where I could look inside the WSDL for the typename I needed.

I dunno if I missed something painfully obvious but maybe this can clear up some of the docs.

Jon

We"ve had some problems using SoapClient connecting to an external server via Microsoft ISA (presently v.2006 but this may apply to other versions too). We supply the proxy_host, proxy_port, proxy_login and proxy_password but the ISA server reports the login in its logs as "anonymous".

Our sysadmin believes this is because PHP is not supplying NTLN information (Windows security protocol) in the correct format (and whether it should work with proprietary proxies is of course another debate). We"d tried "username", "DOMAIN\username" to no effect. The solution is to add an exception in the ISA server for the target hostname/IP; null can then be supplied for proxy_login and proxy_password and the connection should then work as expected.

On a slightly related note, if you are having problems make sure the port number is supplied as an integer. Some versions of PHP will not use the proxy with SoapClient if the port number is supplied as a string.

jan at bestbytes dot de

You CAN get a wsdl, if basic authentication is required:

$login = "bert" ;
$password = "berts password" ;

$client = new SoapClient (
"http:// " . urlencode ($login ) . ":" . urlencode ($password ) . "@www.server.com/path/to/wsdl" ,
array(
"login" => $login ,
"password" => $password
)
);

?>

info at nicksilvestro dot net

For anyone having trouble with ArrayOf_xsd_string and getting an error similar to "No deserializer defined for array type {http://www.w3.org/2001/XMLSchema}string "
Try using the "features" param, set to SOAP_USE_XSI_ARRAY_TYPE - this makes sure the correct deserializer is used.

Eg,
$client = new SoapClient ("some.wsdl" , array("features" => SOAP_USE_XSI_ARRAY_TYPE ));
?>

sniper

i was looking for a good example and couldnt find one,
finally found it somewhere(forgot where) i think this is
the best example to make a soap request with multiple params

$params->AWSAccessKeyId = AMAZON_API_KEY;
$params->Request->SearchIndex = "Books";
$params->Request->Keywords = "php5 oop";

$amazon = new SoapClient("http://webservices.amazon.com
/AWSECommerceService/AWSECommerceService.wsdl");
$result = $amazon->itemSearch($params);

alex on reutone comma com

To connect PHP SOAP to MS SOAP (CRM/EXCHANGE/...) I have created some classes using the explanation below and in other places.
www.reutone.com/heb/articles.php?instance_id=62&actions=show&id=521

naugtur at gmail dot com

SoapFault exception: looks like we got no XML document in has been already mentioned to occur when your server outputs something before ... > tag .

For all those having problems with that , and no access to the server code :
This is how to make a proxy that would clean responses for You

php
/**
* Simple class taken from a note by James Ellis
*/
class Proxy_Client extends SoapClient {
protected $cacheDocument = "" ;
public function __construct ($wsdl , $options ) {
parent :: __construct ($wsdl , $options );
}

/**
* SetCacheDocument() sets the previously cached document contents
*/
public function SetCacheDocument ($document ) {
$this -> cacheDocument = $document ;
}

/**
* __doRequest() overrides the standard SoapClient to handle a local request
*/
public function __doRequest () {
return $this -> cacheDocument ;
}
}

//put this code in your function or wherever You have all required variables set

$client = new SoapClient ($wsdl_url , $settings_array );
$void = $client -> $method ($params ); //call this to get response from server

$response_string = $client -> __getLastResponse ();

//this part removes stuff
$start = strpos ($response_string , ");
$end = strrpos ($response_string , ">" );
$response_string = substr ($response_string , $start , $end - $start + 1 );

//get your proxy prepared
$proxy = new Proxy_Client ($wsdl_url , $settings_array );
//and fill it with the server"s response
$proxy -> SetCacheDocument ($response_string );

$and_finally_the_result_is = $proxy -> $method ($params );

print_r ($and_finally_the_result_is ); //this allows You to see what"s there

?>

$method is the method"s name eg. $method="getVersion";
$params - typical params for a soap method

Оценка статьи:
1 звезда2 звезды3 звезды4 звезды5 звезд (Пока оценок нет)
Загрузка...
Поделиться с друзьями:
Похожие публикации