PHP ile Whale-Alert-PHP Kullanarak Blockchain Balina Aktivitesini İzleme

Chain üzerindeki büyük transferler, izleme, analiz ve uyarı iş akışları için değerli olaylardır. Bir ürün, tarihi bir işlemi geri çağırmak, bir blok zincirinin senkronizasyon durumunu incelemek veya yüksek değerli bir transfer gerçekleştiğinde ekibi bildirmek isteyebilir. PHP’de bu ihtiyaçlar, talepleri oluşturmak, yanıtları ayrıştırmak, para birimlerini güvenli bir şekilde işlemek, geçici hataları yeniden denemek ve canlı bir WebSocket bağlantısını sürdürmek gibi tekrar eden bir işe dönüşebilir.

Bu problemin çözümü için whale-alert-php tasarlanmıştır. Bu, Whale Alert Enterprise API için resmi olmayan bir MIT lisanslı PHP istemcisidir ve belgelenmiş REST uç noktaları ile gerçek zamanlı WebSocket uyarıları için kapsama sahiptir. Kütüphane, gevşek bir dizi ve istek yardımcıları sunmak yerine, PHP uygulamaları için yazılımdan bağımsız, türlenmiş ve değişmez bir arayüz sunar.

Önemli: whale-alert-php bağımsız, resmi olmayan bir SDK’dır. Whale Alert ile bağlantılı değildir, onaylanmamıştır veya sponsor edilmemiştir. Kimlik doğrulamalı API işlemleri için geçerli bir API anahtarı gereklidir.

Özel Bir PHP SDK’sının Önemi

Bir dış blok zinciri verisi API’sini entegre etmek, dar anlamda zor değildir: bir HTTP isteği birkaç satırda JSON döndürebilir. Mühendislik çalışması, bu istekte alındıktan sonra başlar. Üretim kodu, token miktarlarını nasıl temsil edeceğini, eksik bir API anahtarını bir oran sınır yanıtından nasıl ayıracağını, sayfalanmış sonuçları güvenli bir şekilde takip edeceğini ve kısa süreli bir ağ veya sağlayıcı hatasından nasıl kurtulacağını belirlemelidir.

whale-alert-php bu endişeleri odaklanmış bir istemciye paketler. Para birimi değerleri ve ücretler, uygulamaların sessiz bir hassasiyet kaybından korunması için kasıtlı olarak dizeler olarak döndürülür. API yanıtları, değişmez DTO’lara eşlenirken, hatalar türlenmiş istisnalar ile ortaya konur. İstemci, PSR-18 uyumlu herhangi bir HTTP uygulamasını kullanabilir ve Laravel uygulamaları, bir hizmet sağlayıcı, yapılandırma yayınlama, bir facade ve bağımlılık enjeksiyonu gibi seçenekleri kullanabilir.

Composer ile Kurulumu

En hızlı yol, standart bir Composer kurulumudur:

composer require tigusigalpa/whale-alert-php

Pakette varsayılan olarak Guzzle kullanılır, ancak PSR-18 tasarımı uygulamanın ihtiyaç duyduğunda başka bir uyumlu HTTP istemcisini değiştirmesine olanak tanır. Bu, mevcut bir HTTP yığını olan veya farklı bir istemci uygulamasına belirli bir tercih duyan ekipler için kullanışlıdır.

REST API ile Başlama

Aşağıdaki örnek, bir istemci oluşturur, kamu statü uç noktasını destekleyen blok zincirlerini listeler, Ethereum senkronizasyon durumunu alır ve bir dizi işlem getirir. Kod, kütüphanenin belgelenmiş API yüzeyine uyar.

use Tigusigalpa\WhaleAlert\Config;
use Tigusigalpa\WhaleAlert\WhaleAlertClient;

$config = new Config(
    apiKey: getenv('WHALE_ALERT_API_KEY'),
    maxRetries: 3,
);

$client = new WhaleAlertClient($config);

// Kamu uç noktası: burada bir API anahtarı gerekmez.
$chains = $client->getSupportedBlockchains();

foreach ($chains as $chain) {
    echo $chain->getName() . ': '.implode(', ', $chain->getSymbols()) . "\n";
}

// Kimlik doğrulamalı uç nokta: geçerli bir API anahtarı sağlayın.
$status = $client->getBlockchainStatus('ethereum');

echo "Ethereum: {$status->getStartHeight()}-{$status->getEndHeight()}\n";

$page = $client->listTransactions('ethereum', [
    'start_height' => $status->getStartHeight(),
    'limit' => 100,
]);

foreach ($page->getTransactions() as $tx) {
    echo "Transaction {$tx->getHash()}\n";
    echo "Fee: {$tx->getFee()} {$tx->getFeeSymbol()}\n";
}

Buradaki önemli detay, çağrıların yalnızca kısa olması değildir. Dönen değerler DTO’lar olup, kodun okuyucuları bir işlem hash’i ve ücretin net bir API sözleşmesinin parçası olduğunu görebilir. Ücret değerleri dizeler olduğu için, uygulama bunları alındığı gibi görüntüleyebilir veya hassas hesaplamalar için bir ondalık-matematik kütüphanesi kullanabilir.

Sayfalamayı Güvenli Bir Varsayılan Haline Getirin

Sayfalama, genellikle basit bir endişe olarak ele alınır, ta ki güvenlik veya güvenilirlik sorunu haline gelene kadar. Liste çağrıları TransactionPage döner ve mevcut işlemleri ile isteğe bağlı bir sonraki URL’yi içerir. Sonraki sayfa mevcut olduğunda, istemci bunu listTransactionsNext() ile takip edebilir. SDK, sonraki URL’leri yapılandırılmış temel kök ile doğrular, bu da bir yanıt içinde döndürülen keyfi bir URL’yi yanlışlıkla takip etmeyi önler. Adres işlem sayfalamaları için de eşdeğer yardımcılar mevcuttur.

if ($page->getNext() !== null) {
            $nextPage = $client->listTransactionsNext($page->getNext());

            foreach ($nextPage->getTransactions() as $tx) {
                echo $tx->getHash() . "\n";
            }
        }

Büyük işlem setlerini işleyen uygulamalar için bu küçük tasarım seçeneği, çağrı kodunu okunaklı tutarken çok önemli bir doğrulama sınırını korur.

Gerçek Zamanlı Uyarıları WebSockets ile Yayınlayın

Polling’in yerleri vardır, ancak gerçek zamanlı bir uyarı ürünü bir sonraki planlı isteği beklememelidir. whale-alert-php, bir uygulamanın bağlanmasını, uyarılara abone olmasını, işleyiciler kaydetmesini ve bir okuma döngüsüne girmesini sağlayan bir WebSocket istemcisi içerir. Otomatik yeniden bağlantı isteğe bağlıdır: maxReconnects değerini sıfırdan büyük bir değere ayarlayarak bu davranışı uygulamanıza uygun hale getirebilirsiniz.

İşte 500,000 USD minimum değeri olan Ethereum uyarılarını dinleyen kısa bir örnek:

use Tigusigalpa\WhaleAlert\WebSocket\AlertSubscription;
use Tigusigalpa\WhaleAlert\WebSocket\Client;
use Tigusigalpa\WhaleAlert\WebSocket\EventType;

$apiKey = getenv('WHALE_ALERT_API_KEY');
$wsUrl = sprintf(
    'wss://leviathan.whale-alert.io/ws?api_key=%s',
    $apiKey,
);

$client = new Client($wsUrl, maxReconnects: 5);

$client->onMessage(function ($message) {
    if ($message->type === EventType::Alert && $message->alert !== null) {
        echo "Blockchain: {$message->alert['blockchain']}\n";
        echo "Alert: {$message->alert['text']}\n";
    }
});

$client->onError(function (\Throwable $exception) {
    fwrite(STDERR, "Connection issue: {$exception->getMessage()}\n");
});

$client->connect();

$client->subscribeAlerts(new AlertSubscription(
    id: 'eth-whale-watch',
    blockchains: ['ethereum'],
    minValueUsd: 500000,
));

$client->listen();

Bu, bir iç operasyon beslemesi, bir Discord veya Telegram bildirim köprüsü, veri alma işçisi veya gerçek zamanlı bir gösterge panosu için yararlı bir temeldir. SDK, WebSocket protokol mekanikleri—bağlantı, abonelik yönetimi, mesaj çözümleme, keep-alives ve isteğe bağlı yeniden bağlantı—konusunda sorumluluğu üstlenir; böylece uygulama, bir uyarı alındığında ne olacağını odaklanabilir.

Hataları Kasıtlı Olarak Yönetme

Güvenilir bir entegrasyon, bir yapılandırma hatasını geçici bir yukarı akış sorusundan ayırt etmeyi kolaylaştırmalıdır. SDK, UnauthorizedException gibi adlandırılmış istisna türlerine API hatalarını eşler; bu, geçersiz veya eksik kimlik bilgileri için, RateLimitException HTTP 429 yanıtları için, NotFoundException, doğrulama hataları ve sunucu tarafı hataları için geçerlidir.

use Tigusigalpa\WhaleAlert\Exceptions\ApiException;
use Tigusigalpa\WhaleAlert\Exceptions\RateLimitException;
use Tigusigalpa\WhaleAlert\Exceptions\UnauthorizedException;

try {
    $status = $client->getBlockchainStatus();
} catch (UnauthorizedException $exception) {
    // WHALE_ALERT_API_KEY kontrol edin.
} catch (RateLimitException $exception) {
    // Sağlayıcının önerdiği yeniden deneme zamanlamasını kullanın.
    $retryAfter = $exception->getRetryAfter();
} catch (ApiException $exception) {
    // Diğer API'ye özgü hataları günlükleyin veya yönetin.
}

Yeniden deneme stratejisi, kasıtlı olarak ihtiyatlıdır. Varsayılan olarak devredışı bırakılır, yalnızca idempotent GET isteklerine uygulanır, oran sınırı ve 5xx yanıtlara yeniden deneme yapar, üstel geri dönüş ile parazit kullanır ve Retry-After başlığını dikkate alabilir. Kütüphane ayrıca hata örneklerinden api_key değerlerini sansürler ve anahtarı kendisi günlüklemez.

Laravel için Doğal Bir Uyum

Laravel projeleri için isteğe bağlı WhaleAlertServiceProvider, bir config/whale-alert.php dosyası yayınlayabilir ve WhaleAlertClient‘i bir singleton olarak kaydedebilir. Geliştiriciler, ya WhaleAlert facade’ını kullanabilir ya da WhaleAlertClient‘i bağımlılık enjeksiyonu ile talep edebilir. Bu, basit bir prototipten sürdürülebilir uygulama koduna temiz bir yol sunar.

use Tigusigalpa\WhaleAlert\WhaleAlertClient;

public function index(WhaleAlertClient $client)
{
    $chains = $client->getSupportedBlockchains();

    return view(
        'chains.index', compact());
}

Proje ayrıca çalıştırılabilir REST ve WebSocket örnekleri ile REST istemcisi, WebSocket istemcisi, DTO’lar ve hata yönetimini kapsayan PHPUnit testleri içerir. Bu kaynaklar, paketi daha geniş bir iş akışına entegre etmeden önce değerlendirmeyi kolaylaştırır.

Blok Zinciri Özelliğini İnşa Edin, Borulama Değil

whale-alert-php, Whale Alert Enterprise API verileri ile çalışmak isteyen PHP ekipleri için tasarlanmıştır; istemci katmanını baştan aşağı inşa etmeden. Sağladığı değer, uygulama kodunun yeniden keşfetmesine gerek olmayan detaylarda yatıyor: PSR-18 esnekliği, değişmez türlenmiş yanıtlar, dize güvenli para birimi alanları, açık hata türleri, kontrollü yeniden denemeler, korumalı sayfalamalar ve gerçek zamanlı WebSocket desteği.

Eğer bir PHP veya Laravel aracı geliştiriyorsanız, blok zinciri transfer olaylarını izleyen, zenginleştiren, görselleştiren veya yönlendiren, SDK’yı yükleyin, örnekleri gözden geçirin ve abonelikleri ve istek akışını kullanım durumunuza göre özelleştirin. Tam README, kaynak kodu ve sürüm bilgileri için GitHub deposunu ziyaret edin.