Pusher (Real-time WebSockets)

The artiframe add pusher extension installs the official pusher/pusher-php-server package, allowing you to instantly broadcast backend events to your frontend (React, Vue, Vanilla JS, Mobile) over WebSocket using the src/Service/PusherService.php class. It is indispensable for real-time notification systems, live chat applications, and live graphs.

Mobile Push Notification Note: Pusher relies on an active WebSocket connection. Therefore, it cannot send push notifications to mobile devices that are in sleep mode or when the app is fully closed. For waking up devices, delivering notifications to the notification center, or displaying badges, you must use Firebase Cloud Messaging (FCM) or Apple Push Notification service (APNs).

1. Installation and Configuration

Install the extension into your project via the terminal:

terminal

$ artiframe add pusher

After installation, the required configurations will be appended to your .env file. Fill these out with the information from your Pusher Dashboard:

.env

PUSHER_APP_ID=your_app_id
PUSHER_APP_KEY=your_app_key
PUSHER_APP_SECRET=your_app_secret
PUSHER_APP_CLUSTER=eu

2. Basic Event Broadcasting

You define a Channel and an Event name. The frontend listens to that channel, and the backend fires the event.

OrderController.php

<?php
use Src\Service\PusherService;

$pusher = new PusherService();

// Let's assume a new order just came in.
$orderData = [
    'order_id' => 105,
    'total'    => '250.00 TL',
    'customer' => 'Ali Veli'
];

// 1st Parameter: Channel Name, 2nd Parameter: Event Name, 3rd Parameter: Sent Data (Array)
$pusher->trigger('admin-channel', 'new-order', $orderData);

echo "Notification sent to Admin panel!";

Frontend Side (Javascript) Capture

This is an example showing how you receive the data on the client side (e.g., inside index.html) using pusher-js:

app.js

import Pusher from 'pusher-js';

// Connect using your APP KEY
const pusher = new Pusher('your_app_key', { cluster: 'eu' });

// Subscribe to the channel
const channel = pusher.subscribe('admin-channel');

// Listen for the event
channel.bind('new-order', function(data) {
    alert("New order arrived! ID: " + data.order_id);
    console.log(data);
});

3. Private Channels (Authorization)

If you don't want everyone to listen to your data (e.g., users viewing their own private messages), you use Private Channels. The channel name must begin with private-.

ChatController.php

<?php
// Sending a private message to User ID 15
$pusher->trigger('private-user-15', 'new-message', [
    'sender'  => 'Ahmet',
    'message' => 'Hello, how are you?'
]);

Channel Authorization Process

When the Frontend attempts to subscribe to private-user-15, Pusher sends an authorization request to your backend via an HTTP POST. You authenticate the user and return Pusher's signature.

AuthController.php (POST /pusher/auth)

<?php
use Src\Service\PusherService;

$pusher = new PusherService();

// Socket ID and Channel Name sent by Pusher
$socketId = $_POST['socket_id'];
$channelName = $_POST['channel_name'];

// Verify user's session (e.g., from session or JWT)
$activeUserId = $_SESSION['user_id'] ?? null;

// The user is only authorized to listen to their own channel
if ("private-user-{$activeUserId}" === $channelName) {
    echo $pusher->authenticate($socketId, $channelName);
} else {
    header('', true, 403);
    echo "Forbidden";
}