PHP SOAP Wstęp
Ostatnio miałem okazję pracować z protokołem komunikacyjnym jakim jest SOAP. Przyznam że jest to dosyć ciężki, przestarzały i nieelastyczny sposób przekazywania danych, lecz z czasem przyzwyczaiłem się i nawet go polubiłem.
Jego plusy, zastosowania, jak i problemy z którymi się spotkałem, przedstawię w tym wpisie.
Czym jest SOAP
Jak już wyżej wspomniałem, jest to protokół komunikacyjny, z tym że wykorzystuje on język XML do przesyłu danych. Jednym z niewielu plusów komunikacji za pomocą SOAP jest bezpieczeństwo, gdyż zazwyczaj używa się certyfikatów w ramach połączenia pomiędzy klientem, a serwerem.
Budowa ciała SOAP – teoria
Elementy, z których składa się ciało dokumentu SOAP można porównać do struktury dokumentu HTML. Składa się on z elementu o nazwie <header> oraz <body>, a to wszystko jest opakowane w elemencie <envelope>.
Graficzne przedstawienie dokumentu SOAP.
Krótko o WSDL (Web Services Description Language)
WSDL to język, który bazuje na XML’u. Służy do definiowania i opisu korzystania z usług Web Serwisów. WSDL daje nam parę rzeczy, bez których SOAP nie zadziała. A mianowicie:
- Opisuje jakie usługi są udostępniane przez Web Serwis.
- Jak wywoływać jego operacje.
- Gdzie znaleźć taki Web Serwis.
Zastosowanie praktyczne
SOAP jest wykorzystywany między innymi do komunikacji z Allegro, używa go również wiele systemów tworzonych na rzecz państwowych jednostek organizacyjnych.
Klasy związane z SOAP dostępne w PHP
W PHP jest dostępnych sześć klas do komunikacji poprzez SOAP. Ich nazwy wraz z krótkim opisem:
- SoapClient – czyli główna klasa, dzięki której możemy połączyć się z serwerem.
- SoapServer – klasa, która pozwoli nam na serwowanie danych. Czyli przeciwieństwo klasy SoapClient.
- SoapFault – jeśli tworzymy własną usługę, czyli korzystamy z SoapServer i będziemy chcieli odesłać klientowi błąd, to właśnie tej klasy użyjemy.
- SoapHeader – ta klasa posłuży do utworzenia nagłówka, o którym wspomniałem nieco wyżej.
- SoapParam – jest używana gdy serwer wymaga przesłania parametrów w operacji, o której za chwilę.
- SoapVar – klasa reprezentacyjna zmienną albo obiekt.
Pozyskanie dostępnych operacji.
Poniżej napisałem krótki przykład pozyskania takowych operacji.
$client = new SoapClient('/folder/nazwa.wsdl', []);
$client->__getFunctions());
Powyższy kod zwróci nam tablicę dostępnych operacji. Jak widać klasa SoapClient przyjmuje dwa parametry.
Pierwszy to adres do pliku WSDL. Drugi parametr to opcje, jak widać parametr może być pusty, lecz przy wysyłaniu zapytań będzie trzeba uzupełnić parę znaczących informacji, które opiszę przy zabawie z certyfikatami.
Wysłanie zapytania, czyli odwołanie się do operacji.
Kiedy już zapoznaliśmy się z dostępnymi operacjami, to odwołajmy się do jednej z nich. Jak to zrobić? Istnieją na to dwa sposoby. Pierwszy z nich to użycie metody __doRequest(). Prosty przykład:
$client = new SoapClient('/folder/nazwa.wsdl', []);
$client->__doRequest($request, $location, $action, $version);
Funkcja ta przyjmuję pięć parametrów, z czego cztery są wymagane. Pierwszym z nich jest ciało xml, czyli treść naszego zapytania. Kolejny parametr to adres url, czyli endpoint. Następnie nazwa operacji, którą otrzymaliśmy z powyższego przykładu. Ostatnim parametrem jest wersja SOAP, w większości przypadków jest to stała zmienna SOAP_1_1.
Drugim przykładem odwołania się do operacji, jest użycie jej nazwy jako funkcji, a mianowicie:
$client = new SoapClient('/folder/nazwa.wsdl', []);
$client->nazwaOperacji([]);
W ten sposób wywołujemy operację, jako parametr przekazujemy tablicę z wymaganymi wartościami po stronie serwera.
Zabawa z certyfikatami
Dotychczas spotkałem się z dwoma sposobami podpinania certyfikatów do dokumentu SOAP. W każdym z tych sposobów potrzebowałem klucza prywatnego certyfikatu, jak i łańcucha publicznego.
Mam certyfikat i co z nim zrobić?
Kiedy otrzymamy od administratora serwera, lub z innego źródła certyfikat, to będzie to plik z rozszerzeniem .p12. Wraz z certyfikatem otrzymujemy, lub sami generujemy hasło do certyfikatu. To właśnie z tego pliku potrzeba wydobyć klucz prywatny oraz łańcuch publiczny.
W tym celu posłużą nam dwie komendy, które trzeba wpisać w terminalu.
Aby wydobyć klucz prywatny należy użyć:
openssl pkcs12 -in (nazwa certyfikatu).p12 -nocerts -out private_cert.pem
Aby wydobyć łańcuch publiczny należy użyć:
openssl pkcs12 -in (nazwa certyfikatu).p12 -clcerts -nokeys -out public_cert.pem
W tym momencie jesteśmy gotowi do połączenia się z serwerem.
Jak podłączyć certyfikat do dokumentu SOAP.
Znam dwa sposoby, które przedstawię i opiszę. Pierwszym sposobem jest łączenie się za pomocą SSL. Czyli będziemy musieli przekazać certyfikat wraz z hasłem w drugim parametrze klasy SoapClient.
Przykład takiego połączenia.
$options = [
'stream_context' => stream_context_create([
'ssl' =&amp;amp;gt; [
'local_cert' => amp;amp;gt; 'łańcuch_publiczny.pem',
'local_pk' => 'klucz_prywatny.pem',
'passphrase' => 'hasło_certyfikatu',
],
]);
];
$client = new SoapClient('/folder/plik.wsdl', $options);
Drugim sposobem, bardziej złożonym, w którym będziemy potrzebowali zainstalować dwie paczki. Pierwsza z nich czyli wse-php, oraz xmlseclib. Przykłady użycia są opisane w dokumentacji paczek, więc tam odsyłam osoby zainteresowane.
Podsumowanie
Osobiście uważam że w obecnych czasach posiadamy dostęp do równie bezpiecznych, jak i elastyczniejszych dla programistów standardów przesyłania danych. Aczkolwiek SOAP jest wykorzystywany w dalszym ciągu w oprogramowaniach. Mam nadzieje że przekazałem w jasny sposób jak działa SOAP i jak go używać.
Zapraszam również do przeczytania wpisu o przydatnych metodach w Laravel Eloquent, o których nie wspomniano w dokumentacji.
O tym jak monitorować własną stronę w sieci, oraz jak działa biblioteka PHP Carbon.
Jeśli masz jakieś pytania skontaktuj się ze mną, poprzez stronę o mnie.