README

PHP SDK untuk mengirim event (publish) ke WebSocket Server melalui HTTP webhook dengan autentikasi HMAC SHA256 Signature.

Cocok untuk

• Backend PHP (Laravel, CodeIgniter, native PHP)
• Trigger event realtime (order, chat, notifikasi)
• Komunikasi server-to-server (backend → WebSocket server)

📦 Instalasi

Install via Composer:

composer require sejator/ws-server-php

Struktur SDK

• Namespace utama: Sejator\WebSocket
• Class publik utama: Sejator\WebSocket\WsServer

Internal: - Signature generator - HTTP client - Payload validator - Exception handler

🚀 Contoh Penggunaan

<?php

require 'vendor/autoload.php';

use Sejator\WebSocket\WsServer;

// Inisialisasi
$ws = new WsServer(
    'APP_KEY',               // App key
    'APP_SECRET',            // App secret
    'https://ws.example.com' // URL WebSocket server
);

// Publish event ke channel
$response = $ws->publish(
    'orders', // nama channel
    'order.created', // nama event
    [
        'order_id' => 123,
        'amount'   => 50000,
        'status'   => 'pending'
    ]
);

print_r($response);

📡 Cara Kerja Publish Event

1️⃣ Payload yang dikirim ke WebSocket server

{
  "channel": "orders",
  "event": "order.created",
  "data": {
    "order_id": 123
  }
}

2️⃣ Signature HMAC SHA256 dibuat otomatis

HMAC_SHA256(APP_KEY.TIMESTAMP, APP_SECRET)

3️⃣ HTTP Request

POST /api/events/{APP_KEY}
Content-Type: application/json
X-Signature: <signature>
X-Timestamp: <unix_timestamp>

4️⃣ Server memverifikasi

• Signature
• Timestamp

🧾 Method Reference

publish

publish(string $channel, string $event, array|string $data): array

❗ Catatan
data harus berupa array atau string.

⚠️ Aturan Channel & Event

Channel

Contoh:

• orders
• private-user-123
• presence-room-general

Event

WAJIB menggunakan titik (.) sebagai pemisah

Contoh valid:

• order.created
• message.sent

Contoh tidak valid:

• order created
• order_created
• ws:order.created

🔗 Implementasi (SDK untuk @sejator/ws-server)

@sejator/ws-server merupakan WebSocket Server yang berfungsi sebagai jembatan komunikasi realtime antara Publisher dan Subscriber.

SDK PHP ini berperan sebagai Publisher, sedangkan
@sejator/ws-client berperan sebagai Subscriber.

Keduanya mengikuti protokol, event, dan format payload yang sama, sehingga:

✨ Keunggulan

• ✅ Plug & Play (tanpa konfigurasi rumit)
• ✅ Auto kompatibel dengan:
  • Channel system
  • Private channel authentication
  • Heartbeat & pong
  • Reconnect strategy

🚫 Batasan

• ❌ Tidak ditujukan untuk WebSocket server lain.

⚠️ PENTING

Pastikan backend WebSocket kamu menggunakan @sejator/ws-server, karena:

• Event internal seperti:
  • connect_success
  • auth_failed
  • pong
  • dll
• Struktur autentikasi:
  APP_KEY:signature
• Endpoint default:
  /ws

Semuanya bergantung pada implementasi server tersebut.

🔄 Arsitektur Publisher ↔ Server ↔ Client

Application Backend (PHP)
        │
        │  sejator/ws-server-php
        │  (publish event)
        ▼
WebSocket Server
        │
        │  @sejator/ws-server
        ▼
Browser / Frontend
        │
        │  @sejator/ws-client
        ▼
Realtime Event Listener

⚙️ Alur Kerja End-to-End

1. Backend PHP mem-publish event menggunakan SDK ini
2. @sejator/ws-server memverifikasi:
   • Signature
   • Timestamp
3. Server meneruskan event ke channel terkait
4. Client (@sejator/ws-client) menerima event secara realtime
5. Event dipetakan langsung ke listener frontend

🔐 Keamanan

• Signature dibuat otomatis menggunakan HMAC SHA256
• WebSocket server memverifikasi:
  • Signature
  • Timestamp

✅ Rekomendasi

• Simpan APP_KEY & APP_SECRET di ENV
• Gunakan HTTPS
• Batasi timestamp drift (±5 menit)