PHP API Reference

WPS::instance()

Get the singleton instance.

Returns: WPS

WPS::trigger($event)

Create a new trigger builder. Returns a fluent builder: chain ->on(), ->channel(), ->data(), ->when(), then call ->register() to wire it up.

Returns: Trigger A new trigger builder instance.

WPS::trigger( 'user.login' )
    ->on( 'wp_login', 10, 2 )
    ->data( function ( $user_login, $user ) {
        return [ 'user_id' => $user->ID, 'login' => $user_login ];
    } )
    ->register();

WPS::publish($channel, $event, $data)

Publish an event directly (no hook needed). Sends an HMAC-signed POST to the WPSignal server. The plugin must be configured (site_key, site_secret, base_url) or this returns a WP_Error.

Returns: array|WP_Error wp_remote_post response array on success, WP_Error on failure.

WPS::publish( 'events', 'custom.event', [ 'key' => 'value' ] );

->on( $hook, $priority, $accepted_args )

Set the WordPress action hook to listen on.

Returns: $this

->on( 'save_post', 20, 3 )    // priority 20, 3 args
->on( 'wp_login' )            // defaults: priority 10, 1 arg

->channel( $channel )

Set the channel to publish on. Defaults to "events" if not called. The server normalizes this to the full tenant-scoped channel name.

Returns: $this

->channel( 'orders' )

->data( $callback )

Set the data builder callback. The callback receives the same arguments as the WordPress hook and should return an associative array. This array becomes the `data` field in the published event payload.

Returns: $this

->data( function ( $post_id, $post, $update ) {
    return [
        'post_id'    => $post_id,
        'post_title' => $post->post_title,
    ];
} )

->when( $callback )

Set a condition callback. The callback receives the same arguments as the WordPress hook. Return false to skip publishing for this hook invocation. If not set, the trigger always fires.

Returns: $this

->when( function ( $post_id, $post ) {
    return 'publish' === $post->post_status;
} )

->register( )

Register this trigger with the global trigger registry. This wires the WordPress hook so the trigger fires automatically. Must be called after configuring the builder.

wpsignal_token_channels

Filters the channels the client auto-subscribes to on connect. Plugins can append their own channels so they are included in the initial WebSocket/SSE subscription without a separate subscribe call.

add_filter( 'wpsignal_token_channels', function ( $value ) {
    // modify $value and return it
    return $value;
} );

wpsignal_token_channel_prefixes

Filters the channel prefixes the JWT allows the client to subscribe to. The WPSignal server rejects subscribe/publish frames whose channel does not start with one of these prefixes. The default is the site wildcard `site:{site_id}:` until a plugin reserves a namespace through `WPS::instance()->channels()->reserve()`; from then on it is an explicit list (see `Channels::allowed_prefixes()`), so register every channel you subscribe to through `wpsignal_token_channels`.

add_filter( 'wpsignal_token_channel_prefixes', function ( $value ) {
    // modify $value and return it
    return $value;
} );

wpsignal_token_publish_prefixes

Filters the channel prefixes the JWT allows the client to publish on. Publishing covers `WPS.publish()`, binary frames, and presence. The default is the site wildcard until a plugin reserves a namespace; from then on only reserved namespaces whose publish grant the user passes (see `Channels::reserve()`), so a channel registered for reading stays read-only unless it is added here.

add_filter( 'wpsignal_token_publish_prefixes', function ( $value ) {
    // modify $value and return it
    return $value;
} );

wpsignal_allow_client

Controls whether the WordSocket client script is enqueued for the current request. Return `false` to prevent the script from loading (e.g. on specific post types or for guest users). Return `true` to force-load it regardless of login state.

add_filter( 'wpsignal_allow_client', function ( $value ) {
    // modify $value and return it
    return $value;
} );

wpsignal_force_sse

Forces the client to use SSE instead of WebSocket. Return `true` to disable WebSocket and fall back to Server-Sent Events. Useful in environments where WebSocket connections are blocked.

add_filter( 'wpsignal_force_sse', function ( $value ) {
    // modify $value and return it
    return $value;
} );

wpsignal_encryption_seed

Filters the seed used to derive the AES-256-GCM encryption key. The default seed is `AUTH_KEY . SECURE_AUTH_KEY` from WordPress salts. Override this to supply your own key material without modifying WordPress salts.

add_filter( 'wpsignal_encryption_seed', function ( $seed ) {
    return 'my-application-specific-secret';
} );

wpsignal_loaded

Fires when WPSignal is fully loaded and ready for trigger registration. NB: this can only be called by plugins since this runs on `plugins_loaded` hook. Themes will need to use `init` hook instead. Third-party plugins should hook here to register custom triggers:

add_action( 'wpsignal_loaded', function () {
    WPS::trigger( 'order.completed' )
        ->on( 'woocommerce_order_status_completed' )
        ->channel( 'orders' )
        ->data( function ( $order_id ) {
            $order = wc_get_order( $order_id );
            return [ 'order_id' => $order_id, 'total' => $order->get_total() ];
        } )
        ->register();
} );

WPSignal\BASE_URL

Define in wp-config.php to point the plugin at a self-hosted WPSignal server. When defined, overrides the default https://api.wpsignal.io endpoint for all publish, registration, and token requests.

define( 'WPSignal\\BASE_URL', 'https://signal.example.com' );

WPSIGNAL_SITE_KEY

Define in wp-config.php to hard-code the site key. Overrides the value stored in wp_options by the auto-registration flow. Useful for environments where the database is ephemeral (e.g. CI, staging clones) or when credentials are managed via environment variables.

const WPSIGNAL_SITE_KEY = 'your-32-char-hex-site-key';

// or using define:
define( 'WPSIGNAL_SITE_KEY', 'your-32-char-hex-site-key' );

WPSIGNAL_SITE_SECRET

Define in wp-config.php to hard-code the publish secret. Overrides the value stored in wp_options. Always pair with WPSIGNAL_SITE_KEY. Never expose this value to browsers.

const WPSIGNAL_SITE_SECRET = 'your-64-char-hex-secret';

// or using define:
define( 'WPSIGNAL_SITE_SECRET', 'your-64-char-hex-secret' );