PHP İle SOAP Web Servisi Oluşturmak (SOAP Server)

Merhaba arkadaşlar,
Bu yazımızda PHP ile basit bir SOAP web servisi nasıl oluşturulur birlikte incelemeye çalışacağız.

SOAP Nedir ve Ne İşe Yarar ? (wiki : tr / en)

SOAP (Simple Object Access Protocol – Basit Nesne Erişim Protokolü) kısaca farklı platformları ve programları haberleştirmek için kullanılan XML alt yapısıyla haberleşen bir web servisidir. Kullanmak zorunda hissetmiyor olabilirsiniz yada ben veriyi kendi protokolümle gönderebilirim de diyebilirsiniz ancak bunu amaç değil araç olarak kullanırsak hem biz hemde müşterilerimiz yararlarını fazlasıyla göreceği gibi ortak dil kullandığınız için çok uzunca bir zaman ayırmak zorunda kalmamış olursunuz.

Nasıl Çalışır ?

Yukarıda bahsettiğimiz gibi XML dilini kullanarak karşı sunucuyla iletişim kurarak çalışmaktadır. Daha detaylı olarak anlatacak olursak karşı sunucudan yapacağınız metod çağırımını ve o metoda göndereceğiniz parametreleri XML diliyle SOAP standardında yazıp karşı sunucuya raw data POST ederek çalışır.

SOAP Server Nedir ?

PHP ‘de SOAP server, gelen SOAP isteklerini karşılayıp belirttiğiniz fonksiyon yada metodlara yönlendiren bir dosyadır.

WSDL Nedir ?

WSDL (Web Services Description Language – Web Servisleri Tanımlama Dili), müşteri/kullanıcılarınızın sisteminiz üzerinden veri çekerken hangi metodları ve hangi parametreleri kullanacağını, hangi parametrelerin zorunlu olduğunu ve parametre tiplerinin ne olduğunu içeren dosyadır. Kısaca müşteri/kullanıcılarınızın için hareket tanımıdır da diyebiliriz.

Kısıtlamalar ?

• PHP5 ve üzeri versiyon kullnıyor olmak
• PHP ayarlarında (php.ini) SOAP uzantısının (extention) etkinleştirilmiş olması

SOAP Server İçin Lokasyon Önerisi ?

Yoğun istek alan wervisler için ayrı bir sunucu önerebiliriz. Ancak normal servisler için şu yazımızda bahsettiğimiz klasör yapısını kullanmanızı önermekle birlikle bu yazımızdada bahsi geçen standartları kullanmaya çalışacağız.

Ayrıca Şu yazımızda bahsettiğimiz PHPDoc standartlarınıda bu yazımızda kullanacağız.

Proje Dosyaları :

lib/
lib/Products.class.php
lib/nusoap.php
mod/
mod/client.php
mod/client_debug.php
client_getAllBooks.php
mod/create_wsdl.php
rpc/
rpc/products.wsdl
rpc/productsService.php

Buradan indirebilirsiniz.

Başlıyoruz

Yazımızda ürünlerimizi web servis aracılığıyla müşteri/kullanıcılarımıza gönderen bir yapı üzerinden gideceğiz. Mevcut yapınızdaki sınıf yada fonksiyonları kullanabileceğiniz gibi mevcut değilse örneğimiz üzerinden yada ihtiyaçlarınız doğrultusunda sınıfınızı oluşturabilirsiniz.

Ürün sınıfımızı yakından tanıyalım:

Sınıf içerisinde daha önce SOAP ile ilgilenmediyseniz size yeni gelebilecek bir şey var oda SoapFault nesnesi. Bu sınıf standart bildiğimiz Exception sınıfını genişletir ve bir çok metodunu devralır. Özelliği ise Soap Server ‘ın bu istisnayı yakalayıp istemciye direkt oarak bu mesajı dönmesidir. İlerleyen sayfalarda bunlara değineceğiz.

Dosya Adı: Products.class.php

Class Adı: Products

Dosya Yolu: lib/

Metodların İmzaları :

• array getAllNotebooks()
  Hiç bir parametre almaz ve tüm notebookları array olarak döndürür.
• string checkNotebookStatus(integer $notebookCode)
  Notebook kodunu parametre olarak alır ve notebook stok durumunu içeren string döndürür (VAR/YOK).
• array getAllBooks()
  Hiç bir parametre almaz ve tüm kitapları array olarak döndürür.
• string checkBookStatus(string $ISBN)
  Kitap ISBN numarasını parametre olarak alır ve kitap stok durumunu içeren string döndürür (VAR/YOK).

Products.class.php dosyası içerisinde stok durumu dönen metodlarda Soap exception örneği için bilerek birer ürün eksik girilmiştir.

Products.class.php dosyasından bir kesit:

<?php

/**
 * Urunlerin listesi, urun detayi ve stok durum kontrolu yapar.
 *
 * @author mustafa.kirimli
 * @version 1.0
 */
class Products {

  /**
   * Tum notebooklari dondurur
   * @return array notebook listesi
   */
  public function getAllNotebooks() {

    $notebooks = array();
    $notebooks[] = array("code" => "123456", "brand" => "ASUS");
    $notebooks[] = array("code" => "123457", "brand" => "LENOVO");
    $notebooks[] = array("code" => "123458", "brand" => "TOSHIBA");

    return $notebooks;
  }

  /**
   * Notebook stok kontrolu yapar.
   * @param integer $notebookCode notebook code
   * @return string notebook urun stok durumu
   */
  public function checkNotebookStatus($notebookCode) {
    $nbStatus = array("123456" => "VAR", "123458" => "YOK");
    if (array_key_exists($notebookCode, $nbStatus)) {
      return $nbStatus[$notebookCode];
    } else {
      throw New SoapFault("Notebook bulunamadı!", 8);
    }
  }
..

WSDL Create İşlemi

WSDL oluşturmak için nusoap kütüphanesini kullanacağız. Piyasada farklı araçlarda mevcut ancak çok tercih edilmesinden dolayı bu araç üzerinden anlatım yapmaya çalışacağız. İlginizi çekebilecek otomatik wsdl oluşturucu aracı olan php2wsdl ‘i de deneyebilirsiniz.

create_wsdl.php dosyası :

<?php

// wsdl cache 'ini devre disi birak
ini_set("soap.wsdl_cache_enabled", "0");

// nusoap dosyasini dahil et
include '../lib/nusoap.php';

// soap_server nesnesi olustur
$server = new soap_server();

// WSDL in ilk parametrelerini ver
$server->configureWSDL('ProductsService', // Servis adi
        'urn:ProductsService', // namespace
        'http://ws.mustafakirimli.com/rpc/productsService.php' // Servis adresi
        );

..

Gerek wsdl oluştururken gerekse SoapServer için geliştirme yaparken en önemli şeyin yukarıdaki koddla bulunan ini_set bölümündeki soap.wsdl_cache_enabled olduğunu söyleyebilirim. Bunu ayarlamadığınızda yada bir şekilde (varsayılan olarak yada elle) true/1 olduğunda wsdl dosyasını yine php ayarı olan soap.wsdl_cache_ttl ‘de ayarlandığı kadar cache den okur. Dolayısıyla sizin wsdl üzerinde yaptığınız değişiklikler test clientınıza çok geç yansıyacağından çok can sıkıcı durumların ortaya çıkması muhtemel olacaktır.

Çalışmalarınız ve testler bittiğinde bu değeri yine 1 olarak ayarlayacak performans kazanabilirsiniz. Çünkü her istekte bulunduğunuzda wsdl dosyasının karşı sunucudan alınıp indirilmesi çok maliyetli olabilir. Hele de çok fazla kullanılan bir SoapClient ise.

include ile başlayan satırda ise nusoap.php dosyamızın bulunduğu yeri gösterip dahil ediyoruz.

Sonraki satırda soap_server nesnemizi olusturuyoruz.

Sonraki satırda ise ($server->configureWSDL….) wsdl icin ilk atamaları yapıyoruz. configureWSDL metodunun ilk uc parametresini ayarlayacağız. İlk parametre olan $serviceName için web servisinin adını yazıyoruz. Biz bu parametre için ProductsService i kullandık. İkinci parametre olan $namespace için ise urn:ProductsService kullandık (Burada ProductsService yazan yere servis adını yazıyoruz). Üçüncü parametre ($endpoint) içinde http://ws.mustafakirimli.com/rpc/productsService.php adresini kullandık. İlk parametre hariç diğerleri isteğe bağlıdır. Kısa bir hatırlatma 3. parametre web servis isteklerini karşılayan dosyadır. Boş geçerseniz bu dosyanın (create_wsdl.php) kendisini kullanır.

Bu aşamadan sonra notebooklar ve kitaplar için ayrı ayrı ComplexType tanımlamaları yapıp (wsdl ‘e eklenmek üzere) metodlarımızı register metodu ile web servisis wsdl ‘imize kaydediyoruz.

Neden ComplexType Tanımlarız ?

ComplexType tanımlamamızın sebebi PHP den yada diğer bir çok dilden bileceğimiz gibi metodlara tamamı array yada bazıları array parametreler göndeririz. SOAP web servisinde array ile data almak (client ‘dan) yada göndermek (server ‘dan) istediğinizde ComplexType kullanırız. Ve web servisi için tanımladığımız metoda input yada output parametresinde “tns:” ile erişim bizim oluşturduğumuz tipi kullanmasını söyleriz.

Örnek ComplexType Tanımı

<?php 

// Notebook tipi tanimla
$server->wsdl->addComplexType(
        'Notebook', // ozel tip adi
        'complexType', // tip
        'struct', // compositor
        'all', // restrictionBase
        '', // elements
        array(
            // 'ozellikAdi' => array('name' => 'ozellikAdi',
            //                       'type' => 'ozellikTipi',
            //                       'minOccurs' => enazKacDefaOlacak,
            //                       maxOccurs => enazFazlaKacDefaOlabilir)
            'code' => array('name' => 'code', 'type' => 'xsd:string'),
            'brand' => array('name' => 'brand', 'type' => 'xsd:string')
        )
);

..

Yukarıdaki örneğimizi inceleyecek olursak; Notebook tipi tanımladık ve array (dizi) ‘in içereceği key (anahtar) ‘leri (code ve brand) tek tek tipleriyle tanımladığımızı görebilirsiniz. xsd yerleşik tip demektir. Bir ComplexType başka bir ComplexType ‘a bağlı olabilir yine tns ile).

Metod ‘un Array Tipinde Sonuç Dönmesi İçin Gereken ComplexType

<?php

// NotebookList tipi tanimla
$server->wsdl->addComplexType(
        'NotebookList', // ozel tip adi
        'complexType', // tip
        'struct', // compositor
        'all', // restrictionBase
        '', // elements
        array(
            // 'ozellikAdi' => array('name' => 'ozellikAdi',
            //                       'type' => 'ozellikTipi',
            //                       'minOccurs' => enazKacDefaOlacak,
            //                       maxOccurs => enazFazlaKacDefaOlabilir)
            'Notebook' => array('name' => 'Notebook',
                                'type' => 'tns:Notebook',
                                'minOccurs' => '0',
                                'maxOccurs' => 'unbounded')
        )
);

..

Yukarıdaki tanım bir öncekinden yapı olarak farksızdır. Kullanıldığı yer aşağıdaki (getAllNotebooks) metodunun dönüş tipi parametresidir (NotebookList). Yani döndüreceği değerleri belirler.

Tanım parametrelerinde tns ile bir öncekli Notebook ComplexType ‘ına göndermede bulunur. Yani kısaca bu “ComplexType” tanımı/nesnesi getAllNotebooks metodunun Notebook tipinde birden çok değer dönebileceği (maxOccurrs = unbounded) anlamına gelmektedir. JAVA ile ilgilenenler için (her ne kadar JAVA ile web servisi oluşturmak yeni dosya oluşturmaktan çok farklı olmasada) buradaki NotebookList tipi ArrayList ‘e karşılık gelmektedir.

Web Servisi İçin Metod Tanımlama

Web servisi için metod tanımlamayı register metodu ile yapıyoruz. Söz dizimi biraz karışık gibi görünsede PHP ve benzer (syntax olarak) dillerden çokta farklı değildir. Metodun adını verirsiniz, giriş parametreleri ve çıkış parametrelerini verirsiniz. Bir kaç ek özellikle birlikte SOAP ta da aynen böyle yapıyoruz.

Örnek Web Servisi Metodu

<?php

// getAllNotebooks metodunu web servisi icin tanimla
$server->register('getAllNotebooks', // metod adi
        array(), // giris parametreleri
        array('return' => 'tns:NotebookList'), // cikis parametreleri
        'urn:ProductsService', // namespace
        'urn:ProductsService#getAllNotebooks', // soapaction
        'rpc', // style
        'encoded', // use
        'Tum notebooklari dondurur'                      // dokuman
);

..

Yukarıdaki örnekte getAllNotebooks metodunu tanımladık. Metod parametre almadığı için boş bir array yazılmış durumda. Ayrıca metod NotebookList (dosyada ComplexType olarak tanımlanmış hali mevcuttur) tipinde (tns ile yazarak yerleşik tip olduğunu söyleriz) bir parametre döndüreceğini tanımlamış bulunuyoruz.

WSDL Tanımını Oluşturmak ve Dosyaya Yazmak

<?php

// Servisi baslat
$HTTP_RAW_POST_DATA = isset($HTTP_RAW_POST_DATA) ? $HTTP_RAW_POST_DATA : '';
$server->service($HTTP_RAW_POST_DATA);

// parametre olarak print geldiyse WSDL dosyasi olustur
if ($_GET["print"] == true) {
  // bu sayfayi WSDL dosyasini gosterecek bicimde ac ve ciktisini al
  $data = file_get_contents("http://ws.mustafakirimli.com/mod/create_wsdl.php?wsdl");
  // alinan ciktiyi wsd dosyasina yaz
  file_put_contents("../rpc/products.wsdl", $data);
}

..

Yukarıdaki kod ise servisi (sadece wsdl oluşturmak için) başlatır. Bu dosyayı tarayıcınızdan http://ws.mustafakirimli.com/mod/create_wsdl.php?wsdl olarak çalıştırırsanız WSDL i ekrana basacaktır. İsterseniz çıkan WSDL tanımını kaynağını görüntüle diyerek wsdl dosyanıza kaydedebilirsiniz.

Ayrıca yukarıdaki dosyayı direkt olarak çalıştırırsanız WSDL özetini ve metodlar hakkında bilgiler veren ekranları görebilirsiniz. Aşağıda örneklerini vermeye çalıştık.

Metod Listesi Ekranı | Metod Detayları Ekranı

Bu dosya (create_wsdl.php) aslında bir web servisi olarak çalışabilir ancak biz bu dosyayı sadece WSDL dosyasını oluşturmak için kullanacağız. Çünkü servis olarak PHP5 ‘in yerleşik SOAP Server özelliğini (ram ‘den tasaffur için) kullanacağız.

Dosyanın en altındaki kısım ise (yukarıda da mevcut) dosyayı wsdl ‘i gösterecek bir biçimde açıp wsdl dosyasına yazmayı sizin yerinize yapar. Özellikte servisi ilk geliştirmeye başladığınızda çok deneme ve eklemeler olduğu zaman çok işe yarayacağını düşündüğüm için işinizi kolaylaştırması adına ekledim. Bir not: file_get_contents(“http://w .. diye devam eden kısmı &print=true olarak değiştirirseniz işlem hiç bitmeye bilir. Çünkü sistem sonsuz döngüye (kısır döngü) girecektir.

SOAP Server ‘i Çalıştırmak

Bu projenin en çok sevilen yanı bu dosyadır. Çünkü gerçekten anlatması çok kolay ve en az kod içeren koddur. Ayrıca karmaşık anlatımları sevmediğimizden (önceki okuyucularımızın kullanıcıların görüşüne bağlıdır) ama bu yazıda yer yer yüzeysel bilgiler, bazen de karmaşık anlatımlar yaptığımızdan bu dosya üzerinde biraz daha durabiliriz.

Tabi ki diğerleri hakkında başka bir şey yazmak istediğimiz anlamı çıkmamalı zira gerçekten derinlemesine bir konu olduğundan sıkıntılarını yada yapmak istediklerini bildiren (yorumla olabilir) okuyucularımız için detaylandırmaya ve cevaplamaya çalışacağız.

SOAP Server Dosyamız

<?php

// wsdl cache 'ini devre disi birak
ini_set("soap.wsdl_cache_enabled", "0");

// web servisi icin kullanacagimiz metodlari iceren sinifi dahil et
require_once '../lib/Products.class.php';

// Soap Server nesnesi olustur
$soapServer = new SoapServer("products.wsdl", array('encoding' => 'UTF-8'));

// Soap Server 'a Products sinifini kullanmasini soyle
$soapServer->setClass("Products");

// Soap Server 'i baslat ve gelen istekleri Products sinifina gonder
$soapServer->handle();
?>

Dosyamız wsdl cach ‘ini devre dışı bırakarak başlıyor (Bu ayarıda product/live ortamınızda 1 olarak ayarlayabilirsiniz). Daha sonra web servisimizin kullanacağı metodları içeren sınıfı dahil ediyoruz. Biz sınıf kullanmayı tercih ettik ancak elinizde fonksiyonlar varsa bunları dahil edip setClass yerine tum fonksiyonlarımız için ayrı ayrı $soapServer->addFunction(fonksiyonAdi) kullanarak bunları dahil edebilirsiniz.

Sonrasında PHP5 ile yerleşik olarak gelen SoapServer nesnemizi olusturup parametre olarak bir onceki sayfamızda olusturdugumuz WSDL dosyamızı veriyoruz (varsa kendi WSDL dosyanızıda verebilirsiniz). Son olarak setClass ile sınıfımızı SoapServer ‘a kaydettirdikten sonra handle diyerek servisimizi başlatıyoruz ve hayırlı olsun diyoruz.

Bir sonraki yazımızda PHP ile SOAP client ‘ı inceleyip bu olusturduğumuz Soap server ‘a istekte bulunacağız. İncelemek isteyen arkadaşlar için client.php dosyası projemiz içinde mevcuttur.