Php İle Guzzle Kütüphanesi Kullanarak Harici Api Bağlantısı Nasıl Yapılır?

PHP ile Guzzle Kütüphanesi Kullanarak Harici API Bağlantısı Nasıl Yapılır?

Modern web uygulamaları, verilerini zenginleştirmek ve iş süreçlerini otomatize etmek için sıklıkla harici servislerle haberleşir. PHP dünyasında bu işlem için en standart, güvenilir ve esnek çözüm Guzzle HTTP istemcisidir. Guzzle, basit bir HTTP isteğinden karmaşık asenkron işlemlere kadar geniş bir yelpazede, geliştiricilere temiz ve okunabilir bir arayüz sunar.

Bu rehberde, PHP ile Guzzle kütüphanesi kullanarak harici API bağlantısı nasıl yapılır, adım adım öğreneceğiz. Eğer bir REST API'ye veri göndermek veya veri çekmek istiyorsanız, Guzzle'ın sunduğu metodolojiler iş akışınızı büyük ölçüde hızlandıracaktır. Bu makale, temel kurulumdan hata yönetimine kadar profesyonel bir geliştiricinin ihtiyaç duyacağı tüm teknik detayları içermektedir.

Gereksinimler ve Ön Hazırlık

Guzzle kütüphanesini projenize dahil etmek için sisteminizde PHP 8.1 veya üzeri bir sürümün yüklü olması önerilir. Ayrıca, PHP'nin paket yöneticisi olan Composer kurulumunun tamamlanmış olması şarttır. Guzzle, modern PHP standartlarını (PSR-7 ve PSR-18) tam destekler.

Projenizin kök dizininde terminali açarak aşağıdaki komutla kütüphaneyi yükleyebilirsiniz:

composer require guzzlehttp/guzzle

Kurulum tamamlandıktan sonra, projenizin dizininde vendor klasörü ve composer.json dosyası oluşacaktır. PHP kodlarınızın en üstüne require 'vendor/autoload.php'; satırını ekleyerek Guzzle sınıflarını projenize dahil etmeye hazır hale gelirsiniz.

Guzzle ile Temel GET İsteği Nasıl Yapılır?

Bir API'den veri çekmek için en yaygın kullanılan yöntem GET isteğidir. Guzzle, Client sınıfı üzerinden bu işlemi oldukça basit hale getirir. Aşağıdaki örnekte, halka açık bir JSONPlaceholder API'sine nasıl bağlanacağımızı görelim.

require 'vendor/autoload.php';

use GuzzleHttp\Client;

$client = new Client(['base_uri' => 'https://jsonplaceholder.typicode.com/']);

$response = $client->request('GET', 'posts/1');

echo $response->getBody();

Burada base_uri parametresi, isteklerimizin temel adresini belirler. request metodu ise HTTP fiilini ve ilgili endpoint'i (uç noktayı) alır. getBody() metodu ise API'den dönen ham veriyi döndürür.

POST İsteği ile Veri Gönderme

Harici bir servise veri gönderirken genellikle POST metodu kullanılır. API'ler genellikle veriyi json formatında bekler. Guzzle, json anahtarını kullanarak veriyi otomatik olarak JSON formatına dönüştürür ve uygun başlıkları (headers) ayarlar.

$client = new Client();

$response = $client->post('https://jsonplaceholder.typicode.com/posts', [
    'json' => [
        'title' => 'Yeni Makale Başlığı',
        'body'  => 'Bu içerik Guzzle ile gönderildi.',
        'userId'=> 1
    ]
]);

echo "Durum Kodu: " . $response->getStatusCode();

Bu örnekte, json dizisi içerisine gönderdiğimiz veriler, Guzzle tarafından uygun formatta API'ye iletilir. getStatusCode() metodu, isteğin başarılı olup olmadığını (genellikle 201 Created) kontrol etmemizi sağlar.

Hata Yönetimi ve Exception Kullanımı

Gerçek dünya uygulamalarında API'ler her zaman yanıt vermeyebilir veya hatalı istekler oluşabilir. Guzzle, 4xx ve 5xx hatalarında RequestException fırlatır. Bu hataları yakalamak, uygulamanızın çökmesini engeller.

use GuzzleHttp\Exception\RequestException;

try {
    $response = $client->request('GET', 'https://gecersiz-url.com');
} catch (RequestException $e) {
    if ($e->hasResponse()) {
        echo "Hata Mesajı: " . $e->getResponse()->getStatusCode();
    }
}

try-catch bloğu, ağ bağlantı hatalarını veya sunucu taraflı hataları yönetmek için kritik bir güvenlik önlemidir. hasResponse() metodu, hatanın sunucudan bir yanıt alıp almadığımızı doğrular.

Guzzle İsteklerinde Header ve Yetkilendirme

Birçok API, erişim için API anahtarı (API Key) veya Bearer Token gerektirir. Bu bilgiler istek başlıklarına (headers) eklenmelidir. Aşağıdaki örnekte, bir yetkilendirme başlığının nasıl ekleneceğini inceleyelim.

$client = new Client();

$response = $client->request('GET', 'https://api.ornek.com/data', [
    'headers' => [
        'Authorization' => 'Bearer YOUR_ACCESS_TOKEN',
        'Accept'        => 'application/json',
    ]
]);

headers dizisi, API sağlayıcısının talep ettiği tüm özel başlıkları eklemenize olanak tanır. Güvenlik açısından, bu tokenları asla doğrudan kod içine yazmayın; .env dosyaları veya güvenli bir yapılandırma dosyası kullanın.

Guzzle İstek Yöntemlerinin Karşılaştırılması

Guzzle kullanırken farklı ihtiyaçlara göre farklı yöntemler tercih edilebilir. Aşağıdaki tablo, yaygın kullanım senaryolarını özetlemektedir.

Kritik Güvenlik Uyarısı: API anahtarlarınızı ve gizli tokenlarınızı asla sürüm kontrol sistemlerine (Git gibi) göndermeyin. Bu verileri sunucu ortamında tanımlanmış çevre değişkenlerinde (environment variables) saklayın. Ayrıca, harici API'lerden gelen verileri her zaman doğrulamadan (sanitization) doğrudan veritabanına kaydetmeyin.

Sıkça Sorulan Sorular

Guzzle neden file_get_contents'ten daha iyidir?

file_get_contents basit istekler için kullanılabilir ancak hata yönetimi, timeout ayarları, header yönetimi ve asenkron istekler gibi profesyonel ihtiyaçlarda yetersiz kalır. Guzzle, bu süreçleri PSR standartlarına uygun şekilde yönetir.

Guzzle isteklerinde timeout nasıl ayarlanır?

İstek yapılandırmasına 'timeout' => 5.0 parametresini ekleyerek, isteğin 5 saniye içinde yanıt gelmezse zaman aşımına uğramasını sağlayabilirsiniz.

API'den gelen JSON verisini nasıl diziye çevirebilirim?

json_decode($response->getBody(), true); fonksiyonunu kullanarak gelen JSON verisini kolayca bir PHP dizisine dönüştürebilirsiniz.

Guzzle ile aynı anda birden fazla istek atabilir miyim?

Evet, Guzzle'ın Pool veya Promise yapısını kullanarak asenkron (eşzamansız) istekler atabilir ve performansınızı ciddi oranda artırabilirsiniz.

Localhost'ta SSL hatası alıyorum, ne yapmalıyım?

Geliştirme ortamında SSL sertifikası sorunları yaşıyorsanız, geçici olarak 'verify' => false parametresini ekleyebilirsiniz ancak bunu asla canlı sunucuda yapmayın.

Guzzle ile İstekleri İzleme ve Hata Ayıklama (Debugging)

Geliştirme sürecinde API'den dönen yanıtları veya gönderilen isteklerin içeriğini tam olarak görmek, hataları tespit etmek için kritiktir. Guzzle, isteklerinizi izlemenizi sağlayan debug seçeneği ve History middleware yapısı ile güçlü araçlar sunar.

Debug Modu ile İstekleri İnceleme

İsteklerinizi doğrudan terminale veya bir dosyaya yazdırmak için debug parametresini kullanabilirsiniz. Bu, özellikle karmaşık header yapılarını veya hatalı gövde verilerini ayıklarken hayat kurtarıcıdır.

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.ornek.com/veri', [
    'debug' => true
]);

Middleware ile İstek Geçmişini Kaydetme

Daha profesyonel bir yaklaşım için History middleware kullanarak tüm istek ve yanıtları bir diziye kaydedebilir ve daha sonra loglayabilirsiniz.

use GuzzleHttp\Client;
use GuzzleHttp\HandlerStack;
use GuzzleHttp\Middleware;

$container = [];
$history = Middleware::history($container);
$stack = HandlerStack::create();
$stack->push($history);

$client = new Client(['handler' => $stack]);

$client->get('https://api.ornek.com/test');

foreach ($container as $transaction) {
    echo $transaction['request']->getMethod();
    echo $transaction['response']->getStatusCode();
}

Guzzle İsteklerinde Performans Optimizasyonu

Büyük ölçekli uygulamalarda API istekleri, sistemin genel yanıt süresini doğrudan etkiler. Performansı artırmak için bağlantı havuzlarını yönetmek ve asenkron istekleri doğru kullanmak gerekir.

Asenkron İstekler (Promises)

Eğer aynı anda birden fazla API'ye bağlanmanız gerekiyorsa, senkron (sıralı) istekler yerine asenkron istekleri tercih etmelisiniz. Bu yöntem, bir isteğin yanıtını beklemeden diğerini başlatmanıza olanak tanır.

use GuzzleHttp\Client;

$client = new Client();

$promises = [
    'kullanici' => $client->getAsync('https://api.ornek.com/user/1'),
    'siparis'   => $client->getAsync('https://api.ornek.com/orders/1'),
];

$results = \GuzzleHttp\Promise\Utils::unwrap($promises);

echo $results['kullanici']->getBody();
echo $results['siparis']->getBody();

Bağlantı Havuzu (Connection Pooling)

Sürekli aynı API'ye istek atıyorsanız, her seferinde yeni bir TCP bağlantısı kurmak yerine curl seçeneklerini kullanarak bağlantıyı açık tutabilirsiniz (Keep-Alive). Bu, özellikle yüksek trafikli sistemlerde milisaniyelik ciddi kazançlar sağlar.

$client = new \GuzzleHttp\Client([
    'curl' => [
        CURLOPT_TCP_KEEPALIVE => 1,
        CURLOPT_TCP_KEEPIDLE => 120
    ]
]);

İpucu: API isteklerinizde performans darboğazı yaşıyorsanız, yanıtları Redis veya Memcached gibi bir önbellek (caching) katmanında saklayarak API'ye olan toplam istek sayınızı azaltmayı mutlaka değerlendirin.

Sonuç

PHP ile Guzzle kütüphanesini kullanmak, harici API bağlantılarını yönetmenin en profesyonel yoludur. Bu rehberde kurulumdan başlayarak, temel istek türlerini, hata yönetimini ve güvenlik önlemlerini adım adım ele aldık. Guzzle'ın sunduğu esneklik, projelerinizin ölçeklenebilirliğini artıracak ve dış servislerle olan iletişiminizi çok daha kararlı hale getirecektir.

Bir sonraki adım olarak, Guzzle'ın Middleware (ara katman) yapısını inceleyerek isteklerinize otomatik loglama veya yeniden deneme (retry) mekanizmaları eklemeyi deneyebilirsiniz. İyi kodlamalar!