Message Persistence API for PHP SDK
Message Persistence gives you real-time access to the history of messages published to PubNub. Each message is timestamped to the nearest 10 nanoseconds and stored across multiple availability zones in several geographic locations. You can encrypt stored messages with AES-256 so they are not readable on PubNub’s network. For details, see Message Persistence.
You control how long messages are stored through your account’s retention policy. Options include: 1 day, 7 days, 30 days, 3 months, 6 months, 1 year, or Unlimited.
You can retrieve the following:
- Messages
- Message reactions
- Files (using the File Sharing API)
Fetch history
Requires Message Persistence
Enable Message Persistence for your key in the Admin Portal. See how to enable add-on features.
Fetch historical messages from one or more channels. Use includeMessageActions to include message actions.
You can control how messages are returned and in what order.
- If you specify only
start, you receive messages older than that timetoken.startis the newer boundary of the query (exclusive). - If you specify only
end, you receive messages newer than or equal to that timetoken.endis the older boundary of the query (inclusive). - If you specify both
startandend,startmust be a higher timetoken thanend. Results contain messages between those timetokens, excluding the message atstartand including the message atend.
How to use the start and end parameters
PubNub retrieves messages by searching backward through time (newest to oldest). Because of this, the parameter names are the reverse of their intuitive meaning:
startis the newer boundary (higher timetoken value) - search begins here, exclusiveendis the older boundary (lower timetoken value) - search stops here, inclusive
When you provide both parameters, start must be a higher timetoken than end.
Results are always returned in oldest-first order.
You can receive up to 100 messages for a single channel. For multiple channels (up to 500), you can receive up to 25 messages per channel. If more messages match the time range, make iterative calls and adjust the start timetoken to page through the results.
Method(s)
Use the following method(s) in the PHP SDK:
1$pubnub.fetchMessages()
2 ->channels(string|Array<string>)
3 ->maximumPerChannel(Int)
4 ->start(string)
5 ->end(string)
6 ->includeMessageActions(Boolean)
7 ->includeMeta(Boolean)
8 ->includeMessageType(Boolean)
9 ->includeCustomMessageType(Boolean)
10 ->includeUuid(Boolean)
channelsrequired#- Channels to fetch history messages from (up to 500).
maximumPerChannel#- Number of historical messages to return. Default and maximum are 100 (single), 25 (multi), and 25 with
includeMessageActions. start#- Newer boundary of the query (exclusive). Retrieval begins at this timetoken and moves backward in time. Must be a higher timetoken value than
endwhen both are provided. end#- Older boundary of the query (inclusive). Retrieval stops at this timetoken. Must be a lower timetoken value than
startwhen both are provided. includeMessageActions#- Whether to retrieve history messages with message actions. If
True, limited to one channel and 25 messages. includeMeta#- Whether to include the meta object (if provided at publish time) in the response.
includeMessageType#- Whether to include message type. See Retrieving Messages.
includeCustomMessageType#- Whether to include the custom message type. See Retrieving Messages.
includeUuid#- Whether to receive the publisher
uuid.
Sample code
Retrieve the last message on a channel:
1
Returns
The fetchMessages() operation returns an PNFetchMessagesResult which contains the following fields:
PNFetchMessagesResult
channels#- Array of
PNFetchMessageItem startTimetoken#- Start timetoken.
endTimetoken#- End timetoken.
PNFetchMessageItem
History
Requires Message Persistence
Enable Message Persistence for your key in the Admin Portal. See how to enable add-on features.
This function fetches historical messages of a channel.
It is possible to control how messages are returned and in what order, for example you can:
- Search for messages starting on the newest end of the timeline (default behavior -
reverse=false) - Search for messages from the oldest end of the timeline by setting
reversetotrue. - Page through results by providing a
startORendtimetoken. - Retrieve a slice of the time line by providing both a
startANDendtimetoken. - Limit the number of messages to a specific quantity using the
countparameter.
Method(s)
To run History you can use the following method(s) in the PHP SDK:
1$pubnub->history()
2 ->channel(String)
3 ->reverse(bool)
4 ->includeTimetoken(bool)
5 ->start(integer)
6 ->end(integer)
7 ->count(integer)
8 ->sync();
channelrequired#- Channel to return history messages from.
reverse#- Traverse from oldest to newest when set to
true. includeTimetoken#- Whether to include message timetokens in the response.
start#- Newer boundary of the query (exclusive). Retrieval begins at this timetoken and moves backward in time. Must be a higher timetoken value than
endwhen both are provided. end#- Older boundary of the query (inclusive). Retrieval stops at this timetoken. Must be a lower timetoken value than
startwhen both are provided. count#- Number of historical messages to return.
tip
reverse parameterMessages are always returned sorted in ascending time direction from history regardless of reverse. The reverse direction matters when you have more than 100 (or count, if it's set) messages in the time interval, in which case reverse determines the end of the time interval from which it should start retrieving the messages.
Sample code
Retrieve the last 5 messages on a channel:
1
Response
The history() operation returns a PNHistoryResult which contains the following operations:
getMessages()#- array of messages of type PNHistoryItemResult. See PNHistoryItemResult for more details.
getStartTimetoken()#- Start timetoken.
getEndTimetoken()#- End timetoken.
PNHistoryItemResult
Other examples
Use history() to retrieve the three oldest messages by retrieving from the time line in reverse
1
Response
1PubNub\Models\Consumer\History\PNHistoryResult Object(
2 [messages:PubNub\Models\Consumer\History\PNHistoryResult:private] => Array(
3 [0] => PubNub\Models\Consumer\History\PNHistoryItemResult Object(
4 [entry:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => Array(
5 [a] => 11
6 [b] => 22
7 )
8 [crypto:PubNub\Models\Consumer\History\PNHistoryItemResult:private] =>
9 [timetoken:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => 1111
10 )
11 [1] => PubNub\Models\Consumer\History\PNHistoryItemResult Object(
12 [entry:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => Array(
13 [a] => 33
14 [b] => 44
15 )
show all 31 linesUse history() to retrieve messages newer than a given timetoken by paging from oldest message to newest message starting at a single point in time (exclusive)
1
Response
1PubNub\Models\Consumer\History\PNHistoryResult Object(
2 [messages:PubNub\Models\Consumer\History\PNHistoryResult:private] => Array(
3 [0] => PubNub\Models\Consumer\History\PNHistoryItemResult Object(
4 [entry:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => Array
5 (
6 [a] => 11
7 [b] => 22
8 )
9
10 [crypto:PubNub\Models\Consumer\History\PNHistoryItemResult:private] =>
11 [timetoken:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => 1111
12 )
13 [1] => PubNub\Models\Consumer\History\PNHistoryItemResult Object(
14 [entry:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => Array(
15 [a] => 33
show all 36 linesUse history() to retrieve messages until a given timetoken by paging from newest message to oldest message until a specific end point in time (inclusive)
1
Response
1PubNub\Models\Consumer\History\PNHistoryResult Object(
2 [messages:PubNub\Models\Consumer\History\PNHistoryResult:private] => Array(
3 [0] => PubNub\Models\Consumer\History\PNHistoryItemResult Object(
4 [entry:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => Array(
5 [a] => 11
6 [b] => 22
7 )
8
9 [crypto:PubNub\Models\Consumer\History\PNHistoryItemResult:private] =>
10 [timetoken:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => 1111
11 )
12 [1] => PubNub\Models\Consumer\History\PNHistoryItemResult Object(
13 [entry:PubNub\Models\Consumer\History\PNHistoryItemResult:private] => Array(
14 [a] => 33
15 [b] => 44
show all 35 linesInclude timetoken in history response
1$pubnub->history()
2 ->channel("my_channel")
3 ->count(100)
4 ->includeTimetoken(true)
5 ->sync();
Delete messages from history
Requires Message Persistence
Enable Message Persistence for your key in the Admin Portal. See how to enable add-on features.
Remove messages from the history of a specific channel.
Required setting
Enable Delete-From-History for your key in the Admin Portal and initialize the SDK with a secret key.
How to use the start and end parameters
PubNub retrieves messages by searching backward through time (newest to oldest). Because of this, the parameter names are the reverse of their intuitive meaning:
startis the newer boundary (higher timetoken value) - search begins here, exclusiveendis the older boundary (lower timetoken value) - search stops here, inclusive
When you provide both parameters, start must be a higher timetoken than end.
Results are always returned in oldest-first order.
Method(s)
To Delete Messages from History you can use the following method(s) in the PHP SDK.
1$pubnub->deleteMessages()
2 ->channel(String)
3 ->start(integer)
4 ->end(integer)
5 ->sync()
Sample code
1
Other examples
Delete specific message from history
To delete a specific message, pass the publish timetoken (received from a successful publish) in the End parameter and timetoken +/- 1 in the Start parameter. For example, if 15526611838554310 is the publish timetoken, pass 15526611838554309 in Start and 15526611838554310 in End parameters respectively as shown in the following code snippet.
1
Message counts
Requires Message Persistence
Enable Message Persistence for your key in the Admin Portal. See how to enable add-on features.
Return the number of messages published since the given time. The count is the number of messages with a timetoken greater than or equal to the value in channelsTimetoken.
Unlimited message retention
Only messages from the last 30 days are counted.
Method(s)
You can use the following method(s) in the PHP SDK:
1$pubnub->messageCounts()
2 ->channels(array)
3 ->channelsTimetoken(array)
Sample code
1
Returns
The operation returns a PNMessageCountsResult which contains the following operations
getChannels()#- An associative array with channel name as key and messages count as value.
Channelswithout messages have a count of 0.Channelswith 10,000 messages or more have a count of 10000.
Other examples
Retrieve count of messages using different timetokens for each channel
1