PWA ve Web Push Bildirim Sistemi

Bu Proje Nedir?

Web push, ilk bakışta "bir istek at, bildirim gitsin" gibi görünür. Gerçekte üç ayrı parçanın uyum içinde çalışması gerekir ve üçü de tarayıcı tarafından zorunlu kılınmıştır:

1. Service worker — sayfadan bağımsız çalışan bir betik. Bildirimi gösteren odur; sekme kapalıyken bile ayaktadır.
2. VAPID imzası — push servisi (Google, Mozilla, Apple) size ait olmayan bir sunucudur ve "bu isteği gerçekten o site mi yolladı?" diye sorar. Cevabı ES256 ile imzalanmış bir JWT verir.
3. Uçtan uca şifreleme — push servisi mesajın içeriğini okuyamaz. İçerik, tarayıcının abonelikte verdiği anahtarlarla şifrelenir; sunucu ile tarayıcı arasında araya giren servis yalnızca şifreli baytları taşır.

Çoğu PHP örneği bu üçünü composer require minishlink/web-push ile geçiştirir. Bu proje hiçbir kütüphane kullanmadan yazıyor: WebPush sınıfı VAPID JWT'sini üretip ES256 ile imzalar, ECDH anahtar değişimini ve HKDF türetmesini yapar, içeriği aes128gcm (RFC 8188) ile şifreler ve isteği kendisi gönderir.

Sonuç: nasıl çalıştığını gerçekten görebileceğiniz, üretime hazır ve bağımlılıksız bir uygulama — üstelik çevrimdışı çalışan bir PWA kabuğuyla birlikte.

Kimler için uygun?

• Sitesine bildirim eklemek isteyip "FCM SDK'sı olmadan olur mu?" diye soranlar
• VAPID'in ne olduğunu ve neden gerektiğini öğrenmek isteyenler
• Web push şifrelemesinin adım adım nasıl yapıldığını görmek isteyenler
• Uygulamasını PWA'ya çevirip ana ekrana eklenebilir hâle getirecekler
• Bootstrap 5 üzerine kurulu, tekrar kullanılabilir bir panel kalıbı arayanlar

Bu proje, Çılgın Yazılım Kütüphanesi altında yayınlanan açıklamalı, üretime hazır örneklerden biridir.

---

Bir bildirimin yolculuğu

 ABONE OLMA (bir kez)
 ────────────────────
 Tarayıcı                          Sunucu (PHP)
    │  "Bildirimleri aç"              │
    │  Notification.requestPermission()│
    │                                  │
    │  pushManager.subscribe({          │
    │    applicationServerKey: VAPID_PUBLIC })
    │        │                          │
    │        ▼                          │
    │   PUSH SERVİSİ (Google/Mozilla/Apple)
    │        │                          │
    │   endpoint + p256dh + auth        │
    │        │                          │
    │        └──── POST /api/push/subscribe ──►  push_subscriptions
    │                                            (kullanıcıya bağlı)

 GÖNDERME (her seferinde)
 ────────────────────────
 Sunucu (PHP)                                    Tarayıcı
    │
    │ 1) VAPID JWT üret: {aud, exp, sub}
    │    ES256 ile imzala (P-256 özel anahtar)
    │
    │ 2) İçeriği ŞİFRELE (aes128gcm / RFC 8188)
    │    - geçici ECDH anahtar çifti üret
    │    - abonenin p256dh'si ile ortak sır türet
    │    - HKDF ile içerik anahtarı + nonce
    │    - AES-128-GCM ile şifrele
    │
    │ 3) POST <endpoint>
    │    Authorization: vapid t=<jwt>, k=<public>
    │    Content-Encoding: aes128gcm
    │    TTL: 86400
    │              │
    │              ▼
    │        PUSH SERVİSİ  ── içeriği OKUYAMAZ, sadece taşır
    │              │
    │              ▼
    │     service-worker.js  'push' olayı
    │              │  event.data.json()
    │              ▼
    │     showNotification(title, {body, icon, data})
    │              │
    │              ▼  kullanıcı tıklar
    │     'notificationclick' → açık sekme varsa ÖNE GETİR,
    │                           yoksa yeni sekme aç
    │
    └── Yanıt 404/410 ise → failures++ (ölü abonelik ayıklanır)

---

Kritik Kararlar

1. Hiçbir push kütüphanesi kullanılmadı

web-push-php iyi bir kütüphanedir ve üretimde kullanmakta hiçbir sakınca yoktur. Ama bu proje öğretmek için yazıldı: kütüphane çağrısı, VAPID'in ne olduğunu ve şifrelemenin neden gerektiğini gizler.

app/Core/WebPush.php işi baştan sona yapar:

Bu, PHP'nin openssl eklentisi dışında hiçbir şey gerektirmez.

2. aes128gcm — eski aesgcm değil

Web push'un iki şifreleme biçimi vardır. Eski aesgcm, tuz ve geçici anahtarı ayrı başlıklarda (Encryption, Crypto-Key) taşır ve uygulaması hem karmaşık hem hataya açıktır.

aes128gcm (RFC 8188) ikisini de gövdenin içine koyar. Sonuç: daha az başlık, daha az yanlış yapma ihtimali. Bütün güncel tarayıcılar destekler.

'Content-Encoding: aes128gcm',

3. VAPID özel anahtarı .env'de değil, dosyada

Açık anahtar .env içinde durur — zaten JavaScript'e gönderilir, gizli değildir.

Özel anahtar ise PEM dosyası olarak storage/vapid.pem içinde tutulur ve o klasör web'e kapalıdır. Sebep: PEM çok satırlıdır ve .env biçimi tek satır bekler; sıkıştırmaya çalışmak sessiz bozulmalara yol açar.

Anahtar çiftini kaybederseniz bütün abonelikler geçersiz olur — abonelikler açık anahtara bağlıdır. Kullanıcılar yeniden izin vermek zorunda kalır. storage/vapid.pem dosyasını yedekleyin.

4. Bildirim yalnızca giriş yapan kullanıcının kendi cihazlarına gider

// Abonelikler kullanıcıya bağlıdır; gönderim de öyle.
WHERE user_id = :id

"Herkese gönder" düğmesi bilerek yoktur. Bir demo uygulamasında herkese bildirim gönderebilen bir düğme, ilk ziyaretçinin oyuncağı olurdu.

Kendi projenizde toplu gönderim yaparken sırayla değil, kuyrukla gönderin: 10.000 aboneye tek istekte gönderim yapmaya çalışmak PHP'nin zaman aşımına takılmasıyla biter.

5. Ölü abonelik ile geçici hata ayrı ele alınır

Kullanıcı tarayıcı verilerini temizlerse veya uygulamayı kaldırırsa abonelik geçersiz olur ama sunucu bunu ancak gönderim denediğinde öğrenir. Push servisinin yanıt kodu ikisini birbirinden ayırır:

// app/Http/Controllers/Api/PushApiController.php
if (in_array($result['status'], [404, 410], true)) {
    $repository->deleteByEndpoint($subscription['endpoint']);  // kesin ölüm
} else {
    $repository->markFailure($subscription['endpoint']);        // geçici olabilir
}

404 / 410 kesin ölümdür: push servisi "böyle bir adres yok" diyor. Satır hemen silinir; beklemenin bir anlamı yoktur.

Diğer hata kodları (500, ağ zaman aşımı) geçici olabilir. Bunlarda satır silinmez, yalnızca failures sayacı artar. Tek bir geçici hata yüzünden çalışan bir aboneliği atmak, kullanıcıyı sessizce bildirimsiz bırakırdı.

Abonelik yeniden kaydedildiğinde sayaç sıfırlanır — ON DUPLICATE KEY UPDATE ... failures = 0.

6. Service worker fetch olayında gezinme ile varlık isteğini ayırır

Her isteği önbelleğe almak cazip görünür ama tehlikelidir: eski bir JavaScript dosyası önbellekte kalırsa uygulama açıklanamaz biçimde bozulur.

Bu yüzden service worker yalnızca gezinme isteklerinde (request.mode === 'navigate') devreye girer: ağ varsa ağdan, yoksa offline.html'den yanıt verir. Diğer istekler doğrudan ağa gider.

7. notificationclick yeni sekme açmaz — var olanı öne getirir

clients.matchAll({ type: 'window', includeUncontrolled: true })

Bildirime her tıklandığında yeni sekme açan bir uygulama, gün sonunda 14 sekme bırakır. Açık bir sekme varsa focus() edilir; yoksa yenisi açılır.

8. Manifest start_url olarak dashboard verir

Ana ekrana eklenen uygulama açıldığında giriş sayfasını değil, panele gider. Oturum yoksa uygulama zaten girişe yönlendirir; ama oturum varsa kullanıcı doğrudan işine başlar.

---

Neler Var?

Web Push (saf PHP)

• VAPID JWT üretimi ve ES256 imzası
• DER → ham imza dönüşümü
• ECDH ortak sır + HKDF anahtar türetme
• aes128gcm (RFC 8188) içerik şifreleme
• TTL, Content-Encoding ve Authorization: vapid başlıkları
• 404/410'da silme, geçici hatada sayaç
• Anahtar üretici CLI (bin/vapid-keys.php)

PWA kabuğu

• service-worker.js — install · activate · fetch · push · notificationclick · pushsubscriptionchange
• manifest.webmanifest — ana ekrana eklenebilir
• offline.html — ağ yokken gezinme yanıtı

Panel

• Bildirimleri aç / kapat (izin akışıyla)
• Kendi cihazlarına test bildirimi gönderme
• Kayıtlı cihazlar: ad, kullanıcı, push servisi, hata sayacı
• PWA kurulum durumu kartı (worker · manifest · VAPID · çevrimdışı)

Ortak altyapı

• Oturum girişi, "beni hatırla", hız sınırı, CSRF
• CSP, X-Frame-Options: DENY, nosniff
• Açık / koyu tema, hesaba kayıtlı
• Mobilde alt navigasyon, yatay kaydırma yok
• Kullanıcılar sayfasında canlı filtre (JS kapalıysa da çalışır)
• Sıfır bağımlılık

---

Service Worker

Service worker, sayfadan bağımsız çalışan bir betiktir. Sekme kapalıyken bile tarayıcı onu uyandırıp bir olay verebilir — push bildiriminin sekme kapalıyken gelmesinin sebebi budur.

Altı olay dinlenir:

Kapsam (scope) kuralı: service worker yalnızca kendi klasörü ve altındaki adresleri kontrol edebilir. Bu yüzden service-worker.js proje kökündedir; assets/js/ altına koysaydınız yalnızca o klasörü kontrol ederdi ve gezinme isteklerini hiç göremezdi.

Güncelleme: tarayıcı dosyayı bayt bayt karşılaştırır. Tek bir karakter değişirse yeni sürümü kurar. Bu yüzden dosyanın başındaki önbellek sürüm adını (var CACHE = 'cy-pwa-v1') her değişiklikte artırın; activate olayı eskileri temizler.

---

VAPID anahtarı üretmek

VAPID, "bu bildirimi gerçekten o site gönderdi" diyebilmek için kullanılan bir anahtar çiftidir. Bir kez üretilir ve değişmez.

php bin/vapid-keys.php

Betik P-256 (prime256v1) eğrisinde bir ECDSA çifti üretir:

• Özel anahtar → storage/vapid.pem (web'e kapalı klasör)
• Açık anahtar → ekrana yazılır; .env içindeki VAPID_PUBLIC_KEY satırına yapıştırın

VAPID_PUBLIC_KEY=BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQ...
VAPID_SUBJECT=mailto:[email protected]

VAPID_SUBJECT bir mailto: veya https: adresidir; push servisi bir sorun olduğunda kime ulaşacağını buradan öğrenir.

Windows/XAMPP'ta openssl.cnf bulunamıyor hatası alırsanız betik gerekli seçenekleri WebPush::keygenOptions() üzerinden zaten veriyor; yine de sorun sürerse php.ini içindeki openssl.cafile ve OPENSSL_CONF ortam değişkenini kontrol edin.

Anahtarı değiştirmeyin. Abonelikler açık anahtara bağlıdır; değiştirirseniz mevcut bütün abonelikler geçersiz olur ve kullanıcılar yeniden izin vermek zorunda kalır.

---

Güvenlik: Neyi, Nasıl Kapattık?

---

Yapılandırma

APP_DEBUG=true          # silerseniz: yerelde açık, canlıda kapalı
APP_URL=
APP_PRETTY_URLS=true

DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=cy_pwa_push
DB_USER=root
DB_PASS=

# --- WEB PUSH (VAPID) ---
VAPID_PUBLIC_KEY=       # bin/vapid-keys.php çıktısı
VAPID_SUBJECT=mailto:[email protected]

Özel anahtar .env'de değildir; storage/vapid.pem dosyasındadır.

---

Dosya Yapısı

pwa-push-notification-system/
│
├── index.php                     Ön denetleyici — TEK giriş noktası
├── service-worker.js             ★ KÖKTE olmalı (kapsam kuralı)
├── manifest.webmanifest          Ana ekrana ekleme künyesi
├── offline.html                  Ağ yokken gösterilen sayfa
├── database.sql                  Şema + 51 kullanıcı + 4 örnek abonelik
├── .env.example
│
├── bin/
│   ├── vapid-keys.php            ★ P-256 anahtar çifti üretici (CLI)
│   └── .htaccess                 Web erişimine kapalı
│
├── storage/
│   ├── vapid.pem                 ★ VAPID ÖZEL ANAHTARI — web'e kapalı
│   └── .htaccess
│
├── app/
│   ├── Core/
│   │   ├── WebPush.php           ★ VAPID JWT · ECDH · HKDF · aes128gcm · gönderim
│   │   ├── Auth.php · Session.php · Csrf.php · RateLimiter.php
│   │   ├── Database.php          PDO (EMULATE_PREPARES = false)
│   │   ├── Env.php               .env okuyucu + isLocalHost()
│   │   └── ...
│   │
│   ├── Http/Controllers/         Auth · Dashboard · Push · User · Api
│   ├── Repositories/PushSubscriptionRepository.php
│   └── Support/helpers.php
│
├── views/                        Düzenler, push sayfası
├── assets/                       css · js (push izin akışı) · images
├── config/config.php
├── routes/web.php
└── docs/screenshots/

---

Veritabanı Şeması

push_subscriptions

---

SSS

HTTPS olmadan çalışır mı?

Hayır — localhost dışında çalışmaz ve bu bir tercih değil, tarayıcı kuralıdır.

Service worker ve push API'si güvenli bağlam ister. Sebebi açıktır: service worker sitenizin bütün isteklerini görebilir; araya giren biri onu enjekte edebilseydi tam kontrolü ele geçirirdi.

Geliştirme için localhost yeterlidir. Yerel ağdaki bir telefondan denemek isterseniz ngrok gibi bir tünel veya kendi imzaladığınız bir sertifika kullanın.

iOS'ta çalışıyor mu?

Evet, iOS 16.4 ve sonrasında — ama bir şartla: kullanıcının uygulamayı önce ana ekrana eklemesi gerekir. Safari sekmesinde açık dururken push izni istenemez.

Bu yüzden manifest ve "ana ekrana ekle" akışı yalnızca bir süs değil, iOS'ta push'un ön koşuludur.

Bildirim gitmiyor, hata da yok

Sırayla kontrol edin:

1. HTTPS mi? (localhost hariç)
2. Tarayıcı izni verilmiş mi? Adres çubuğundaki kilit simgesinden bakın; bir kez reddedildiyse sayfa bir daha soramaz, izni elle açmanız gerekir.
3. .env içinde VAPID_PUBLIC_KEY dolu mu? Kontrol panelindeki kart size söyler.
4. storage/vapid.pem dosyası var mı ve PHP onu okuyabiliyor mu?
5. İşletim sistemi düzeyinde bildirimler kapalı olabilir (Windows'ta "Odak yardımı", macOS'ta "Rahatsız etmeyin").

Toplu bildirim nasıl gönderirim?

Döngüyle değil, kuyrukla. 10.000 aboneye tek istekte gönderim yapmaya çalışmak PHP'nin zaman aşımına takılmasıyla biter ve yarısı gitmiş, yarısı gitmemiş bir gönderim bırakır.

Doğru kalıp: her abonelik için kuyruğa bir iş bırakın, worker'lar paralel göndersin. Kuyruk örneği için İş Kuyruğu ve Worker Sistemi'ne bakın.

Neden web-push-php kullanmadınız?

Üretimde kullanabilirsiniz, iyi bir kütüphanedir. Ama bu proje VAPID'in ve şifrelemenin nasıl çalıştığını göstermek için yazıldı; tek satırlık bir kütüphane çağrısı bunu gizlerdi.

WebPush.php 471 satırdır ve her adımı yorumlarla açıklar. Okuduktan sonra kütüphaneye geçmek isterseniz, artık onun ne yaptığını biliyor olacaksınız.

Service worker'ı güncelledim ama eski sürüm çalışıyor

Tarayıcı yeni service worker'ı kurar ama eski sürüm hâlâ bir sekmeyi kontrol ediyorsa beklemeye alır.

Geliştirme sırasında: DevTools → Application → Service Workers → "Update on reload" işaretleyin veya "Unregister" deyip sayfayı yenileyin.

Üretimde: CACHE değerini her sürümde artırın (cy-pwa-v2 …); activate olayı eski önbellekleri temizler.

---

Canlı Ortama Alırken

• [ ] HTTPS zorunlu olsun — push ve service worker bunsuz çalışmaz
• [ ] .env içinde APP_DEBUG=false (veya satırı tümüyle silin)
• [ ] VAPID_PUBLIC_KEY dolu, storage/vapid.pem yerinde
• [ ] storage/vapid.pem dosyasını yedekleyin — kaybederseniz tüm abonelikler geçersiz olur
• [ ] storage/ ve bin/ klasörlerinin web'den erişilemediğini doğrulayın (403)
• [ ] service-worker.js proje kökünde mi?
• [ ] manifest.webmanifest içindeki start_url ve simgeler doğru mu?
• [ ] VAPID_SUBJECT gerçek bir iletişim adresi olsun
• [ ] Toplu gönderim yapacaksanız kuyruk kullanın
• [ ] Demo hesaplarının parolalarını değiştirin veya hesapları silin

---

Sorun Giderme

---

Yol Haritası

• [ ] Bildirim eylem düğmeleri (actions) örneği
• [ ] Toplu gönderim için kuyruk entegrasyonu
• [ ] Gönderim geçmişi tablosu (kime, ne zaman, sonuç)
• [ ] Konu bazlı abonelik (topic) desteği
• [ ] Urgency başlığı desteği ve panelden seçilebilmesi

---

Katkı

Hata bildirimi ve öneriler için issue açabilirsiniz.

Lisans

MIT — ticari projelerinizde de özgürce kullanabilirsiniz.

---