Presence API for PubNub PHP SDK
Presence enables you to track the online and offline status of users and devices in real time, as well as store custom state information. Presence provides authoritative information on:
- When a user has joined or left a channel
- Who, and how many, users are subscribed to a particular channel
- Which channel(s) an individual user is subscribed to
- Associated state information for these users
Learn more about our Presence feature here.
Here Now
Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
You can obtain information about the current state of a channel including a list of unique user-ids currently subscribed to the channel and the total occupancy count of the channel by calling the hereNow()
function in your application.
Method(s)
To call Here Now
you can use the following method(s) in the PHP V4 SDK:
$pubnub->hereNow()->channels(string|array)->channelGroups(string|array)->includeState(boolean)->includeUuids(boolean)->sync();
Parameter Type Required Defaults Description channels
String|Array Optional The channels
to get thehere now
details.channelGroups
String|Array Optional The channel groups
to get thehere now
details.includeState
Boolean Optional false
If true
, the response will include the presence states of the users forchannels
/channelGroups
.includeUuids
Boolean Optional true
If true
, the response will include theUUIDs
of the connected clients.
Basic Usage
Get a list of UUIDs subscribed to channel:
try {
$result = $pubnub->hereNow()
->channels(["my_channel", "demo"])
->includeUuids(true)
->sync();
} catch (PubNubException $err) {
print_r($err);
}
foreach ($result->getChannels() as $channelData) {
print("---\n");
printf("channel: %s\n", $channelData->getChannelName());
printf("occupancy: %s\n", $channelData->getOccupancy());
foreach ($channelData->getOccupants() as $occupant) {
printf("uuid: %s, state: %s\n", $occupant->getUuid(), $occupant->getState());
}
}
Response
The hereNow()
operation returns a PNHereNowResult
which contains the following fields:
Method | Type | Description |
---|---|---|
getTotalChannels() | Integer | Total Channels . |
getTotalOccupancy() | Integer | Total Occupancy . |
getChannels() | Array | A array with values of PNHereNowChannelData for each channel . See PNHereNowChannelData for more details. |
Method | Type | Description |
---|---|---|
getChannelName() | String | Channel name. |
getOccupancy() | Integer | Occupancy of the channel . |
getOccupants() | Array | A array of PNHereNowOccupantData , see PNHereNowOccupantData for more details. |
Method | Type | Description |
---|---|---|
getUuid() | String | UUID of the user. |
getState() | Array | State of the user. |
Other Examples
- Returning State: Requires Presence add-onRequires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-$result = $pubnub->hereNow() ->channels("my_channel") ->includeUuids(true) ->includeState(true) ->sync();
PubNub\Models\Consumer\Presence\PNHereNowResult Object( [totalChannels:protected] => 2 [totalOccupancy:protected] => 3 [channels:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowChannelData Object( [channelName:protected] => ch1 [occupancy:protected] => 1 [occupants:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => user1 [state:protected] => ) ) ) [1] => PubNub\Models\Consumer\Presence\PNHereNowChannelData Object( [channelName:protected] => ch2 [occupancy:protected] => 2 [occupants:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => user1 [state:protected] => ) [1] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => user3 [state:protected] => ) ) ) ) )
- Return Occupancy Only: Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-You can return only the
occupancy
information for a single channel by specifying the channel and settingUUIDs
to false:$result = $pubnub->hereNow() ->channels("my_channel") ->includeUuids(false) ->includeState(false) ->sync();
PubNub\Models\Consumer\Presence\PNHereNowResult Object( [totalChannels:protected] => 2 [totalOccupancy:protected] => 3 [channels:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowChannelData Object( [channelName:protected] => ch1 [occupancy:protected] => 1 [occupants:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => user1 [state:protected] => ) ) ) [1] => PubNub\Models\Consumer\Presence\PNHereNowChannelData Object( [channelName:protected] => ch2 [occupancy:protected] => 2 [occupants:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => user1 [state:protected] => ) [1] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => user3 [state:protected] => ) ) ) ) )
-
$pubnub->hereNow() ->channelGroups(["cg1", "cg2", "cg3"]) ->includeUuids(true) ->includeState(true) ->sync();
( [totalChannels:protected] => 1 [totalOccupancy:protected] => 4 [channels:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowChannelData Object( [channelName:protected] => ch1 [occupancy:protected] => 1 [occupants:protected] => Array( [0] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => 123123234t234f34fq3dq [state:protected] => ) [1] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => 143r34f34t34fq34q34q3 [state:protected] => ) [2] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => 23f34d3f4rq34r34rq23q [state:protected] => ) [3] => PubNub\Models\Consumer\Presence\PNHereNowOccupantsData Object( [uuid:protected] => w34tcw45t45tcw435tww3 [state:protected] => ) ) ) ) )
Where Now
Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
You can obtain information about the current list of channels to which a UUID is subscribed to by calling the whereNow()
function in your application.
Note
If the app is killed/crashes and restarted (or the page containing the PubNub instance is refreshed on the browser) within the heartbeat window no timeout event is generated.
Method(s)
To call whereNow()
you can use the following method(s) in the PHP V4 SDK:
$pubnub->whereNow()->uuid(string)->sync();
Parameter Type Required Defaults Description uuid
String Optional Uuid
of the user we want to spy on.
Basic Usage
You simply need to define the uuid
and the callback
function to be used to send the data to as in the example below.
Get a list of channels a UUID is subscribed to:
$result = $pubnub->whereNow()
->sync();
Rest Response from Server
The whereNow()
function returns a list of channels a uuid
is subscribed to.
channels:["String","String", ... ,"String"]
- List of channels auuid
is subscribed to.
Example Response:
{
"channels": [
"lobby",
"game01",
"chat"
]
}
Other Examples
$result = $pubnub->whereNow()
->uuid("his-uuid")
->sync();
User State
Requires Presence add-on Requires that the Presence add-on is enabled for your key. See this page on enabling add-on features on your keys:
https://support.pubnub.com/hc/en-us/articles/360051974791-How-do-I-enable-add-on-features-for-my-keys-
Description
The state API is used to set/get key/value pairs specific to a subscriber uuid
.
State information is supplied as a JSON object of key/value pairs.
Method(s)
$pubnub->setState()->channels(string|array)->channelGroups(string|array)->state(array)->sync();
Parameter Type Required Description channels
String|Array Optional channels
to setstate
.channelGroups
String|Array Optional channel groups
to setstate
.state
Array Optional State
to set.
$pubnub->getState()->channels(string|array)->channelGroups(string|array)->uuid(string)->sync();
Parameter Type Required Description channels
String|Array Optional channels
to getstate
.channelGroups
String|Array Optional channel groups
to getstate
.uuid
String Optional uuid
Basic Usage
$pubnub->setState()
->channels(["ch1", "ch2", "ch3"])
->state(["age" => 30])
->sync();
$pubnub->getState()
->channels(["ch1", "ch2", "ch3"])
->sync();
Response
The setState()
operation returns a PNSetStateResult
which contains the following fields:
Method | Type | Description |
---|---|---|
setState() | Array | Array of UUIDs and the user states. |
The getState()
operation returns a PNGetStateResult
which contains the following fields:
Method | Type | Description |
---|---|---|
getChannels() | Array | Array of channels and the user states. |