Guide
Getting Started
From a fresh WordPress install to live browser events in under 5 minutes.
1 Prerequisites
- WordPress 6.2 or later
- PHP 7.4 or later
- A free WPSignal account (sign up at wpsignal.io)
- Your WordPress site must be able to make outbound HTTP requests (most hosts allow this)
2 Install the plugin
WordSocket is available on the WordPress.org plugin directory. Install it from the WordPress admin or via WP-CLI:
wp plugin install wordsocket --activate
Or go to WP Admin → Plugins → Add New and search for WordSocket.
3 Connect to WPSignal
HTTPS
If you are using HTTPS, you can connect to the WPSignal server by clicking the Connect to WPSignal button on the WP Admin > WordSocket > Connection settings page.
HTTP
If you are using HTTP, you can connect to the WPSignal server by entering your WPSignal API key from the dashboard and clicking the Connect to WPSignal button on the WP Admin > WordSocket > Connection settings page.
4 Verify with Explorer
Go to WordSocket → Explorer in the WordPress admin menu.
This page shows five panels:
- Connection Status: live WebSocket state indicator
- Registered Triggers: table of all active triggers
- Live Event Log: realtime stream of received events
- Publish Form: manually send a test event
- Token Inspector: decode and inspect your current JWT
If the connection status shows Connected, your setup is working. Use the Publish Form to send a test event and watch it appear in the Event Log instantly.
5 Your first event in the browser
The plugin automatically enqueues client.js for logged-in
users. The script connects via WebSocket (SSE fallback) and dispatches a native
CustomEvent for each received event.
Listen for events with plain JavaScript:
document.addEventListener('wpsignal:post.updated', (e) => {
console.log('Post updated:', e.detail);
// e.detail = { event: 'post.updated', data: { post_id, ... }, channel: '...' }
});
The event name format is wpsignal:{event_name}. The
built-in trigger fires wpsignal:post.updated whenever a post is saved.
Save any post in the WordPress editor and observe the event fire in your browser console.
6 Custom triggers
Use the fluent WPS::trigger() builder
to publish on any WordPress action hook.
Where to register triggers
wpsignal_loaded: use this inside a plugin. It fires during plugin initialisation, before the theme loads.
init: use this inside a theme's functions.php. Themes load after plugins, so wpsignal_loaded has already fired by the time functions.php runs, meaning your callback would never execute.
New comment published
add_action('wpsignal_loaded', function () {
WPS::trigger('comment.created')
->on('wp_insert_comment', 10, 2)
->channel('events')
->data(function ($comment_id, $comment) {
return [
'comment_id' => $comment_id,
'post_id' => $comment->comment_post_ID,
'author' => $comment->comment_author,
];
})
->when(function ($comment_id, $comment) {
return (int) $comment->comment_approved === 1;
})
->register();
});WooCommerce order status change, inside a theme
add_action('init', function () {
WPS::trigger('order.status_changed')
->on('woocommerce_order_status_changed', 10, 3)
->channel('events')
->data(function ($order_id, $old_status, $new_status) {
return [
'order_id' => $order_id,
'old_status' => $old_status,
'new_status' => $new_status,
];
})
->register();
});Builder methods
->on($hook, $priority, $args): WordPress action to attach to
->channel($name): channel to publish on (default: events)
->data(callable): transform hook args into event payload
->when(callable): optional condition; returning false skips publish
->register(): finalize and register the trigger
7 Direct publish
For one-off publishes outside of a hook, call
WPS::publish() directly:
// Publish from anywhere in your plugin or theme
WPS::publish('events', 'custom.event', [
'message' => 'Hello from PHP',
'time' => time(),
]);This sends an HMAC-signed HTTP POST to the WPSignal server immediately.
8 Allowing public (logged-out) access
By default client.js is only enqueued for logged-in users.
To serve realtime events to all visitors, one filter is all you need:
// Prevent non-logged-in users from receiving realtime events.
add_filter('wpsignal_allow_client', '__return_false'); wpsignal_allow_client is the single access control for the realtime client.
It gates the script enqueue and the connection token minted server-side at page load.
Token refresh is handled automatically and protected by a WordPress REST nonce. No additional configuration required.