PHP API Reference

WPS::instance( )

WPSignal\WPS - main singleton facade. Central entry point for the plugin. Provides static convenience methods for the two most common operations (registering triggers and publishing events) and wires all internal components during boot().

Returns: WPS

add_action( 'wpsignal_loaded', function () {
    WPS::trigger( 'comment.created' )
        ->on( 'wp_insert_comment', 10, 2 )
        ->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();
} );

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

$config = WPSignal::instance()->config();

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.

WPS::trigger( 'post.updated' )
    ->on( 'save_post', 20, 3 )
    ->channel( 'events' )
    ->data( function ( $post_id, $post, $update ) {
        return array(
            'post_id'    => $post_id,
            'post_type'  => $post->post_type,
    ->register();

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. Add a prefix here whenever you add channels via the `wpsignal_token_channels` filter that fall outside the default `site:{site_id}:` namespace.

add_filter( 'wpsignal_token_channel_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', '__return_true' );

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', '__return_true' );

wpsignal_encryption_seed

Filters the seed used to derive the AES-256-GCM encryption key. The default seed is `AUTH_KEY . SECURE_AUTH_KEY`. 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. 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_JWT_SECRET

Legacy override: define in wp-config.php to supply the JWT signing secret. Superseded by the secret returned during site registration (stored in wp_options as `wpsignal_jwt_secret`). Only needed for sites that were configured before the auto-registration flow existed.

define( 'WPSIGNAL_JWT_SECRET', 'your-64-char-hex-secret' );