Skip to content

Commit 5ceaa20

Browse files
mogitaclaude
mogita
and
claude
committed
feat: add migration guide for messages and reactions
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 8447bda commit 5ceaa20

1 file changed

Lines changed: 397 additions & 0 deletions

File tree

‎docs/migration-to-getstream-php/04-messages-and-reactions.md‎

Lines changed: 397 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,397 @@
1+
# Messages and Reactions
2+
3+
This guide covers migrating messaging and reaction operations from `stream-chat-php` to `getstream-php`.
4+
5+
> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup.
6+
7+
## Sending a Message
8+
9+
**Before (stream-chat-php):**
10+
11+
```php
12+
use GetStream\StreamChat\Client;
13+
14+
$client = new Client("<api-key>", "<api-secret>");
15+
16+
$channel = $client->Channel('messaging', 'general');
17+
$response = $channel->sendMessage(
18+
['text' => 'Hello, world!'],
19+
'user-1',
20+
);
21+
```
22+
23+
**After (getstream-php):**
24+
25+
```php
26+
use GetStream\ClientBuilder;
27+
use GetStream\GeneratedModels;
28+
29+
$client = ClientBuilder::fromEnv()->build();
30+
31+
$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest(
32+
message: new GeneratedModels\MessageRequest(
33+
text: 'Hello, world!',
34+
userID: 'user-1',
35+
),
36+
));
37+
```
38+
39+
**Key differences:**
40+
41+
- The old SDK calls `sendMessage()` on a `Channel` object, passing the user ID as a separate argument. The new SDK calls `sendMessage()` on the client with channel type and ID, wrapping the message in a typed `SendMessageRequest`.
42+
- The user ID moves from a standalone parameter into the `MessageRequest` as `userID`.
43+
- Message properties change from snake_case array keys to camelCase named arguments.
44+
45+
## Sending a Message with Options
46+
47+
**Before (stream-chat-php):**
48+
49+
```php
50+
use GetStream\StreamChat\Client;
51+
52+
$client = new Client("<api-key>", "<api-secret>");
53+
54+
$channel = $client->Channel('messaging', 'general');
55+
$response = $channel->sendMessage(
56+
[
57+
'text' => 'Hello!',
58+
'custom_field' => 'value',
59+
],
60+
'user-1',
61+
null, // parentId
62+
['skip_push' => true],
63+
);
64+
```
65+
66+
**After (getstream-php):**
67+
68+
```php
69+
use GetStream\ClientBuilder;
70+
use GetStream\GeneratedModels;
71+
72+
$client = ClientBuilder::fromEnv()->build();
73+
74+
$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest(
75+
message: new GeneratedModels\MessageRequest(
76+
text: 'Hello!',
77+
userID: 'user-1',
78+
custom: (object) ['custom_field' => 'value'],
79+
),
80+
skipPush: true,
81+
));
82+
```
83+
84+
**Key differences:**
85+
86+
- Options like `skip_push` become named arguments on `SendMessageRequest` instead of a separate options array.
87+
- Custom fields go into the `custom` property (cast to `(object)`) on `MessageRequest`, rather than being mixed in with the top-level message array.
88+
89+
## Replying to a Message (Threads)
90+
91+
**Before (stream-chat-php):**
92+
93+
```php
94+
use GetStream\StreamChat\Client;
95+
96+
$client = new Client("<api-key>", "<api-secret>");
97+
98+
$channel = $client->Channel('messaging', 'general');
99+
100+
// Reply in a thread
101+
$response = $channel->sendMessage(
102+
['text' => 'This is a thread reply'],
103+
'user-1',
104+
'parent-message-id',
105+
);
106+
107+
// Reply in a thread and show in channel
108+
$response = $channel->sendMessage(
109+
['text' => 'This reply also appears in the channel', 'show_in_channel' => true],
110+
'user-1',
111+
'parent-message-id',
112+
);
113+
```
114+
115+
**After (getstream-php):**
116+
117+
```php
118+
use GetStream\ClientBuilder;
119+
use GetStream\GeneratedModels;
120+
121+
$client = ClientBuilder::fromEnv()->build();
122+
123+
// Reply in a thread
124+
$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest(
125+
message: new GeneratedModels\MessageRequest(
126+
text: 'This is a thread reply',
127+
userID: 'user-1',
128+
parentID: 'parent-message-id',
129+
),
130+
));
131+
132+
// Reply in a thread and show in channel
133+
$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest(
134+
message: new GeneratedModels\MessageRequest(
135+
text: 'This reply also appears in the channel',
136+
userID: 'user-1',
137+
parentID: 'parent-message-id',
138+
showInChannel: true,
139+
),
140+
));
141+
```
142+
143+
**Key differences:**
144+
145+
- The old SDK passes `parentId` as a separate third argument to `sendMessage()`. The new SDK sets `parentID` directly on the `MessageRequest`.
146+
- `show_in_channel` moves from the message array into the typed `showInChannel` named argument on `MessageRequest`.
147+
148+
## Getting a Message
149+
150+
**Before (stream-chat-php):**
151+
152+
```php
153+
use GetStream\StreamChat\Client;
154+
155+
$client = new Client("<api-key>", "<api-secret>");
156+
157+
$response = $client->getMessage('message-id-123');
158+
```
159+
160+
**After (getstream-php):**
161+
162+
```php
163+
use GetStream\ClientBuilder;
164+
165+
$client = ClientBuilder::fromEnv()->build();
166+
167+
$response = $client->getMessage('message-id-123', showDeletedMessage: false);
168+
```
169+
170+
**Key differences:**
171+
172+
- Both SDKs call `getMessage()` on the client. The new SDK adds a required `showDeletedMessage` boolean parameter.
173+
174+
## Updating a Message
175+
176+
**Before (stream-chat-php):**
177+
178+
```php
179+
use GetStream\StreamChat\Client;
180+
181+
$client = new Client("<api-key>", "<api-secret>");
182+
183+
$response = $client->updateMessage([
184+
'id' => 'message-id-123',
185+
'text' => 'Updated message text',
186+
'user_id' => 'user-1',
187+
]);
188+
```
189+
190+
**After (getstream-php):**
191+
192+
```php
193+
use GetStream\ClientBuilder;
194+
use GetStream\GeneratedModels;
195+
196+
$client = ClientBuilder::fromEnv()->build();
197+
198+
$response = $client->updateMessage('message-id-123', new GeneratedModels\UpdateMessageRequest(
199+
message: new GeneratedModels\MessageRequest(
200+
text: 'Updated message text',
201+
userID: 'user-1',
202+
),
203+
));
204+
```
205+
206+
**Key differences:**
207+
208+
- The old SDK passes a flat array with the message `id` included in it. The new SDK passes the message ID as the first argument and the update data as a typed `UpdateMessageRequest`.
209+
- The message ID is no longer part of the message body; it is a separate parameter.
210+
211+
### Partial Update
212+
213+
The new SDK also supports partial message updates, which the old SDK does not have as a dedicated method.
214+
215+
**After (getstream-php):**
216+
217+
```php
218+
use GetStream\ClientBuilder;
219+
use GetStream\GeneratedModels;
220+
221+
$client = ClientBuilder::fromEnv()->build();
222+
223+
$response = $client->updateMessagePartial('message-id-123', new GeneratedModels\UpdateMessagePartialRequest(
224+
set: (object) ['text' => 'Partially updated text', 'color' => 'blue'],
225+
unset: ['old_field'],
226+
userID: 'user-1',
227+
));
228+
```
229+
230+
## Deleting a Message
231+
232+
**Before (stream-chat-php):**
233+
234+
```php
235+
use GetStream\StreamChat\Client;
236+
237+
$client = new Client("<api-key>", "<api-secret>");
238+
239+
// Soft delete
240+
$response = $client->deleteMessage('message-id-123');
241+
242+
// Hard delete
243+
$response = $client->deleteMessage('message-id-123', ['hard' => true]);
244+
```
245+
246+
**After (getstream-php):**
247+
248+
```php
249+
use GetStream\ClientBuilder;
250+
251+
$client = ClientBuilder::fromEnv()->build();
252+
253+
// Soft delete
254+
$response = $client->deleteMessage('message-id-123', hard: false, deletedBy: '', deleteForMe: false);
255+
256+
// Hard delete
257+
$response = $client->deleteMessage('message-id-123', hard: true, deletedBy: '', deleteForMe: false);
258+
```
259+
260+
**Key differences:**
261+
262+
- The old SDK accepts an optional options array for `hard` delete. The new SDK uses explicit named parameters: `hard`, `deletedBy`, and `deleteForMe`.
263+
- The new SDK adds `deletedBy` (to attribute deletion to a specific user) and `deleteForMe` (to delete only for the requesting user), which were not available in the old SDK.
264+
265+
## Sending a Reaction
266+
267+
**Before (stream-chat-php):**
268+
269+
```php
270+
use GetStream\StreamChat\Client;
271+
272+
$client = new Client("<api-key>", "<api-secret>");
273+
274+
$channel = $client->Channel('messaging', 'general');
275+
$response = $channel->sendReaction(
276+
'message-id-123',
277+
['type' => 'like'],
278+
'user-1',
279+
);
280+
281+
// With a score
282+
$response = $channel->sendReaction(
283+
'message-id-123',
284+
['type' => 'like', 'score' => 5],
285+
'user-1',
286+
);
287+
```
288+
289+
**After (getstream-php):**
290+
291+
```php
292+
use GetStream\ClientBuilder;
293+
use GetStream\GeneratedModels;
294+
295+
$client = ClientBuilder::fromEnv()->build();
296+
297+
$response = $client->sendReaction('message-id-123', new GeneratedModels\SendReactionRequest(
298+
reaction: new GeneratedModels\ReactionRequest(
299+
type: 'like',
300+
userID: 'user-1',
301+
),
302+
));
303+
304+
// With a score
305+
$response = $client->sendReaction('message-id-123', new GeneratedModels\SendReactionRequest(
306+
reaction: new GeneratedModels\ReactionRequest(
307+
type: 'like',
308+
score: 5,
309+
userID: 'user-1',
310+
),
311+
));
312+
```
313+
314+
**Key differences:**
315+
316+
- The old SDK calls `sendReaction()` on a `Channel` object with the reaction as a flat array and user ID as a separate argument. The new SDK calls `sendReaction()` on the client with a typed `SendReactionRequest` wrapping a `ReactionRequest`.
317+
- The user ID moves from a standalone parameter into the `ReactionRequest` as `userID`.
318+
- The new SDK adds `enforceUnique` on `SendReactionRequest` to replace all existing reactions by the user, and `skipPush` to suppress push notifications.
319+
320+
## Listing Reactions
321+
322+
**Before (stream-chat-php):**
323+
324+
```php
325+
use GetStream\StreamChat\Client;
326+
327+
$client = new Client("<api-key>", "<api-secret>");
328+
329+
$channel = $client->Channel('messaging', 'general');
330+
331+
// Get reactions for a message
332+
$response = $channel->getReactions('message-id-123');
333+
334+
// With pagination
335+
$response = $channel->getReactions('message-id-123', ['limit' => 10, 'offset' => 0]);
336+
```
337+
338+
**After (getstream-php):**
339+
340+
```php
341+
use GetStream\ClientBuilder;
342+
343+
$client = ClientBuilder::fromEnv()->build();
344+
345+
// Get reactions for a message
346+
$response = $client->getReactions('message-id-123', limit: 25, offset: 0);
347+
348+
// With pagination
349+
$response = $client->getReactions('message-id-123', limit: 10, offset: 0);
350+
```
351+
352+
**Key differences:**
353+
354+
- The old SDK calls `getReactions()` on a `Channel` object with an optional options array. The new SDK calls `getReactions()` on the client with explicit `limit` and `offset` named parameters.
355+
- Pagination parameters are no longer bundled in an associative array.
356+
357+
## Deleting a Reaction
358+
359+
**Before (stream-chat-php):**
360+
361+
```php
362+
use GetStream\StreamChat\Client;
363+
364+
$client = new Client("<api-key>", "<api-secret>");
365+
366+
$channel = $client->Channel('messaging', 'general');
367+
$response = $channel->deleteReaction('message-id-123', 'like', 'user-1');
368+
```
369+
370+
**After (getstream-php):**
371+
372+
```php
373+
use GetStream\ClientBuilder;
374+
375+
$client = ClientBuilder::fromEnv()->build();
376+
377+
$response = $client->deleteReaction('message-id-123', type: 'like', userID: 'user-1');
378+
```
379+
380+
**Key differences:**
381+
382+
- The old SDK calls `deleteReaction()` on a `Channel` object. The new SDK calls it on the client directly.
383+
- The parameters are the same (message ID, reaction type, user ID), but the new SDK uses named arguments.
384+
385+
## Summary of Method Changes
386+
387+
| Operation | stream-chat-php | getstream-php |
388+
|-----------|-----------------|---------------|
389+
| Send message | `$channel->sendMessage($msg, $userId)` | `$client->sendMessage($type, $id, new SendMessageRequest(...))` |
390+
| Send thread reply | `$channel->sendMessage($msg, $userId, $parentId)` | `$client->sendMessage($type, $id, new SendMessageRequest(message: new MessageRequest(parentID: ...)))` |
391+
| Get message | `$client->getMessage($id)` | `$client->getMessage($id, showDeletedMessage: false)` |
392+
| Update message | `$client->updateMessage($msg)` | `$client->updateMessage($id, new UpdateMessageRequest(...))` |
393+
| Partial update message | _(not available)_ | `$client->updateMessagePartial($id, new UpdateMessagePartialRequest(...))` |
394+
| Delete message | `$client->deleteMessage($id, $opts)` | `$client->deleteMessage($id, hard: false, deletedBy: '', deleteForMe: false)` |
395+
| Send reaction | `$channel->sendReaction($msgId, $reaction, $userId)` | `$client->sendReaction($msgId, new SendReactionRequest(...))` |
396+
| List reactions | `$channel->getReactions($msgId, $opts)` | `$client->getReactions($msgId, limit: 25, offset: 0)` |
397+
| Delete reaction | `$channel->deleteReaction($msgId, $type, $userId)` | `$client->deleteReaction($msgId, type: $type, userID: $userId)` |

0 commit comments

Comments
 (0)