DataSync API for PHP SDK
DataSync is PubNub's data layer for storing application state (users, channels, memberships, and any custom object type) and keeping every connected client current through real-time events. Use it to model the objects your application works with and to react the moment they change.
DataSync is the successor to App Context.
DataSync entities and SDK entities are different things
This page is about DataSync entities, the records the service stores and treats as the source of truth for your application state. They are created and read through the $pubnub->dataSync()->* methods documented here.
The PHP SDK has no client-side SDK entity concept. A channel ID is just the string you pass to channels() when you subscribe, it carries no stored state of its own. To observe a DataSync object in real time, subscribe to its channel and attach a DataSync listener to the PubNub client, as described in Real-time updates.
The classes that your objects conform to (their types and schemas) are defined through the Admin API or the Admin Portal, not through this SDK:
- Entity classes, which back users, channels, and custom entities: list, read, create, replace, and delete. Partial updates aren't implemented; replace the complete class version instead.
- Relationship classes, which back memberships and custom relationships: list, read, create, replace, and delete.
User and Channel entity classes and the Membership relationship class are predefined on every keyset, so you only need to define classes for your own custom entities and relationships.
A class definition is what decides, for every object of that class, which payload fields are filterable and sortable, which projection each field belongs to, and how long the object lives before it expires. Refer to managing classes for more information.
Every method returns a typed result from sync(), or a PNEnvelope from envelope() that carries the result and the status side by side. The single-object methods return a result whose getData() holds the record, with getId() and getETag() as shortcuts. The list methods return a result whose getData() holds an array of records, with count() and getPage() for the pagination details. The deleteUser, deleteChannel, deleteMembership, deleteEntity, and deleteRelationship methods return a PNDataSyncDeleteResult that carries no data. The status key in each Response block below stands for the HTTP status code, which envelope() exposes through getStatus()->getStatusCode(), and the result doesn't surface the HATEOAS links the service adds to a response. A stored object carries its free-form status and its expiresAt auto-deletion timestamp (ISO 8601) whenever those are set on it, and the timestamps stay ISO 8601 strings rather than becoming DateTime objects.
#
The DataSync API returns prev_cursor and has_prev, but this SDK doesn't read them, so PNDataSyncPage has no previous cursor or previous-page flag. Pagination in this SDK is forward-only. To revisit an earlier page, page from the start again.
All list methods (getUsers, getChannels, getMemberships, getEntities, and getRelationships) accept cursor and limit (default 20, max 100) and can return a PNDataSyncPage from getPage() with hasNext(), getNextCursor(), and getLimit(). The page is optional, so guard the access when you read it, for example $result->getPage()?->getNextCursor().
To page forward, pass the returned getNextCursor() value back as cursor on the next call, and stop when hasNext() is false. getNextCursor() is null on the last page. Refer to sorting and pagination for details.
#
All list methods accept two mutually exclusive filter parameters, filterFast and filter. The SDK sends whatever you set, so a call that carries both reaches the server and fails there with a 400.
| Parameter | Consistency | Properties it can read | Expression complexity |
|---|---|---|---|
filterFast | Strongly consistent, reflects the latest writes | Filtering mode simple or full | Up to 10 conditions by default (raisable per keyset) |
filter | Eventually consistent, results can briefly lag writes | Filtering mode full only | Full expression language |
Reach for filterFast when the query has to see an object you just wrote, and for filter when you need the full expression language over a full-indexed property.
danger
filter is not the strongly consistent oneThe two names read the wrong way round if you assume filter is the basic option. filterFast is the strongly consistent, limited one. filter is the richer, eventually consistent one.
Both parameters share the same expression language, a string built from a property name, an operator, and a value:
| Operators | |
|---|---|
| Comparison | ==, !=, <, >, <=, >= |
| Pattern matching | LIKE (case-insensitive), SLIKE (case-sensitive), ILIKE (case-insensitive, same as LIKE) |
| Logical | &&, ||, !, and parentheses for grouping |
Values are quoted strings, numbers, true, false, or null. Pattern operators (LIKE, SLIKE, ILIKE) apply to string properties only, and null is only valid with == and !=. Reference a property by its name, not its declared path, and only properties declared on the class are filterable. To reach a nested payload property, declare it as a class property first, then filter by that property's name, for example 'price < 100' for a product class that declares price.
Some examples:
1->filterFast('price < 100') // strongly consistent, single condition
2->filterFast('(price < 100 && stock > 0) || price > 500') // strongly consistent, grouped conditions
3->filter('name LIKE "*sneaker*"') // eventually consistent, needs filtering mode "full"
4->filter('!(status == "discontinued")') // eventually consistent, negated condition
Both parameters only work over properties declared on the class, plus the built-in id, createdAt, updatedAt, and status fields, which are always filterable and sortable without being declared. eTag and expiresAt are neither. The status exception does not hold if the class redeclares /status scoped to projections your token cannot fully reach. When you don't pass the class version, the list includes items of every version, but filter, filterFast, and sort can only use properties declared on the latest version of the class. A property that exists only in an older version is rejected with a 400. Pass the class version (entityClassVersion, or relationshipClassVersion on memberships and relationships) to use properties declared on an older version. Refer to filtering for the two filtering tiers, and property definitions for how properties are declared.
Use sort to order results. Its value is a comma-separated list of fields, each a property name optionally suffixed with :asc or :desc. A bare name sorts ascending:
1->sort('price:desc') // single field, descending
2->sort('type,price:desc') // type ascending, then price descending
3->sort('createdAt:asc') // explicit ascending
sort also accepts an array that the SDK joins into that string. A key is a property name and its value is 'asc' or 'desc', and a bare list entry sorts ascending. Fields are joined in the order they appear:
1->sort(['type', 'price' => 'desc']) // same order as 'type,price:desc'
The +field and -field prefixes are not accepted. A leading - is read as part of the property name, so '-price' fails with a 400. Only properties declared on the class with a filtering mode other than none can be sorted on when sorting alone or alongside filterFast. Sorting alongside filter additionally requires the field to be declared full. The built-in fields id, createdAt, updatedAt, and status are always sortable without declaring them on the class.
The SDK doesn't validate filterFast, filter, or limit locally, it passes them through as-is, and it passes a sort string through untouched. An invalid expression, an unsortable field, or an out-of-range limit only surfaces as an error response from the server. The one exception is an array sort whose direction is neither asc nor desc, which throws a PubNubValidationException before anything is sent, because the server would otherwise silently drop the direction and sort the other way.
#
Every stored object carries an ETag. To guard against concurrent writes, pass the ETag you read earlier as ifMatchesETag on set*, update*, and delete* calls. The SDK sends it as the If-Match request header.
If the server-side value has changed in the meantime, the operation fails with a 412, and you should re-read the object and retry. Refer to optimistic concurrency with ETags for details.
With sync(), the 412 arrives as a PubNubServerException, and getStatusCode() returns it.
#
The update* methods apply a partial update using raw JSON Patch (RFC 6902). Build the operations by chaining add, remove, replace, move, copy, and test on a PNDataSyncPatch and pass it to patch, or pass a raw array of operations instead. Each raw operation has an op (add, remove, replace, move, copy, or test), a path (a full JSON Pointer, for example /status or /payload/price), and, depending on the operation, a value or a from.
Each path is a full JSON Pointer (RFC 6901) and is sent as you write it. The SDK does not add a /payload prefix. To target a field inside payload, include the prefix yourself, for example /payload/price, not /price. A bare /price targets a top-level field named price, which doesn't exist. Top-level fields like /status can be patched directly. Refer to partial update for details.
Correct patch forms:
1->add('/payload/tags', 'sale') // adds a value inside payload.tags
2->replace('/payload/price', 79.99) // replaces payload.price
3->remove('/payload/tempFlag') // removes payload.tempFlag
4->move('/payload/oldTag', '/payload/tag')
5->copy('/payload/price', '/payload/msrp')
6->test('/status', 'active') // fails the patch if the current value doesn't match
move and copy take the source pointer first and the target pointer second, instead of a value. test fails the entire patch if the current value at its path doesn't match, use it to guard the rest of the operations against a stale read.
Paths address the object's stored property names, the same keys that come back in responses. The class version is entityClassVersion on users, channels, and entities, and relationshipClassVersion on memberships and relationships. The fields set at creation cannot be patched: entityClass and entityClassLevel on users, channels, and entities, relationshipClass, entityAId, and entityBId on relationships, and userId and channelId on memberships.
All operations in the call apply together or not at all.
The patch must contain at least one operation. The SDK checks this before it sends anything and throws a PubNubValidationException if the builder is empty or the array has no operations. For a raw array, it also checks that every operation has an op and a path, a value for add, replace, and test, and a from for move and copy.
#
An object's expiresAt is computed once when the object is created, and updates never refresh it. The value is the creation time plus the class TTL, rounded up to the start of the next whole UTC day, so it rarely lands exactly one TTL from the moment you wrote the object.
Entity classes you create default to a 31-day TTL, while the built-in Global User and Channel classes use 30 days. TTL cannot be disabled. A relationship expires at the earlier expiry time of the two entities it links, fixed when the relationship is created.
Refer to data expiry for details.
Synchronous calls, two ways to read the outcome
Every DataSync method is a fluent builder that you finish with sync() or envelope(), and the request blocks until it completes. sync() returns the typed result and throws on failure: a PubNubValidationException for a missing or invalid argument, checked before anything is sent (for example a missing id, an entityClassVersion below 1, or a missing entityClass on entities), and a PubNubServerException when the service answers with an error, where getStatusCode() returns the HTTP status. envelope() returns a PNEnvelope and never throws for a server error, so call isError() first, then read getResult() or getStatus(). It also skips the argument checks, so the service rejects an invalid request instead. The samples use sync().
Requires Access Manager
DataSync requires that the Access Manager add-on is enabled for your key in the Admin Portal. See Enable the features your app calls.
Users
Users are built-in objects. There are no top-level name or email fields, all application data lives in the free-form payload. Refer to users for the concept.
A user is an entity of the built-in User entity class, which the service provides at the Global class level. To give your users their own declared, filterable properties, define a subclass of User with Create a new entity class and pass its name as entityClass.
Create user
Creates a user. Supply an userId to control the identifier, or omit it to let the server generate one.
Method(s)
1$pubnub->dataSync()->createUser()
2 ->userId(string)
3 ->entityClass(string)
4 ->entityClassVersion(int)
5 ->entityClassLevel(string)
6 ->status(string)
7 ->payload(array)
8 ->sync(); // PNDataSyncUserResult
userId#- User identifier. Omit to let the server generate a UUID. Max 255 characters.
entityClass#- Name of the entity class this user belongs to. Must be
Useror one of its subclasses. Defaults toUseron the server if omitted. Set at creation and immutable afterward. entityClassVersionrequired#- Version of the user class schema.
entityClassLevel#- Class hierarchy level of
entityClass, eitherGlobalfor a class the service provides orSubKeyfor one defined on your keyset. Used to disambiguate classes with the same name defined at different levels. Set at creation and immutable afterward. status#- Free-form lifecycle status. Max 100 characters.
payload#- Free-form JSON object holding your application data.
Sample code
1
Response
1{
2 "status": 201,
3 "data": {
4 "id": "user-alice",
5 "entityClass": "User",
6 "entityClassVersion": 1,
7 "entityClassLevel": "Global",
8 "payload": { "name": "Alice", "type": "shopper" },
9 "createdAt": "2026-07-13T09:00:00.000Z",
10 "updatedAt": "2026-07-13T09:00:00.000Z",
11 "eTag": "AbCdEfGhIjKlMn"
12 }
13}
Get user
Returns a single user by userId.
Method(s)
1$pubnub->dataSync()->getUser()
2 ->userId(string)
3 ->sync(); // PNDataSyncUserResult
userIdrequired#- User identifier.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "user-alice",
5 "entityClass": "User",
6 "entityClassVersion": 1,
7 "entityClassLevel": "Global",
8 "payload": { "name": "Alice", "type": "shopper" },
9 "createdAt": "2026-07-13T09:00:00.000Z",
10 "updatedAt": "2026-07-13T09:00:00.000Z",
11 "eTag": "AbCdEfGhIjKlMn"
12 }
13}
Get all users
Returns a paginated list of users. All parameters are optional, so you can call getUsers and finish with sync() straight away. For pagination, filtering, and sorting, refer to sorting and pagination.
Method(s)
1$pubnub->dataSync()->getUsers()
2 ->entityClass(string)
3 ->entityClassVersion(int)
4 ->entityClassLevel(string)
5 ->cursor(string)
6 ->limit(int)
7 ->filterFast(string)
8 ->filter(string)
9 ->sort(string|array)
10 ->sync(); // PNDataSyncUsersResult
entityClass#- User class to list. Omit to list the Global
Userclass and all of its subclasses. entityClassVersion#- User class version to list. Omit to list users across every version of the class.
entityClassLevel#- Class hierarchy level of
entityClass, eitherGlobalfor a class the service provides orSubKeyfor one defined on your keyset. Used to disambiguate a class name defined at both levels. cursor#- Opaque pagination cursor. Omit for the first page.
limit#- Maximum number of users per page. Max
100. filterFast#- Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode
simpleorfull. Cannot be combined withfilter. filter#- Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode
full. Cannot be combined withfilterFast. sort#- Order results. Pass a string of fields each optionally suffixed with
:ascor:desc, or an array that the SDK joins into one, for example'createdAt:desc'.
Sample code
1
Response
1{
2 "status": 200,
3 "data": [
4 {
5 "id": "user-alice",
6 "entityClass": "User",
7 "entityClassVersion": 1,
8 "entityClassLevel": "Global",
9 "payload": { "name": "Alice", "type": "shopper" },
10 "createdAt": "2026-07-13T09:00:00.000Z",
11 "updatedAt": "2026-07-13T09:00:00.000Z",
12 "eTag": "AbCdEfGhIjKlMn"
13 }
14 ],
15 "meta": {
show all 20 linesOther examples
Filter with filterFast
filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path. It shares the same expression language as filter, so only one of the two can be sent per call.
1
Filter with filter
filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path. It shares the same expression language as filterFast, so only one of the two can be sent per call.
1
Page through results with cursor
Pass no cursor on the first call. Take getPage()->getNextCursor() from the result and pass it back as cursor on the next call. Stop when getPage()->hasNext() is false.
1
Set user
Replaces a user in full (PUT). Send the complete set of fields, any field you omit is cleared. entityClass is immutable after creation and cannot be sent. Refer to optimistic concurrency with ETags for ifMatchesETag. For a partial update, use Update user.
Method(s)
1$pubnub->dataSync()->setUser()
2 ->userId(string)
3 ->entityClassVersion(int)
4 ->status(string)
5 ->payload(array)
6 ->ifMatchesETag(string)
7 ->sync(); // PNDataSyncUserResult
userIdrequired#- User identifier.
entityClassVersionrequired#- Version of the user class schema.
status#- Free-form lifecycle status. Max 100 characters.
payload#- Free-form JSON object holding your application data.
ifMatchesETag#- The
ETagfrom a prior read. The update succeeds only if it still matches, otherwise the server returns412.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "user-alice",
5 "entityClass": "User",
6 "entityClassVersion": 1,
7 "entityClassLevel": "Global",
8 "payload": { "name": "Alice B.", "type": "shopper" },
9 "createdAt": "2026-07-13T09:00:00.000Z",
10 "updatedAt": "2026-07-13T10:15:00.000Z",
11 "eTag": "CdEfGhIjKlMnOp"
12 }
13}
Update user
Applies a partial update to a user with raw JSON Patch operations. Refer to partial update for the operation model.
Method(s)
1$pubnub->dataSync()->updateUser()
2 ->userId(string)
3 ->patch(PNDataSyncPatch|array)
4 ->ifMatchesETag(string)
5 ->sync(); // PNDataSyncUserResult
userIdrequired#- User identifier.
patchrequired#- One or more JSON Patch operations. Must contain at least one item. Pass a
PNDataSyncPatchbuilder or a raw array of RFC 6902 operations. ifMatchesETag#- The
ETagfrom a prior read. The patch succeeds only if it still matches, otherwise the server returns412.
Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "user-alice",
5 "status": "active",
6 "entityClass": "User",
7 "entityClassVersion": 1,
8 "entityClassLevel": "Global",
9 "payload": { "name": "Alice B.", "type": "shopper" },
10 "createdAt": "2026-07-13T09:00:00.000Z",
11 "updatedAt": "2026-07-13T10:20:00.000Z",
12 "eTag": "EfGhIjKlMnOpQr"
13 }
14}
Remove user
Deletes a user by userId.
Method(s)
1$pubnub->dataSync()->deleteUser()
2 ->userId(string)
3 ->ifMatchesETag(string)
4 ->sync(); // PNDataSyncDeleteResult
Sample code
1
Response
1{
2 "status": 200
3}
Channels
Channels work like users. They have no top-level name field, all application data lives in payload, and they support the same operations. Refer to channels for the concept.
A channel is an entity of the built-in Channel entity class, which the service provides at the Global class level. Subclass it with Create a new entity class to add declared properties, then pass the subclass name as entityClass.
Create channel
Creates a channel. Supply an channelId to control the identifier, or omit it to let the server generate one.
Method(s)
1$pubnub->dataSync()->createChannel()
2 ->channelId(string)
3 ->entityClass(string)
4 ->entityClassVersion(int)
5 ->entityClassLevel(string)
6 ->status(string)
7 ->payload(array)
8 ->sync(); // PNDataSyncChannelResult
channelId#- Channel identifier. Omit to let the server generate a UUID. Max 255 characters.
entityClass#- Name of the entity class this channel belongs to. Must be
Channelor one of its subclasses. Defaults toChannelon the server if omitted. Set at creation and immutable afterward. entityClassVersionrequired#- Version of the channel class schema.
entityClassLevel#- Class hierarchy level of
entityClass, eitherGlobalfor a class the service provides orSubKeyfor one defined on your keyset. Used to disambiguate classes with the same name defined at different levels. Set at creation and immutable afterward. status#- Free-form lifecycle status. Max 100 characters.
payload#- Free-form JSON object holding your application data.
Sample code
1
Response
1{
2 "status": 201,
3 "data": {
4 "id": "channel-summer-sale",
5 "entityClass": "Channel",
6 "entityClassVersion": 1,
7 "entityClassLevel": "Global",
8 "payload": { "name": "Summer Sale", "type": "promotion" },
9 "createdAt": "2026-07-13T09:05:00.000Z",
10 "updatedAt": "2026-07-13T09:05:00.000Z",
11 "eTag": "GhIjKlMnOpQrSt"
12 }
13}
Get channel
Returns a single channel by channelId.
Method(s)
1$pubnub->dataSync()->getChannel()
2 ->channelId(string)
3 ->sync(); // PNDataSyncChannelResult
channelIdrequired#- Channel identifier.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "channel-summer-sale",
5 "entityClass": "Channel",
6 "entityClassVersion": 1,
7 "entityClassLevel": "Global",
8 "payload": { "name": "Summer Sale", "type": "promotion" },
9 "createdAt": "2026-07-13T09:05:00.000Z",
10 "updatedAt": "2026-07-13T09:05:00.000Z",
11 "eTag": "GhIjKlMnOpQrSt"
12 }
13}
Get all channels
Returns a paginated list of channels. All parameters are optional, so you can call getChannels and finish with sync() straight away. For pagination, filtering, and sorting, refer to sorting and pagination.
Method(s)
1$pubnub->dataSync()->getChannels()
2 ->entityClass(string)
3 ->entityClassVersion(int)
4 ->entityClassLevel(string)
5 ->cursor(string)
6 ->limit(int)
7 ->filterFast(string)
8 ->filter(string)
9 ->sort(string|array)
10 ->sync(); // PNDataSyncChannelsResult
entityClass#- Channel class to list. Omit to list the Global
Channelclass and all of its subclasses. entityClassVersion#- Channel class version to list. Omit to list channels across every version of the class.
entityClassLevel#- Class hierarchy level of
entityClass, eitherGlobalfor a class the service provides orSubKeyfor one defined on your keyset. Used to disambiguate a class name defined at both levels. cursor#- Opaque pagination cursor. Omit for the first page.
limit#- Maximum number of channels per page. Max
100. filterFast#- Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode
simpleorfull. Cannot be combined withfilter. filter#- Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode
full. Cannot be combined withfilterFast. sort#- Order results. Pass a string of fields each optionally suffixed with
:ascor:desc, or an array that the SDK joins into one.
Sample code
1
Response
1{
2 "status": 200,
3 "data": [
4 {
5 "id": "channel-summer-sale",
6 "entityClass": "Channel",
7 "entityClassVersion": 1,
8 "entityClassLevel": "Global",
9 "payload": { "name": "Summer Sale", "type": "promotion" },
10 "createdAt": "2026-07-13T09:05:00.000Z",
11 "updatedAt": "2026-07-13T09:05:00.000Z",
12 "eTag": "GhIjKlMnOpQrSt"
13 }
14 ],
15 "meta": {
show all 20 linesOther examples
Filter with filterFast
filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path. It shares the same expression language as filter, so only one of the two can be sent per call.
1
Filter with filter
filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path. It shares the same expression language as filterFast, so only one of the two can be sent per call.
1
Page through results with cursor
Pass no cursor on the first call. Take getPage()->getNextCursor() from the result and pass it back as cursor on the next call. Stop when getPage()->hasNext() is false.
1
Set channel
Replaces a channel in full (PUT). Send the complete set of fields, any field you omit is cleared. entityClass is immutable after creation and cannot be sent. Refer to optimistic concurrency with ETags for ifMatchesETag. For a partial update, use Update channel.
Method(s)
1$pubnub->dataSync()->setChannel()
2 ->channelId(string)
3 ->entityClassVersion(int)
4 ->status(string)
5 ->payload(array)
6 ->ifMatchesETag(string)
7 ->sync(); // PNDataSyncChannelResult
channelIdrequired#- Channel identifier.
entityClassVersionrequired#- Version of the channel class schema.
status#- Free-form lifecycle status. Max 100 characters.
payload#- Free-form JSON object holding your application data.
ifMatchesETag#- The
ETagfrom a prior read. The update succeeds only if it still matches, otherwise the server returns412.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "channel-summer-sale",
5 "entityClass": "Channel",
6 "entityClassVersion": 1,
7 "entityClassLevel": "Global",
8 "payload": { "name": "Summer Sale 2026", "type": "promotion" },
9 "createdAt": "2026-07-13T09:05:00.000Z",
10 "updatedAt": "2026-07-13T11:00:00.000Z",
11 "eTag": "IjKlMnOpQrStUv"
12 }
13}
Update channel
Applies a partial update to a channel with raw JSON Patch operations. Refer to partial update for the operation model.
Method(s)
1$pubnub->dataSync()->updateChannel()
2 ->channelId(string)
3 ->patch(PNDataSyncPatch|array)
4 ->ifMatchesETag(string)
5 ->sync(); // PNDataSyncChannelResult
channelIdrequired#- Channel identifier.
patchrequired#- One or more JSON Patch operations. Must contain at least one item. Pass a
PNDataSyncPatchbuilder or a raw array of RFC 6902 operations. ifMatchesETag#- The
ETagfrom a prior read. The patch succeeds only if it still matches, otherwise the server returns412.
Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "channel-summer-sale",
5 "status": "active",
6 "entityClass": "Channel",
7 "entityClassVersion": 1,
8 "entityClassLevel": "Global",
9 "payload": { "name": "Summer Sale 2026", "type": "promotion" },
10 "createdAt": "2026-07-13T09:05:00.000Z",
11 "updatedAt": "2026-07-13T11:05:00.000Z",
12 "eTag": "KlMnOpQrStUvWx"
13 }
14}
Remove channel
Deletes a channel by channelId.
Method(s)
1$pubnub->dataSync()->deleteChannel()
2 ->channelId(string)
3 ->ifMatchesETag(string)
4 ->sync(); // PNDataSyncDeleteResult
Sample code
1
Response
1{
2 "status": 200
3}
Memberships
A membership links a user to a channel and carries its own payload. In the running example, Alice is a member of channel-summer-sale with the payload { "role": "viewer" }. Refer to memberships for the concept.
A membership is a relationship of the built-in Global Membership relationship class, whose two sides are surfaced as channelId and userId. Every membership response includes both relationshipClass and relationshipClassVersion. The class is assigned by the service, so the createMembership and setMembership methods take no class parameter.
Relationship classes don't support inheritance, and only the Global Membership class produces memberships, so relationshipClass is always Membership and relationshipClassVersion is the only part that varies.
Create membership
Creates a membership linking a user to a channel. The userId/channelId pair must be unique for the membership class. A membership that duplicates an existing pair is rejected with a 409.
Method(s)
1$pubnub->dataSync()->createMembership()
2 ->membershipId(string)
3 ->channelId(string)
4 ->userId(string)
5 ->relationshipClassVersion(int)
6 ->status(string)
7 ->payload(array)
8 ->sync(); // PNDataSyncMembershipResult
membershipId#- Membership identifier. Omit to let the server generate a UUID. Max 255 characters.
channelIdrequired#- Identifier of the channel in the membership.
userIdrequired#- Identifier of the user in the membership.
relationshipClassVersionrequired#- Version of the Membership relationship class schema.
status#- Free-form lifecycle status. Max 100 characters.
payload#- Free-form JSON object holding your application data.
Sample code
1
Response
1{
2 "status": 201,
3 "data": {
4 "id": "membership-alice-summer-sale",
5 "channelId": "channel-summer-sale",
6 "userId": "user-alice",
7 "relationshipClass": "Membership",
8 "relationshipClassVersion": 1,
9 "payload": { "role": "viewer" },
10 "createdAt": "2026-07-13T09:10:00.000Z",
11 "updatedAt": "2026-07-13T09:10:00.000Z",
12 "eTag": "MnOpQrStUvWxYz"
13 }
14}
Get membership
Returns a single membership by membershipId.
Method(s)
1$pubnub->dataSync()->getMembership()
2 ->membershipId(string)
3 ->sync(); // PNDataSyncMembershipResult
membershipIdrequired#- Membership identifier.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "membership-alice-summer-sale",
5 "channelId": "channel-summer-sale",
6 "userId": "user-alice",
7 "relationshipClass": "Membership",
8 "relationshipClassVersion": 1,
9 "payload": { "role": "viewer" },
10 "createdAt": "2026-07-13T09:10:00.000Z",
11 "updatedAt": "2026-07-13T09:10:00.000Z",
12 "eTag": "MnOpQrStUvWxYz"
13 }
14}
Get all memberships
Returns a paginated list of memberships. All parameters are optional, so you can call getMemberships and finish with sync() straight away. userId and channelId can be set independently, together, or omitted entirely. Filter by userId to list a user's memberships or by channelId to list a channel's members. For pagination, filtering, and sorting, refer to sorting and pagination.
Method(s)
1$pubnub->dataSync()->getMemberships()
2 ->userId(string)
3 ->channelId(string)
4 ->relationshipClassVersion(int)
5 ->cursor(string)
6 ->limit(int)
7 ->filterFast(string)
8 ->filter(string)
9 ->sort(string|array)
10 ->sync(); // PNDataSyncMembershipsResult
userId#- List only memberships for this user.
channelId#- List only memberships for this channel.
relationshipClassVersion#- Membership class version to list. Omit to list memberships across every version of the class.
cursor#- Opaque pagination cursor. Omit for the first page.
limit#- Maximum number of memberships per page. Max
100. filterFast#- Filter expression evaluated against strongly consistent storage, so it reflects the latest writes. Accepts up to 10 conditions by default (raisable per keyset), over properties declared with filtering mode
simpleorfull. Cannot be combined withfilter. filter#- Filter expression evaluated against eventually consistent storage, so results can briefly lag writes. Supports the full expression language, over properties declared with filtering mode
full. Cannot be combined withfilterFast. sort#- Order results. Pass a string of fields each optionally suffixed with
:ascor:desc, or an array that the SDK joins into one.
Sample code
1
Response
1{
2 "status": 200,
3 "data": [
4 {
5 "id": "membership-alice-summer-sale",
6 "channelId": "channel-summer-sale",
7 "userId": "user-alice",
8 "relationshipClass": "Membership",
9 "relationshipClassVersion": 1,
10 "payload": { "role": "viewer" },
11 "createdAt": "2026-07-13T09:10:00.000Z",
12 "updatedAt": "2026-07-13T09:10:00.000Z",
13 "eTag": "MnOpQrStUvWxYz"
14 }
15 ],
show all 21 linesOther examples
List a channel's members with channelId
Pass channelId instead of userId to list the members of a channel rather than a user's memberships.
1
Filter with filterFast
filterFast is evaluated against strongly consistent storage, so it matches an object you just wrote. It runs over properties declared with filtering mode simple or full and accepts up to 10 conditions by default (raisable per keyset). Reference a declared property by its name, not its path. It shares the same expression language as filter, so only one of the two can be sent per call.
1
Filter with filter
filter runs over properties declared with filtering mode full and is evaluated against eventually consistent storage, so a very recent write may not be matched yet. Reference a declared property by its name, not its path. It shares the same expression language as filterFast, so only one of the two can be sent per call.
1
Page through results with cursor
Pass no cursor on the first call. Take getPage()->getNextCursor() from the result and pass it back as cursor on the next call. Stop when getPage()->hasNext() is false.
1
Set membership
Replaces a membership in full (PUT). Send the complete set of fields, any field you omit is cleared. The linked user and channel ids are immutable, so setMembership doesn't expose userId/channelId at all, there's nothing to resend. Refer to optimistic concurrency with ETags for ifMatchesETag. For a partial update, use Update membership.
Method(s)
1$pubnub->dataSync()->setMembership()
2 ->membershipId(string)
3 ->relationshipClassVersion(int)
4 ->status(string)
5 ->payload(array)
6 ->ifMatchesETag(string)
7 ->sync(); // PNDataSyncMembershipResult
membershipIdrequired#- Membership identifier.
relationshipClassVersionrequired#- Version of the Membership relationship class schema.
status#- Free-form lifecycle status. Max 100 characters.
payload#- Free-form JSON object holding your application data.
ifMatchesETag#- The
ETagfrom a prior read. The update succeeds only if it still matches, otherwise the server returns412.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "membership-alice-summer-sale",
5 "channelId": "channel-summer-sale",
6 "userId": "user-alice",
7 "relationshipClass": "Membership",
8 "relationshipClassVersion": 1,
9 "payload": { "role": "moderator" },
10 "createdAt": "2026-07-13T09:10:00.000Z",
11 "updatedAt": "2026-07-13T12:00:00.000Z",
12 "eTag": "OpQrStUvWxYzAb"
13 }
14}
Update membership
Applies a partial update to a membership with raw JSON Patch operations. Refer to partial update for the operation model.
Method(s)
1$pubnub->dataSync()->updateMembership()
2 ->membershipId(string)
3 ->patch(PNDataSyncPatch|array)
4 ->ifMatchesETag(string)
5 ->sync(); // PNDataSyncMembershipResult
membershipIdrequired#- Membership identifier.
patchrequired#- One or more JSON Patch operations. Must contain at least one item. Pass a
PNDataSyncPatchbuilder or a raw array of RFC 6902 operations. ifMatchesETag#- The
ETagfrom a prior read. The patch succeeds only if it still matches, otherwise the server returns412.
Use a JSON Pointer that starts with /payload/ to target payload fields, or a root pointer (for example /status) to target a top-level field.
Sample code
1
Response
1{
2 "status": 200,
3 "data": {
4 "id": "membership-alice-summer-sale",
5 "status": "active",
6 "channelId": "channel-summer-sale",
7 "userId": "user-alice",
8 "relationshipClass": "Membership",
9 "relationshipClassVersion": 1,
10 "payload": { "role": "moderator" },
11 "createdAt": "2026-07-13T09:10:00.000Z",
12 "updatedAt": "2026-07-13T12:05:00.000Z",
13 "eTag": "QrStUvWxYzAbCd"
14 }
15}
Remove membership
Deletes a membership by membershipId.
Method(s)
1$pubnub->dataSync()->deleteMembership()
2 ->membershipId(string)
3 ->ifMatchesETag(string)
4 ->sync(); // PNDataSyncDeleteResult
Sample code
1
Response
1{
2 "status": 200
3}
Entities
Entities are instances of the custom entity classes you define on your keyset. In the running example, product is a class and product-sneaker-42 is an instance. Use Create a new entity class to declare a class, and Get entity class by ID to read the property, filtering, and projection declarations that govern its instances.
Entity classes can extend one another. Listing a class also returns the entities of its subclasses, so getEntities()->entityClass('product') returns every product plus every instance of a class that extends product.
Create entity
Creates an entity of a given class and version.
Method(s)
1$pubnub->dataSync()->createEntity()
2 ->entityId(string)
3 ->entityClass(string)
4 ->entityClassVersion(int)
5 ->entityClassLevel(string)
6 ->status(string)
7 ->payload(array)
8 ->sync(); // PNDataSyncEntityResult
entityId#- Entity identifier. Omit to let the server generate a UUID. Max 255 characters.
entityClassrequired#- Name of the entity class this instance belongs to. Set at creation and immutable afterward.
entityClassVersionrequired#- Version of the entity class schema.
entityClassLevel#- Class hierarchy level of
entityClass, eitherGlobalfor a class the service provides orSubKeyfor one defined on your keyset. Used to disambiguate classes with the same name defined at different levels. Set at creation and immutable afterward. status#- Free-form lifecycle status. Max 100 characters.
payload#- Free-form JSON object holding your application data.