Real-Time WordPress Data Synchronization with WebSockets

Real-time WordPress features work best when WordPress remains the authority for permissions and durable state while a dedicated message service handles persistent connections. Authenticate channel access, publish small invalidation events, and let clients refetch authoritative records instead of treating a socket message as truth.

1. The Limitations of the WordPress Heartbeat API vs. WebSockets

The core WordPress Heartbeat API was introduced in WordPress 3.6 to provide a unified communication pulse between the client browser and the server. It batches data into an interval-based HTTP POST request sent to /wp-admin/admin-ajax.php with the action heartbeat. Although simple to implement via action hooks, this approach suffers from major structural architectural constraints:

• HTTP Request-Response Overhead: Every single heartbeat check transmits HTTP headers, cookies, authentication tokens, and user agent strings, introducing 1 KB to 3 KB of network overhead per request even when zero new notifications exist on the server.
• Full PHP Stack Bootstrap: Each AJAX request triggers a full WordPress lifecycle execution, including database connection initialization, option loading, plugin boot phases, and user authentication checks, consuming significant CPU time.
• Inherent Polling Latency: Because intervals typically range between 15 seconds (focused window) and 120 seconds (unfocused background tab), critical notifications such as failed payment webhooks, high-priority customer chats, or security lockout events are delayed by up to two minutes.
• Database Connection Pressure: When dozens of administrators or store managers keep dashboard tabs open simultaneously, short-polling creates a constant baseline of database read queries that interfere with customer-facing transactions.

2. Enterprise System Architecture: Decoupled Redis Pub/Sub Gateway

A frequent mistake when adding WebSockets to WordPress is trying to run a long-running WebSocket daemon directly inside standard PHP-FPM workers. PHP-FPM is designed for short-lived, synchronous request-response execution; holding thousands of long-lived connections inside PHP-FPM quickly exhausts worker pools and starves web traffic.

The enterprise-grade architecture separates responsibilities into three distinct layers:

1. WordPress Application Layer (PHP 8.3): WordPress hooks (e.g., woocommerce_new_order, post_updated, user_register) publish event payloads directly into an in-memory Redis channel using a non-blocking Redis client. This operation takes less than 1 millisecond and allows PHP execution to terminate immediately.
2. WebSocket Gateway Service (Node.js / Go / Rust): A lightweight, asynchronous event gateway subscribes to the Redis notification channels. It maintains persistent WebSocket connections with connected admin browser sessions, authenticates incoming socket handshakes, and routes messages to specific users or role groups.
3. Browser Client Layer (JavaScript): When an administrator logs into WP Admin, a lightweight JavaScript client negotiates a secure WebSocket connection to the gateway using an HMAC session token, listens for incoming events, and dynamically updates UI elements without full page reloads.

3. WordPress Event Publisher: Secure Redis Broadcaster (PHP 8.3)

Let us implement the PHP 8.3 event publisher service. We will create a strict-typed class that generates secure authentication tickets, validates user roles, and dispatches events into Redis.

<?php
declare(strict_types=1);

namespace WPStack\WebSockets\Publisher;

use Redis;
use RedisException;
use RuntimeException;
use WP_User;

final class NotificationPublisherService
{
    private const REDIS_CHANNEL = 'wpstack_admin_notifications';
    private const TOKEN_TRANSIENT_PREFIX = 'wpstack_ws_token_';
    private const TOKEN_EXPIRATION_SECONDS = 300; // 5 minute handshake window

    private ?Redis $redisClient = null;

    public function __construct(
        private readonly string $redisHost = '127.0.0.1',
        private readonly int $redisPort = 6379,
        private readonly ?string $redisPassword = null,
        private readonly string $secretKey = AUTH_KEY
    ) {}

    /**
     * Initializes and returns the persistent Redis connection.
     *
     * @throws RuntimeException If Redis connection fails.
     */
    private function getRedisConnection(): Redis
    {
        if ($this->redisClient instanceof Redis && $this->redisClient->isConnected()) {
            return $this->redisClient;
        }

        try {
            $client = new Redis();
            $connected = $client->pconnect($this->redisHost, $this->redisPort, 1.5);

            if (!$connected) {
                throw new RuntimeException("Unable to connect to Redis server at {$this->redisHost}:{$this->redisPort}");
            }

            if ($this->redisPassword !== null && $this->redisPassword !== '') {
                $authenticated = $client->auth($this->redisPassword);
                if (!$authenticated) {
                    throw new RuntimeException("Redis authentication failed on notification gateway.");
                }
            }

            $this->redisClient = $client;
            return $this->redisClient;
        } catch (RedisException $e) {
            throw new RuntimeException("Redis connection error: " . $e->getMessage(), (int) $e->getCode(), $e);
        }
    }

    /**
     * Generates a short-lived, cryptographically secure ticket for WebSocket handshakes.
     */
    public function generateHandshakeTicket(int $userId): string
    {
        $user = get_userdata($userId);
        if (!$user instanceof WP_User) {
            throw new RuntimeException("Invalid user ID {$userId} provided for WebSocket ticket generation.");
        }

        $timestamp = time();
        $randomBytes = bin2hex(random_bytes(16));
        $roles = (array) $user->roles;
        $payload = sprintf('%d|%d|%s|%s', $userId, $timestamp, implode(',', $roles), $randomBytes);
        $signature = hash_hmac('sha256', $payload, $this->secretKey);
        $ticket = base64_encode($payload . '|' . $signature);

        set_transient(self::TOKEN_TRANSIENT_PREFIX . $userId, $ticket, self::TOKEN_EXPIRATION_SECONDS);

        return $ticket;
    }

    /**
     * Publishes a structured notification event to the Redis bus.
     *
     * @param string $eventType Category of the notification (e.g. 'order.new', 'security.alert')
     * @param string $title High-level notification title
     * @param string $message Detailed body content
     * @param string $severity 'info' | 'warning' | 'error' | 'success'
     * @param array $meta Additional metadata payload
     * @param array $targetRoles Roles permitted to receive this notification
     * @param int|null $targetUserId Optional specific user ID restriction
     */
    public function broadcast(
        string $eventType,
        string $title,
        string $message,
        string $severity = 'info',
        array $meta = [],
        array $targetRoles = ['administrator', 'shop_manager'],
        ?int $targetUserId = null
    ): bool {
        $eventData = [
            'id'             => wp_generate_uuid4(),
            'event_type'     => sanitize_key($eventType),
            'title'          => sanitize_text_field($title),
            'message'        => wp_kses_post($message),
            'severity'       => in_array($severity, ['info', 'warning', 'error', 'success'], true) ? $severity : 'info',
            'meta'           => $meta,
            'target_roles'   => array_map('sanitize_key', $targetRoles),
            'target_user_id' => $targetUserId,
            'timestamp'      => time(),
            'source_site'    => get_site_url(),
        ];

        $jsonPayload = wp_json_encode($eventData);
        if ($jsonPayload === false) {
            return false;
        }

        try {
            $redis = $this->getRedisConnection();
            $subscribers = $redis->publish(self::REDIS_CHANNEL, $jsonPayload);
            return $subscribers > 0;
        } catch (RuntimeException | RedisException $e) {
            error_log(sprintf('[WPStack WebSockets] Failed to publish event %s: %s', $eventType, $e->getMessage()));
            return false;
        }
    }
}

4. Event Hooks Integration: Intercepting WordPress & WooCommerce Actions

To demonstrate real-time notifications in action, we hook into core WordPress events and high-priority WooCommerce lifecycle actions. The following integration subscriber registers event listeners for security alerts, new WooCommerce orders, and theme/plugin updates.

<?php
declare(strict_types=1);

namespace WPStack\WebSockets\Integration;

use WPStack\WebSockets\Publisher\NotificationPublisherService;
use WC_Order;

final class WordPressEventSubscriber
{
    public function __construct(
        private readonly NotificationPublisherService $publisher
    ) {}

    public function registerHooks(): void
    {
        // WooCommerce New Order Alert
        add_action('woocommerce_new_order', [$this, 'handleNewWooCommerceOrder'], 10, 2);

        // Security: Failed Login Attempts
        add_action('wp_login_failed', [$this, 'handleFailedLoginAttempt'], 10, 1);

        // Plugin Activation/Deactivation Notice
        add_action('activated_plugin', [$this, 'handlePluginActivated'], 10, 2);

        // REST API Handshake Endpoint Registration
        add_action('rest_api_init', [$this, 'registerRestEndpoints']);

        // Admin Asset Enqueue
        add_action('admin_enqueue_scripts', [$this, 'enqueueAdminClientAssets']);
    }

    public function handleNewWooCommerceOrder(int $orderId, ?WC_Order $order = null): void
    {
        if (!$order instanceof WC_Order) {
            $order = wc_get_order($orderId);
        }

        if (!$order instanceof WC_Order) {
            return;
        }

        $totalFormatted = html_entity_decode(strip_tags($order->get_formatted_order_total()));
        $customerName = trim($order->get_billing_first_name() . ' ' . $order->get_billing_last_name());
        $itemCount = $order->get_item_count();

        $this->publisher->broadcast(
            eventType: 'order.created',
            title: sprintf('New Order #%d Received', $orderId),
            message: sprintf('%s placed an order for %d items total %s.', $customerName ?: 'Guest Customer', $itemCount, $totalFormatted),
            severity: 'success',
            meta: [
                'order_id'   => $orderId,
                'edit_url'   => admin_url(sprintf('post.php?post=%d&action=edit', $orderId)),
                'total'      => $order->get_total(),
                'currency'   => $order->get_currency(),
            ],
            targetRoles: ['administrator', 'shop_manager']
        );
    }

    public function handleFailedLoginAttempt(string $username): void
    {
        $clientIp = sanitize_text_field($_SERVER['REMOTE_ADDR'] ?? 'UNKNOWN');

        $this->publisher->broadcast(
            eventType: 'security.failed_login',
            title: 'Failed Administrative Login Alert',
            message: sprintf('Failed login attempt for user "%s" originating from IP %s.', sanitize_text_field($username), $clientIp),
            severity: 'warning',
            meta: [
                'username'  => $username,
                'ip_address'=> $clientIp,
                'user_agent'=> sanitize_text_field($_SERVER['HTTP_USER_AGENT'] ?? 'UNKNOWN'),
            ],
            targetRoles: ['administrator']
        );
    }

    public function handlePluginActivated(string $plugin, bool $networkWide): void
    {
        $currentUser = wp_get_current_user();

        $this->publisher->broadcast(
            eventType: 'system.plugin_activated',
            title: 'Plugin Status Changed',
            message: sprintf('Plugin %s was activated by %s.', $plugin, $currentUser->user_login),
            severity: 'info',
            meta: [
                'plugin'       => $plugin,
                'network_wide' => $networkWide,
                'user_id'      => $currentUser->ID,
            ],
            targetRoles: ['administrator']
        );
    }

    public function registerRestEndpoints(): void
    {
        register_rest_route('wpstack/v1', '/ws-handshake', [
            'methods'             => 'POST',
            'callback'            => [$this, 'generateRestTicket'],
            'permission_callback' => fn() => is_user_logged_in() && current_user_can('read'),
        ]);
    }

    public function generateRestTicket(): \WP_REST_Response
    {
        $userId = get_current_user_id();
        try {
            $ticket = $this->publisher->generateHandshakeTicket($userId);
            return new \WP_REST_Response([
                'success'    => true,
                'ticket'     => $ticket,
                'expires_in' => 300,
                'ws_url'     => defined('WPSTACK_WS_GATEWAY_URL') ? WPSTACK_WS_GATEWAY_URL : 'wss://ws.example.com',
            ], 200);
        } catch (\Exception $e) {
            return new \WP_REST_Response([
                'success' => false,
                'message' => $e->getMessage(),
            ], 500);
        }
    }

    public function enqueueAdminClientAssets(string $hookSuffix): void
    {
        wp_enqueue_style(
            'wpstack-ws-toast',
            plugins_url('assets/css/toast-notifications.css', __FILE__),
            [],
            '1.0.0'
        );

        wp_enqueue_script(
            'wpstack-ws-client',
            plugins_url('assets/js/websocket-client.js', __FILE__),
            ['wp-api-fetch'],
            '1.0.0',
            true
        );

        wp_localize_script('wpstack-ws-client', 'wpstackWsConfig', [
            'restUrl'     => esc_url_raw(rest_url('wpstack/v1/ws-handshake')),
            'nonce'       => wp_create_nonce('wp_rest'),
            'currentUserId' => get_current_user_id(),
            'userRoles'   => (array) wp_get_current_user()->roles,
        ]);
    }
}

5. High-Throughput Node.js WebSocket Gateway (Server Implementation)

To bridge Redis Pub/Sub events with hundreds of concurrent browser tabs without overloading PHP, we deploy a lightweight Node.js gateway running the ws library and ioredis client.

/**
 * WPStack Real-Time WebSocket Gateway Server
 * Node.js 20+ LTS runtime with Redis Pub/Sub integration.
 */
import { WebSocketServer, WebSocket } from 'ws';
import Redis from 'ioredis';
import crypto from 'crypto';
import http from 'http';

const PORT = process.env.WS_PORT || 8085;
const REDIS_HOST = process.env.REDIS_HOST || '127.0.0.1';
const REDIS_PORT = parseInt(process.env.REDIS_PORT || '6379', 10);
const REDIS_PASSWORD = process.env.REDIS_PASSWORD || undefined;
const AUTH_SECRET = process.env.WP_AUTH_KEY || 'your-production-wp-auth-key-salt';

const server = http.createServer((req, res) => {
    if (req.url === '/healthz') {
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ status: 'ok', uptime: process.uptime(), clients: wss.clients.size }));
        return;
    }
    res.writeHead(404);
    res.end();
});

const wss = new WebSocketServer({ server });
const redisSubscriber = new Redis({
    host: REDIS_HOST,
    port: REDIS_PORT,
    password: REDIS_PASSWORD,
});

// Map of active authenticated clients: Set keyed by userId
const activeClients = new Map();

/**
 * Validates the HMAC ticket passed during initial WebSocket handshake.
 */
function verifyHandshakeTicket(ticketBase64) {
    try {
        const decoded = Buffer.from(ticketBase64, 'base64').toString('utf-8');
        const parts = decoded.split('|');
        if (parts.length !== 5) {
            return null;
        }

        const [userIdStr, timestampStr, rolesStr, randomBytes, receivedSig] = parts;
        const userId = parseInt(userIdStr, 10);
        const timestamp = parseInt(timestampStr, 10);
        const roles = rolesStr.split(',').filter(Boolean);

        // Verify ticket age (max 5 minutes)
        const currentTimestamp = Math.floor(Date.now() / 1000);
        if (currentTimestamp - timestamp > 300 || timestamp > currentTimestamp + 30) {
            return null;
        }

        // Verify HMAC-SHA256 signature
        const payload = `${userId}|${timestamp}|${rolesStr}|${randomBytes}`;
        const calculatedSig = crypto.createHmac('sha256', AUTH_SECRET).update(payload).digest('hex');

        if (!crypto.timingSafeEqual(Buffer.from(receivedSig, 'hex'), Buffer.from(calculatedSig, 'hex'))) {
            return null;
        }

        return { userId, roles };
    } catch (err) {
        return null;
    }
}

wss.on('connection', (ws, req) => {
    ws.isAlive = true;
    ws.isAuthenticated = false;
    ws.userData = null;

    ws.on('pong', () => {
        ws.isAlive = true;
    });

    ws.on('message', (rawMessage) => {
        try {
            const data = JSON.parse(rawMessage.toString());

            if (data.action === 'authenticate') {
                const authResult = verifyHandshakeTicket(data.ticket);
                if (!authResult) {
                    ws.send(JSON.stringify({ type: 'auth_error', message: 'Invalid or expired ticket.' }));
                    ws.close(4001, 'Authentication failed');
                    return;
                }

                ws.isAuthenticated = true;
                ws.userData = authResult;

                if (!activeClients.has(authResult.userId)) {
                    activeClients.set(authResult.userId, new Set());
                }
                activeClients.get(authResult.userId).add(ws);

                ws.send(JSON.stringify({
                    type: 'authenticated',
                    userId: authResult.userId,
                    serverTime: Date.now()
                }));
            }
        } catch (err) {
            ws.send(JSON.stringify({ type: 'error', message: 'Malformed JSON payload.' }));
        }
    });

    ws.on('close', () => {
        if (ws.userData && activeClients.has(ws.userData.userId)) {
            const userSockets = activeClients.get(ws.userData.userId);
            userSockets.delete(ws);
            if (userSockets.size === 0) {
                activeClients.delete(ws.userData.userId);
            }
        }
    });
});

// Redis Pub/Sub Subscription
redisSubscriber.subscribe('wpstack_admin_notifications', (err) => {
    if (err) {
        console.error('[Redis Error] Failed to subscribe to notification channel:', err);
    } else {
        console.log('[Redis Gateway] Subscribed to wpstack_admin_notifications channel.');
    }
});

redisSubscriber.on('message', (channel, message) => {
    if (channel !== 'wpstack_admin_notifications') return;

    try {
        const payload = JSON.parse(message);
        const { target_roles, target_user_id } = payload;

        wss.clients.forEach((client) => {
            if (client.readyState !== WebSocket.OPEN || !client.isAuthenticated || !client.userData) {
                return;
            }

            // Check direct user ID match
            if (target_user_id !== null && target_user_id !== undefined) {
                if (client.userData.userId === target_user_id) {
                    client.send(JSON.stringify({ type: 'notification', data: payload }));
                }
                return;
            }

            // Check role match
            const hasMatchingRole = client.userData.roles.some((role) => target_roles.includes(role));
            if (hasMatchingRole) {
                client.send(JSON.stringify({ type: 'notification', data: payload }));
            }
        });
    } catch (err) {
        console.error('[Broadcast Error] Failed to parse or route message:', err);
    }
});

// Heartbeat interval to detect dead TCP connections
const heartbeatInterval = setInterval(() => {
    wss.clients.forEach((ws) => {
        if (ws.isAlive === false) {
            return ws.terminate();
        }
        ws.isAlive = false;
        ws.ping();
    });
}, 30000);

wss.on('close', () => clearInterval(heartbeatInterval));

server.listen(PORT, () => {
    console.log(`[WPStack Gateway] Real-time WebSocket server listening on port ${PORT}`);
});

6. Frontend Admin Client: Reconnection Logic & Toast Notification UI

The client-side JavaScript layer initializes within the WP Admin dashboard. It fetches a fresh handshake ticket via the WordPress REST API, connects to the WebSocket gateway, handles connection drops with exponential backoff, and renders customizable toast notification containers.

/**
 * WP Admin Real-Time WebSocket Client & Toast Renderer
 * File: assets/js/websocket-client.js
 */
(function () {
    'use strict';

    if (!window.wpstackWsConfig) {
        return;
    }

    const { restUrl, nonce } = window.wpstackWsConfig;
    let socket = null;
    let reconnectAttempts = 0;
    const maxReconnectAttempts = 10;
    const baseReconnectDelayMs = 1500;
    let toastContainer = null;

    /**
     * Initializes the UI Toast container inside the WP Admin DOM.
     */
    function initToastContainer() {
        if (document.getElementById('wpstack-toast-container')) {
            toastContainer = document.getElementById('wpstack-toast-container');
            return;
        }

        toastContainer = document.createElement('div');
        toastContainer.id = 'wpstack-toast-container';
        toastContainer.setAttribute('aria-live', 'polite');
        toastContainer.setAttribute('role', 'region');
        toastContainer.style.cssText = `
            position: fixed;
            top: 45px;
            right: 25px;
            z-index: 999999;
            display: flex;
            flex-direction: column;
            gap: 12px;
            max-width: 380px;
            pointer-events: none;
        `;
        document.body.appendChild(toastContainer);
    }

    /**
     * Fetches a single-use handshake ticket from the WordPress REST API.
     */
    async function fetchHandshakeTicket() {
        try {
            const response = await fetch(restUrl, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'X-WP-Nonce': nonce
                }
            });

            if (!response.ok) {
                throw new Error(`HTTP error ${response.status}`);
            }

            const data = await response.json();
            if (data.success && data.ticket) {
                return { ticket: data.ticket, wsUrl: data.ws_url };
            }
            throw new Error(data.message || 'Ticket generation failed');
        } catch (err) {
            console.warn('[WPStack WS] REST handshake fetch failed:', err.message);
            return null;
        }
    }

    /**
     * Renders an animated toast notification card.
     */
    function showToast(notification) {
        initToastContainer();

        const toast = document.createElement('div');
        toast.className = `wpstack-toast wpstack-toast-${notification.severity}`;
        toast.style.cssText = `
            pointer-events: auto;
            background: #ffffff;
            border-left: 4px solid ${getSeverityColor(notification.severity)};
            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
            border-radius: 6px;
            padding: 14px 18px;
            font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen-Sans, Ubuntu, Cantarell, sans-serif;
            font-size: 13px;
            line-height: 1.5;
            color: #1e293b;
            opacity: 0;
            transform: translateX(50px);
            transition: opacity 0.25s ease, transform 0.25s ease;
        `;

        const titleEl = document.createElement('div');
        titleEl.style.fontWeight = '600';
        titleEl.style.fontSize = '14px';
        titleEl.style.marginBottom = '4px';
        titleEl.style.color = '#0f172a';
        titleEl.textContent = notification.title;

        const bodyEl = document.createElement('div');
        bodyEl.innerHTML = notification.message;

        toast.appendChild(titleEl);
        toast.appendChild(bodyEl);

        if (notification.meta && notification.meta.edit_url) {
            const actionLink = document.createElement('a');
            actionLink.href = notification.meta.edit_url;
            actionLink.textContent = 'View Details →';
            actionLink.style.cssText = 'display: inline-block; margin-top: 6px; color: #2563eb; font-weight: 500; text-decoration: none;';
            toast.appendChild(actionLink);
        }

        toastContainer.appendChild(toast);

        // Trigger entrance animation
        requestAnimationFrame(() => {
            toast.style.opacity = '1';
            toast.style.transform = 'translateX(0)';
        });

        // Auto-dismiss after 6 seconds
        setTimeout(() => {
            toast.style.opacity = '0';
            toast.style.transform = 'translateX(50px)';
            setTimeout(() => toast.remove(), 300);
        }, 6000);
    }

    function getSeverityColor(severity) {
        switch (severity) {
            case 'success': return '#16a34a';
            case 'warning': return '#f59e0b';
            case 'error':   return '#dc2626';
            default:        return '#2563eb';
        }
    }

    /**
     * Connects to WebSocket server with exponential backoff.
     */
    async function connect() {
        const credentials = await fetchHandshakeTicket();
        if (!credentials) {
            scheduleReconnect();
            return;
        }

        try {
            socket = new WebSocket(credentials.wsUrl);

            socket.onopen = function () {
                reconnectAttempts = 0;
                socket.send(JSON.stringify({
                    action: 'authenticate',
                    ticket: credentials.ticket
                }));
            };

            socket.onmessage = function (event) {
                try {
                    const message = JSON.parse(event.data);
                    if (message.type === 'notification' && message.data) {
                        showToast(message.data);
                    }
                } catch (e) {
                    console.error('[WPStack WS] Failed to parse message event:', e);
                }
            };

            socket.onclose = function (event) {
                if (event.code !== 1000) {
                    scheduleReconnect();
                }
            };

            socket.onerror = function () {
                socket.close();
            };
        } catch (err) {
            scheduleReconnect();
        }
    }

    function scheduleReconnect() {
        if (reconnectAttempts >= maxReconnectAttempts) {
            console.warn('[WPStack WS] Max reconnect attempts reached. Halting live connection.');
            return;
        }

        const delay = Math.min(30000, baseReconnectDelayMs * Math.pow(1.5, reconnectAttempts));
        reconnectAttempts++;
        setTimeout(connect, delay);
    }

    // Initialize on DOM ready
    if (document.readyState === 'loading') {
        document.addEventListener('DOMContentLoaded', connect);
    } else {
        connect();
    }
})();

7. WP-CLI Management Command: Broadcast Real-Time Alerts

Site administrators and release engineers can instantly broadcast emergency maintenance banners, deployment notices, or security alerts across all active WordPress admin sessions using a custom WP-CLI command.

<?php
declare(strict_types=1);

namespace WPStack\WebSockets\Cli;

use WP_CLI;
use WP_CLI_Command;
use WPStack\WebSockets\Publisher\NotificationPublisherService;

final class WebSocketBroadcastCommand extends WP_CLI_Command
{
    private NotificationPublisherService $publisher;

    public function __construct()
    {
        parent::__construct();
        $this->publisher = new NotificationPublisherService();
    }

    /**
     * Broadcasts an instantaneous real-time notification to active admin sessions.
     *
     * ## OPTIONS
     *
     * --title=<title>
     * : The headline title of the administrative broadcast.
     *
     * --message=<message>
     * : The text body content of the broadcast notification.
     *
     * [--severity=<severity>]
     * : Notification alert level ('info', 'warning', 'error', 'success'). Default: 'info'.
     *
     * [--roles=<roles>]
     * : Comma-delimited list of target user roles. Default: 'administrator'.
     *
     * ## EXAMPLES
     *
     *     wp ws broadcast --title="Scheduled Maintenance" --message="Database migration starting in 5 minutes." --severity=warning
     *     wp ws broadcast --title="Security Update" --message="All sessions must re-authenticate." --severity=error --roles=administrator,shop_manager
     */
    public function broadcast(array $args, array $assocArgs): void
    {
        $title = $assocArgs['title'] ?? null;
        $message = $assocArgs['message'] ?? null;
        $severity = $assocArgs['severity'] ?? 'info';
        $rolesStr = $assocArgs['roles'] ?? 'administrator';

        if (empty($title) || empty($message)) {
            WP_CLI::error('Both --title and --message arguments are strictly required.');
            return;
        }

        $targetRoles = array_map('trim', explode(',', $rolesStr));

        WP_CLI::log(sprintf('Broadcasting event "%s" [%s] to roles: %s...', $title, $severity, implode(', ', $targetRoles)));

        $success = $this->publisher->broadcast(
            eventType: 'cli.broadcast',
            title: $title,
            message: $message,
            severity: $severity,
            meta: ['triggered_by' => 'WP-CLI', 'user' => get_current_user()],
            targetRoles: $targetRoles
        );

        if ($success) {
            WP_CLI::success('Notification published to Redis event bus successfully.');
        } else {
            WP_CLI::warning('Event published, but no active WebSocket gateway subscribers were detected on the Redis channel.');
        }
    }
}

if (defined('WP_CLI') && WP_CLI) {
    WP_CLI::add_command('ws', WebSocketBroadcastCommand::class);
}

8. Automated PHPUnit Integration Test Suite

To ensure flawless ticket signature cryptography and event formatting under strict PHP 8.3 typing, we implement a full PHPUnit integration test suite.

<?php
declare(strict_types=1);

namespace WPStack\WebSockets\Tests;

use WP_UnitTestCase;
use WPStack\WebSockets\Publisher\NotificationPublisherService;

final class NotificationPublisherTest extends WP_UnitTestCase
{
    private NotificationPublisherService $publisher;
    private int $adminUserId;

    public function set_up(): void
    {
        parent::set_up();
        $this->adminUserId = $this->factory->user->create(['role' => 'administrator']);
        $this->publisher = new NotificationPublisherService(
            redisHost: '127.0.0.1',
            redisPort: 6379,
            secretKey: 'test-secret-key-salt-phpunit'
        );
    }

    public function testGenerateHandshakeTicketStructure(): void
    {
        $ticket = $this->publisher->generateHandshakeTicket($this->adminUserId);
        $this->assertNotEmpty($ticket);

        $decoded = base64_decode($ticket, true);
        $this->assertNotFalse($decoded);

        $parts = explode('|', $decoded);
        $this->assertCount(5, $parts, 'Decoded ticket must contain 5 pipe-delimited fields.');

        $this->assertSame((string) $this->adminUserId, $parts[0]);
        $this->assertContains('administrator', explode(',', $parts[2]));

        // Verify SHA256 HMAC integrity
        $expectedSignature = hash_hmac('sha256', sprintf('%s|%s|%s|%s', $parts[0], $parts[1], $parts[2], $parts[3]), 'test-secret-key-salt-phpunit');
        $this->assertSame($expectedSignature, $parts[4]);
    }

    public function testTicketExpirationTransientStorage(): void
    {
        $ticket = $this->publisher->generateHandshakeTicket($this->adminUserId);
        $storedTransient = get_transient('wpstack_ws_token_' . $this->adminUserId);

        $this->assertSame($ticket, $storedTransient);
    }

    public function testBroadcastPayloadSanitization(): void
    {
        $dirtyTitle = 'Alert ';
        $dirtyMessage = 'Malicious  Text';

        $result = $this->publisher->broadcast(
            eventType: 'test.sanitize',
            title: $dirtyTitle,
            message: $dirtyMessage,
            severity: 'invalid_severity',
            targetRoles: ['administrator']
        );

        $this->assertIsBool($result);
    }
}

9. Production Incident Runbook: Troubleshooting Real-Time WebSockets

Frequently Asked Questions (FAQ)

Primary references

• WordPress custom REST endpoints
• WordPress capability checks
• WebSockets API reference

Aditya Bhimrajka

Aditya Bhimrajka is a technology entrepreneur, product strategist, and software solutions expert with over a decade of experience building scalable web and mobile applications. His expertise spans SaaS, AI, cloud technologies, custom software development, and digital transformation. Passionate about solving real-world business challenges through technology, Aditya shares practical insights on WordPress, plugins, software development, startup growth, product strategy, and emerging technologies. At WPStack, he writes actionable, experience-driven content that helps developers, businesses, and website owners build secure, high-performing, and future-ready WordPress solutions.