Pusher (Gerçek Zamanlı İletişim / WebSockets)

artiframe add pusher eklentisi, projenize saniyeler içinde "Realtime" (gerçek zamanlı) yeteneği kazandırır. Kullanıcı sayfayı yenilemeden ekranda bildirim göstermek, canlı sohbet (chat) yapmak veya bir borsadaki anlık fiyat değişimlerini ekrana yansıtmak istiyorsanız Pusher sizin için biçilmiş kaftandır.

Pusher Aslında Nasıl Çalışır? (Kavramsal Bakış)

Normal web sitelerinde kullanıcı bir butona basar, PHP'ye (Backend) istek gider ve sayfa yenilenir. Pusher ise tarayıcı ile Pusher sunucuları arasında sürekli açık kalan bir tünel (WebSocket) kurar.

Senaryo şudur:

1. Kullanıcının tarayıcısındaki (Frontend) JavaScript kodu, Pusher'ın "odalarından" (Channel) birine, örneğin chat-oda-1 isimli odaya bağlanır ve dinlemeye başlar.
2. Sizin PHP kodunuz (Backend) ArtiFrame PusherService'i kullanarak chat-oda-1 odasına "yeni-mesaj" isminde bir olay (Event) ateşler (Broadcast/Trigger).
3. PHP'nin ateşlediği bu veriyi Pusher anında yakalar ve o odayı dinleyen tüm tarayıcılara saniyenin onda biri sürede iletir. Kullanıcının ekranında mesaj anında belirir!

Önemli Ayrım: Push Notifications vs WebSockets
Pusher (Channels), uygulama veya web sitesi "açıkken" (ekrandayken) anlık veri iletimi sağlar. Eğer kullanıcının mobil uygulaması kapalıysa veya uyku modundaysa Pusher ile telefona kilit ekranı bildirimi (Push Notification) gönderemezsiniz! Arka planda uyuyan cihazları uyandırmak ve bildirim atmak için WebSocket değil, işletim sistemi seviyesinde çalışan Firebase Cloud Messaging (FCM) veya Apple Push Notification Service (APNs) servislerini kullanmanız gerekir.
1. Kurulum ve Yapılandırma

Eklentiyi kurmak için terminalinize şu komutu girin:

terminal
$ artiframe add pusher

Pusher.com üzerinden ücretsiz bir hesap açıp "App" oluşturduğunuzda size verilen anahtarları .env dosyasına girmelisiniz:

.env
PUSHER_APP_ID=1234567
PUSHER_APP_KEY=xxxxx_key_xxxxx
PUSHER_APP_SECRET=xxxxx_secret_xxxxx
PUSHER_CLUSTER=eu
2. Temel Olay Ateşlemek (Broadcast Event)

PHP tarafında (örneğin bir sipariş Controller'ında) bir eylem gerçekleştiğinde bunu Pusher üzerinden fırlatırsınız.

OrderController.php
<?php
use Src\Service\PusherService;

$pusher = new PusherService();

// Veritabanına sipariş kaydedildi...
$siparisData = ['id' => 99, 'fiyat' => '500 TL', 'musteri' => 'Ahmet'];

// 1. Parametre: Kanal Adı (Oda)
// 2. Parametre: Olay Adı (Event)
// 3. Parametre: Gönderilecek Veri (Array otomatik JSON'a çevrilir)
$pusher->broadcast('genel-bildirimler', 'yeni-siparis-geldi', $siparisData);
Bu kod çalıştığı anda frontend tarafında genel-bildirimler kanalını dinleyen bir JavaScript (pusher-js) varsa, kendisine JSON objesi düşer ve ekrana "Yeni Sipariş!" pop-up'ı çıkartabilir.
3. Güvenli Odalar (Private & Presence Channels) ve Auth

Herkesin "chat-oda-1" kanalını dinlemesini istemeyebilirsiniz (Aksi takdirde başkalarının gizli mesajlarını okuyabilirler). Pusher, adının başında private- veya presence- olan kanalları Güvenli Kanal sayar ve Frontend bunları dinlemek istediğinde Pusher önce sizin PHP sunucunuza dönüp "Bu adamın bu odaya girmeye yetkisi var mı?" diye sorar.

İşte bu soruya yanıt vermek (yetkilendirmek) için auth() metodu kullanılır.

AuthController.php (Pusher Webhook / API Endpoint)
<?php
use Src\Service\PusherService;

// Frontend (JS) private bir kanala bağlanmak istediğinde Pusher otomatik bu PHP rotanıza istek atar.
$pusher = new PusherService();

$channelName = $_POST['channel_name']; // Örn: private-chat-55
$socketId    = $_POST['socket_id'];    // Kullanıcının anlık tarayıcı ID'si

// Kendi veritabanınızda kontrol ediyorsunuz: Bu adamın odaya yetkisi var mı?
if ($currentUser->canAccessChat(55)) {
    // Evet yetkisi var, Pusher'a onay damgasını (Auth Token) döndür!
    echo $pusher->auth($channelName, $socketId);
    exit;
}

// Yetkisi yoksa 403 HTTP kodu basıyoruz.
header('', true, 403);
echo "Forbidden";
Presence Kanalı (Kimler Çevrimiçi?)

Kanal adının başında presence- varsa, bu odaya bağlanan herkes birbirini görebilir (Örn: "Ahmet yazıyor...", "Odadakiler: Ali, Ayşe"). Bunun için auth() yerine presenceAuth() kullanılır.

example.php
<?php
// Odaya girecek kullanıcının verilerini de gönderiyoruz ki diğerleri onu görebilsin
echo $pusher->presenceAuth(
    $channelName, 
    $socketId, 
    'user_99', // Benzersiz Kullanıcı ID'si
    ['name' => 'Ahmet', 'avatar' => 'ahmet.jpg'] // Diğerlerinin göreceği profil detayı
);
4. Gelişmiş Özellikler ve Bilgi Sorgulama
MetotParametrelerAçıklama
broadcastToMany() array channels, string event, array data Aynı veriyi 100 farklı kanala tek seferde fırlatır (Örn: Gruplara toplu mesaj).
toUser() string userId, string event, array data Kanal ismi düşünmeden doğrudan belirlediğiniz bir User ID'ye mesaj fırlatır. Pusher'ın yeni özel bir yeteneğidir.
channelInfo() string channel Siz PHP tarafındayken, channelInfo('private-chat-5') diyerek o an o odada birileri var mı (occupied) veya kaç kişi var (user_count) görebilirsiniz.
channels() string prefix = '' Şu anda aktif (içinde biri olan) tüm kanalların listesini dizi olarak çeker.