Twilio (SMS ve Doğrulama API)

artiframe add twilio eklentisi, dünyanın en popüler haberleşme API'si Twilio'yu projenize bağlar. Karmaşık twilio/sdk nesneleri içinde boğulmadan sadece src/Service/TwilioService.php üzerinden tek satır kodla SMS gönderebilir, WhatsApp mesajı atabilir veya 2FA (İki Aşamalı Doğrulama) kodları üretebilirsiniz.

1. Kurulum ve Yapılandırma

Eklentiyi kurmak için terminalinize şu komutu girin:

terminal
$ artiframe add twilio

Kurulumdan sonra Twilio Konsolundan alacağınız bilgileri .env dosyanıza ekleyin:

.env
TWILIO_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=yyyyyyyyyyyyyyyyyyyyyyyyyyyy
TWILIO_FROM_NUMBER=+15551234567

# 2FA (Verify) özelliği kullanacaksanız Verify servis SID numarası
TWILIO_VERIFY_SID=VAzzzzzzzzzzzzzzzzzzzzzzzzzzzz
E.164 Formatı Zorunluluğu: Hem .env dosyasındaki numaranız hem de mesaj atacağınız numaralar daima + ile başlamalı ve ülke kodunu içermelidir (Örn: +905551234567).
2. Temel Mesajlaşma (SMS & WhatsApp)

Servisin en temel görevi olan metin mesajı gönderimi.

example.php
<?php
use Src\Service\TwilioService;

$twilio = new TwilioService();

// 1. Standart SMS Gönderimi
$response = $twilio->sendSms('+905551234567', 'Siparişiniz kargoya verilmiştir.');

if ($response['status'] !== 'error') {
    echo "Mesaj ID: " . $response['sid'];
}

// 2. WhatsApp Üzerinden Gönderim (İşletme Hesabı Onayı Gerekir)
// Twilio arkaplanda numaraların başına 'whatsapp:' ön ekini otomatik koyar.
$twilio->sendWhatsApp('+905551234567', 'Merhaba, bu bir WhatsApp mesajıdır.');
3. İki Faktörlü Doğrulama (2FA - Verify API)

Twilio'nun Verify API servisi sizin yerinize rastgele 6 haneli kodlar üretir, SMS atar, kodu kendi veritabanında (10 dakikalığına) tutar ve kullanıcı girdiğinde "Bu kod doğru mu?" diye size yanıt verir. Sizin hiçbir veritabanı işlemi yapmanıza gerek kalmaz.

Adım 1: Doğrulama Kodu Gönderimi (Start)
AuthController.php
<?php
// Kullanıcı telefon numarasını girip "Kodu Gönder" dediğinde
$response = $twilio->verifyStart('+905551234567', 'sms');

if ($response['status'] === 'pending') {
    echo "Doğrulama kodu SMS ile gönderildi!";
}
2. Parametre olarak sms yerine call yazarsanız kodu telefonla arayıp okur (Voice), email yazarsanız e-posta ile gönderir.
Adım 2: Kodu Kontrol Etme (Check)
AuthController.php
<?php
// Kullanıcı kendisine gelen '123456' kodunu forma girdiğinde:
$userPhone = '+905551234567';
$userCode  = '123456';

$result = $twilio->verifyCheck($userPhone, $userCode);

if ($result['status'] === 'approved') {
    echo "Harika, telefon numaranız doğrulandı!";
    // Oturum açtır (Session)
} else {
    echo "Geçersiz veya süresi dolmuş kod.";
}
4. Toplu SMS ve Raporlama
MetotParametrelerAçıklama
sendBulkSms() array recipients, string message Verdiğiniz bir telefon numarası dizisindeki herkese aynı mesajı sırayla fırlatır. Kaç başarılı (sent), kaç hatalı (failed) dönüşümleri raporlar.
getMessageStatus() string messageSid Gönderilen bir SMS'in o anki durumunu (Örn: sent, delivered, failed) API üzerinden anlık sorgular.
listMessages() int limit = 20 Hesabınızdan gönderilen/alınan son SMS'lerin listesini tarih, numara, ve mesaj özeti ile birlikte dizi olarak getirir.
call() string to, string twimlUrl Hedef numarayı arayıp (Voice Call), belirttiğiniz TwiML XML'ine göre robotik sesle (Text-To-Speech) konuşmasını veya bir IVR (Telesekreter) menüsü başlatmasını sağlar.