PHP reference
Everything is on wordplus_realtime(), the newest copy of the package on the site. Call it from plugins_loaded on.
Channels
| Method | Returns | |
|---|---|---|
channel( $prefix, $authorize ) | $this | owns the channels whose names start with $prefix. $authorize( $user_id, $channel ) answers false, true, or array( 'info' => …, 'id' => … ) (channels, presence) |
publish( $channels, $event, $data = null, $args = array() ) | true or WP_Error | an event to up to 100 channels; $args: except, seal, blocking, timeout (publishing) |
publish_batch( $events, $args = array() ) | true or WP_Error | up to 10 events, each channels, event, data, except, seal |
channel_info( $channel ) | array or WP_Error | subscriptions, and a presence channel's members |
token( $channels, $user = null, $info = null, $ttl = null ) | string or null | a channels token you hand out yourself, in place of the auth route |
authorize( $channels, $user_id ) | array | what the auth route answers: token, exp, keys, denied |
may_join( $channel, $user_id ) | bool | whether the channel's owner lets the user in, as the auth route asks it |
script() | handle | the page script with its settings in window.wordplusRealtimeConfig; an empty handle on a site without credentials |
Calls
| Method | Returns | |
|---|---|---|
calls( $prefix, $authorize ) | $this | owns the calls and rooms whose names start with $prefix. $authorize( $user_id, $call, $with ) answers false, true, or array( 'info' => …, 'publish' => …, 'subscribe' => …, 'admin' => …, 'hidden' => … ); $with is the other person, or null for a room (calls, group calls) |
calls_script() | handle | the calls script, window.wordplusRealtimeCalls, after the page script; the empty handle without credentials |
call_screen( $args = array() ) | bool | loads the call screen on the page; $args['ring'] false: nothing rings on it |
call_user() | int | who takes part in calls on this page: user() |
authorize_call( $request, $user_id ) | array | what the calls route answers: token, exp, key for a call, or denied |
screen_strings() | array | the call screen's words in the site's language |
WordPlus_Realtime::call_key( $id, $caller, $callee ) | string | the key a call's two pages seal their negotiation with |
Keys and the site's users
Encryption explains them. On wordplus_realtime()->keys():
| Method | Returns | |
|---|---|---|
seal( $value, $label ), seal_json( $data, $label ) | string or null | a value sealed with a label's key: only those who may have that key open it |
open( $value ) | string or null | what a value this site sealed holds; null for anything else or anything changed |
WordPlus_Realtime_Keys::label_of( $value ) | string or null | the label of the key that opens a sealed value |
day_label(), user_label( $user_id ), channel_label( $channel ) | string | the day's key, a user's own, a private or presence channel's newest |
rotate_user( $user_id ), rotate_channel( $channel ) | the next key, which someone who lost access never gets | |
kind( $kind, $may_have, $newest = null ) | $this | keys of your own, {kind}:{…}: $may_have( $rest, $user_id, $label ) says who may have one; $newest( $rest, $label ) names the newest of the same thing |
may_have( $label, $user_id ) | bool | whether the user may have a key |
entry( $label ) | string | a key as the site hands it to a browser |
user_entries( $user_id ) | string[] | the keys a user starts with: their own, and the day's from yesterday's to tomorrow's |
profile( $user_id ) | array or null | the user's entry in the site's directory, sealed (pd, pdh) |
sealing() | bool | whether the site seals (wordplus_realtime_seal) |
And on wordplus_realtime():
| Method | Returns | |
|---|---|---|
user() | int | who the site knows on this request: the signed-in user, a visitor's negative id (wordplus_realtime_visitor_id), or 0 |
identity( $user_id ) | array( 'token', 'exp' ) or null | who the user is for the realtime server, with their directory entry, signed as the site |
The site
| Method | Returns | |
|---|---|---|
available() | bool | the site has its credentials |
credentials() | array( 'key', 'secret' ) or null | the site key and the secret to sign with now |
site_key() | string | the site key, or '' |
connect()->url( $return_to ) | URL | WordPlus Cloud's approval, back to $return_to with wordplus_realtime=connected, denied or failed |
server(), api_server() | URL | where browsers connect, and where the site's requests go |
config() | array | what the page gets in window.wordplusRealtimeConfig |
version() | string | this copy's version |
Routes
| Route | |
|---|---|
POST /wp-json/wordplus/v1/realtime/auth | { channels } → { token, exp, denied } |
POST /wp-json/wordplus/v1/realtime/calls | { line: true }, { call, id, role, to or from, type } or { room, type } → { token, exp, key? } or { denied } |
POST /wp-json/wordplus/v1/realtime/keys | { labels } → { keys }, those the user may have; { labels: [] } → the keys they start with and their identity |
Anyone may ask; your callbacks decide. A refusal is an answer, not an HTTP error.
Filters
| Filter | Default | |
|---|---|---|
wordplus_realtime_token_ttl | 21600 | a channels token's life in seconds, at most a day |
wordplus_realtime_call_token_ttl | 21600 | a calls token's, at most 6 hours |
wordplus_realtime_visitor_id | 0 | a visitor's id, a negative number: who takes part in calls and gets keys |
wordplus_realtime_seal | true | whether what the site sends through WordPlus Cloud goes sealed |
wordplus_realtime_user_has_keys | true | false keeps every key from a user you cut off ($has, $user_id) |
wordplus_realtime_profile | name, avatar, author page | a user's entry in the site's directory ($profile, $user_id); text is sealed |
wordplus_realtime_call_screen_strings | the words | the call screen's words |
wordplus_realtime_server | https://ws.wordplus.cloud/ | where browsers connect |
wordplus_realtime_api_server | https://rest.wordplus.cloud/ | where the site's requests and a closing page's leave go |
wordplus_realtime_account | https://www.wordplus.cloud/ | where Connect sends the administrator |
wordplus_realtime_account_api | https://api.wordplus.cloud/ | where Connect's code is exchanged |
The option
The credentials live in wordplus_cloud_license, which every WordPlus plugin on the site shares: on a network, the network's when the site has none. The package only reads it, but Connect writes it.
The master key every other key is derived from lives in wordplus_realtime_master_key, the network's on a network. It never leaves the site; deleting it changes every key, and what was sealed before no longer opens.