Laravel Fast2SMS v2.0.0 — WhatsApp Desteği, Bildirim Kanalları ve Daha Akıllı Kullanıcı Deneyimi

Hedef, Laravel üzerinden Hindistan telefon numaralarına SMS göndermekti ve bunu ham API dizileriyle uğraşmadan gerçekleştirmekti. v2.0.0 bu fikri daha ileriye taşıyor.

Ana başlık WhatsApp Business API desteği — metin, resimler, belgeler, konumlar, şablonlar, tepkiler, çıkartmalar ve etkileşimli mesajlar, hepsi tanıdık Fast2sms fasadından. Bunun ötesinde v2, drop-in Laravel Notification Channels, tipli istisna hiyerarşisi, etkileyici test araçları ve üretimde cüzdanınızı koruyan maliyet tasarrufu sağlayan korumalar getiriyor.

⚠️ Bu, önemli bir sürüm ve kırıcı değişiklikler içeriyor. Güncellemeden önce Güncelleme Kılavuzu‘na göz atın.

💬 WhatsApp Business API

Bu büyük bir yenilik. v2.0.0’dan itibaren, paket Fast2sms::whatsapp() ile Fast2SMS WhatsApp Business API desteği sunuyor.

Basit bir metin mesajı gönderme:

use Shakil\Fast2sms\Facades\Fast2sms;

Fast2sms::whatsapp()
    ->to('9999999999')
    ->text()
    ->send();

Bir resim ile birlikte başlık gönderme:

Fast2sms::whatsapp()
    ->to()
    ->image(, caption: )
    ->send();

Bir belge gönderme:

Fast2sms::whatsapp()
    ->to()
    ->document(, filename: )
    ->send();

Bir konum gönderme:

Fast2sms::whatsapp()
    ->to()
    ->location(lat: 28.6139, lng: 77.2090, name: )
    ->send();

Bir kayıtlı şablon gönderme:

Fast2sms::whatsapp()
    ->to()
    ->template(id: , variables: [, ])
    ->send();

Bir mesaja tepki verme, bir çıkartma gönderme veya etkileşimli buton akışları oluşturma — tam WhatsApp API yüzeyi, aynı akıcı zincir üzerinden mevcuttur.

🔔 Laravel Notification Channels

v2, iki drop-in bildirim kanalı ile geliyor: SmsChannel ve WhatsAppChannel. Mevcut bildirim sınıflarınız tam olarak beklediğiniz gibi çalışır.

use Shakil\Fast2sms\Channels\SmsChannel;
use Shakil\Fast2sms\Channels\WhatsAppChannel;
use Shakil\Fast2sms\Messages\SmsMessage;
use Shakil\Fast2sms\Messages\WhatsAppMessage;

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        return [SmsChannel::class, WhatsAppChannel::class];
    }

    public function toFast2sms($notifiable): SmsMessage
    {
        return SmsMessage::create()
            ->otp();
    }

    public function toWhatsApp($notifiable): WhatsAppMessage
    {
        return WhatsAppMessage::create()
            ->text();
    }
}

Routing yöntemlerini User modelinize ekleyin ve işte hepsi hazır:

public function routeNotificationForFast2sms(): string
{
    return $this->phone_number;
}

public function routeNotificationForWhatsapp(): string
{
    return $this->phone_number;
}

Hiçbir fasad yok, manuel numara geçişi yok. Sadece idiomatik Laravel.

🧱 Typed Exception Hierarchy

v1’de, her API hatası tek bir Fast2smsException fırlatıyordu. v2’de tam olarak ihtiyacınız olanı yakalayabilirsiniz:

use Shakil\Fast2sms\Exceptions\AuthenticationException;
use Shakil\Fast2sms\Exceptions\RateLimitException;
use Shakil\Fast2sms\Exceptions\InsufficientBalanceException;
use Shakil\Fast2sms\Exceptions\NetworkException;

try {
    Fast2sms::otp(, );
} catch (InsufficientBalanceException $e) {
    // Ekibinize haber verin — cüzdan boş
} catch (RateLimitException $e) {
    // Geri adım atın ve yeniden deneyin
} catch (AuthenticationException $e) {
    // API anahtarı yanlış ya da süresi dolmuş
} catch (NetworkException $e) {
    // Fast2SMS erişilemez durumda
}

Tipli istisnaların tam listesi değişiklik günlüğü‘nde mevcuttur.

🧪 Rich Fake Assertions for Testing

v2, okunan ve okunabilir hale getirilmiş 16 doğrulama yöntemi sunuyor:

Fast2sms::fake();

// ... kodunuzu tetikleyin ...

Fast2sms::assertSmsSentTo();

Fast2sms::assertSmsSentTo(, fn ($sms) =>
    str_contains$sms->message, )
);

Fast2sms::assertWhatsAppSentTo();

Fast2sms::assertNothingSent();

// Gerçek gönderim gerektiren sınavlar için temizlik yapın
Fast2sms::stopFaking();

💡 Fluent Message Builders with Credit Helpers

SmsMessage ve WhatsAppMessage birinci sınıf nesnelerdir ve adlandırılmış oluşturucular ve zincirleme ayarlayıcılarla birlikte gelir. SmsMessage, göndermeden önce maliyeti tahmin edebilmeniz için kredi yardımcılarıyla birlikte gelmektedir:

use Shakil\Fast2sms\Messages\SmsMessage;

$message = SmsMessage::create()
    ->withContent()
    ->withRoute(SmsRoute::QUICK);

$message->charCount();       // karakter sayısı
$message->isUnicode();       // Unicode kodlamasının gerekli olup olmadığını kontrol edin
$message->creditCount();     // bu SMS'lerin tüketeceği kredi
$message->exceedsOneSms();   // birden fazla SMS'ten uzun olup olmadığını kontrol edin

Uzun bir mesajın 1 kredi mi yoksa 3 kredi mi maliyetine sebep olacağını tahmin etme derdi yok.

🛡️ Cost-Saving Guards

v2, üretimde cüzdanınızı koruyan birkaç isteğe bağlı koruma getiriyor. Hepsi varsayılan olarak kapalıdır — sadece ihtiyaç duyduğunuzı config/fast2sms.php‘de etkinleştirin:

⚙️ Yeni Artisan Komutları

# Paket tarafından tetiklenen her olayı listeler, açıklamalar ile
php artisan fast2sms:events

# Tam otokomple için bir IDE yardımcı dosyası oluşturur
php artisan fast2sms:ide-helper

fast2sms:ide-helper komutunu yükledikten sonra bir kez çalıştırın ve PhpStorm veya VS Code’de her fasad yönteminin tam otokomple özelliğine sahip olun.

🚀 Başlarken

Gereksinimler: PHP ^8.3 (8.4 ve 8.5 de test edildi), Laravel 11, 12 veya 13.

composer require itxshakil/laravel-fast2sms

php artisan vendor:publish --tag=fast2sms-config

FAST2SMS_API_KEY="your-api-key"
FAST2SMS_DEFAULT_SENDER_ID="FSTSMS"
FAST2SMS_DEFAULT_ROUTE="dlt"

v1’den Güncelleme

Halka açık gönderim API’si — Fast2sms::quick(), ::dlt(), ::otp() ve artık ::viaWhatsApp() — tamamen aynı şekilde kalmıştır. Çoğu v1 kodu değişiklik olmadan çalışacaktır.

Kırıcı değişiklikler içsel yapıdadır: istisna türleri, DTO’lar ve dönüş türü ipuçları. Tam adım adım geçiş kılavuzu UPGRADING.md‘de mevcuttur.

Bağlantılar

Eğer bu yazı size zaman kazandırdıysa, GitHub’da bir yıldız vermek diğer Laravel geliştiricilerinin paketi bulmasına yardımcı olur.

Yazar: Shakil Alam — Laravel geliştirici, açık kaynak katkıda bulunan.