From 78174a061c05453211ffd7929de9ecfb032d0542 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:41:56 +0100 Subject: [PATCH 1/9] feat: add migration guide for client setup and authentication Co-Authored-By: Claude Opus 4.6 --- .../01-setup-and-auth.md | 178 ++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 docs/migration-to-getstream-php/01-setup-and-auth.md diff --git a/docs/migration-to-getstream-php/01-setup-and-auth.md b/docs/migration-to-getstream-php/01-setup-and-auth.md new file mode 100644 index 0000000..0c1f63d --- /dev/null +++ b/docs/migration-to-getstream-php/01-setup-and-auth.md @@ -0,0 +1,178 @@ +# Setup and Authentication + +This guide covers migrating client setup, configuration, and token generation from `stream-chat-php` to `getstream-php`. + +## Installation + +**Before (stream-chat-php):** + +```bash +composer require get-stream/stream-chat +``` + +**After (getstream-php):** + +```bash +composer require getstream/getstream-php +``` + +## Client Instantiation + +### Direct Constructor + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// With optional timeout (seconds) +$client = new Client("", "", timeout: 5.0); +``` + +**After (getstream-php):** + +```php +use GetStream\Client; + +$client = new Client( + apiKey: "", + apiSecret: "", +); + +// With optional base URL or custom HTTP client +$client = new Client( + apiKey: "", + apiSecret: "", + baseUrl: "https://chat.stream-io-api.com", +); +``` + +### ClientBuilder (New) + +The new SDK introduces a `ClientBuilder` with a fluent interface. This pattern has no equivalent in the old SDK. + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +// Build from environment variables (STREAM_API_KEY, STREAM_API_SECRET, STREAM_BASE_URL) +$client = ClientBuilder::fromEnv()->build(); + +// Build from a custom .env file path +$client = ClientBuilder::fromEnv('/path/to/.env')->build(); + +// Mix environment and explicit values +$client = ClientBuilder::fromEnv() + ->apiKey("") + ->apiSecret("") + ->baseUrl("") + ->build(); + +// Skip .env file loading entirely +$client = ClientBuilder::fromEnv() + ->skipEnvLoad() + ->apiKey("") + ->apiSecret("") + ->build(); +``` + +### Environment Variables + +The environment variable names have changed: + +| Purpose | stream-chat-php | getstream-php | +|---------|-----------------|---------------| +| API Key | `STREAM_KEY` | `STREAM_API_KEY` | +| API Secret | `STREAM_SECRET` | `STREAM_API_SECRET` | +| Base URL | `STREAM_CHAT_URL`, `STREAM_BASE_CHAT_URL`, or `STREAM_BASE_URL` | `STREAM_BASE_URL` | +| Timeout | `STREAM_CHAT_TIMEOUT` | _(configure via HTTP client)_ | + +## Namespace Changes + +Update your `use` statements: + +| Purpose | stream-chat-php | getstream-php | +|---------|-----------------|---------------| +| Client | `GetStream\StreamChat\Client` | `GetStream\Client` | +| Chat Client | _(same class)_ | `GetStream\ChatClient` | +| Builder | _(none)_ | `GetStream\ClientBuilder` | + +`ChatClient` extends `Client` and adds all chat-specific methods via `ChatTrait`. For chat operations, you can use either `Client` or `ChatClient` directly. + +## User Token Generation + +### Token Without Expiration + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); +$token = $client->createToken("user-id-123"); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); +$token = $client->createUserToken("user-id-123"); +``` + +### Token With Expiration + +The expiration parameter changed from an absolute Unix timestamp to a relative duration in seconds. + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Expiration is an absolute Unix timestamp +$expiration = time() + 3600; // 1 hour from now +$token = $client->createToken("user-id-123", $expiration); + +// With both expiration and issued-at +$issuedAt = time(); +$expiration = $issuedAt + 3600; +$token = $client->createToken("user-id-123", $expiration, $issuedAt); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +// Expiration is a duration in seconds (relative, not absolute) +$token = $client->createUserToken( + userId: "user-id-123", + expiration: 3600, // expires 1 hour from now +); + +// With additional custom claims +$token = $client->createUserToken( + userId: "user-id-123", + claims: ['role' => 'admin'], + expiration: 3600, +); +``` + +> **Important:** In `stream-chat-php`, `createToken()` expects an absolute Unix timestamp for expiration. In `getstream-php`, `createUserToken()` expects a duration in seconds. If you are computing `time() + 3600` in your old code, simply pass `3600` to the new SDK. + +## Summary of Method Changes + +| Operation | stream-chat-php | getstream-php | +|-----------|-----------------|---------------| +| Create client | `new Client($key, $secret)` | `new Client(apiKey: $key, apiSecret: $secret)` or `ClientBuilder::fromEnv()->build()` | +| Generate user token | `$client->createToken($userId)` | `$client->createUserToken($userId)` | +| Token with expiry | `$client->createToken($userId, time() + 3600)` | `$client->createUserToken($userId, expiration: 3600)` | +| Token with claims | _(not supported)_ | `$client->createUserToken($userId, claims: [...])` | From 7c92fbe5790ae6e61ef46375254e9d085f06f6f6 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:45:16 +0100 Subject: [PATCH 2/9] feat: create migration guide for user management operations Co-Authored-By: Claude Opus 4.6 --- docs/migration-to-getstream-php/02-users.md | 409 ++++++++++++++++++++ 1 file changed, 409 insertions(+) create mode 100644 docs/migration-to-getstream-php/02-users.md diff --git a/docs/migration-to-getstream-php/02-users.md b/docs/migration-to-getstream-php/02-users.md new file mode 100644 index 0000000..5d779ea --- /dev/null +++ b/docs/migration-to-getstream-php/02-users.md @@ -0,0 +1,409 @@ +# Users + +This guide covers migrating user management operations from `stream-chat-php` to `getstream-php`. + +> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. + +## Upsert a Single User + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->upsertUser([ + 'id' => 'user-123', + 'name' => 'John Doe', + 'role' => 'admin', + 'custom_field' => 'value', +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateUsers(new GeneratedModels\UpdateUsersRequest( + users: [ + 'user-123' => new GeneratedModels\UserRequest( + id: 'user-123', + name: 'John Doe', + role: 'admin', + custom: (object) ['custom_field' => 'value'], + ), + ], +)); + +$user = $response->getData()->users['user-123']; +``` + +**Key differences:** + +- The old SDK accepts a flat associative array. The new SDK uses typed `UserRequest` model objects. +- Custom fields are placed in the `custom` property (cast to `object`) instead of being mixed into the top-level array. +- The `users` parameter is keyed by user ID. +- There is no dedicated `upsertUser()` method in the new SDK. Use `updateUsers()` with a single entry. + +## Batch Upsert Users + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->upsertUsers([ + ['id' => 'user-1', 'name' => 'Alice'], + ['id' => 'user-2', 'name' => 'Bob'], +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateUsers(new GeneratedModels\UpdateUsersRequest( + users: [ + 'user-1' => new GeneratedModels\UserRequest( + id: 'user-1', + name: 'Alice', + ), + 'user-2' => new GeneratedModels\UserRequest( + id: 'user-2', + name: 'Bob', + ), + ], +)); + +$users = $response->getData()->users; +``` + +**Key differences:** + +- The old SDK takes a plain array of user arrays and indexes them by ID internally. The new SDK requires you to key the array by user ID yourself. + +## Query Users + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Query by ID +$response = $client->queryUsers( + ['id' => ['$in' => ['user-1', 'user-2']]], +); + +// With sort and pagination +$response = $client->queryUsers( + ['role' => 'admin'], + ['last_active' => -1], // sort descending + ['limit' => 10, 'offset' => 0], +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Query by ID +$response = $client->queryUsers(new GeneratedModels\QueryUsersPayload( + filterConditions: (object) [ + 'id' => (object) ['$in' => ['user-1', 'user-2']], + ], +)); + +// With sort and pagination +$response = $client->queryUsers(new GeneratedModels\QueryUsersPayload( + filterConditions: (object) ['role' => (object) ['$eq' => 'admin']], + sort: [ + new GeneratedModels\SortParamRequest( + field: 'last_active', + direction: -1, + ), + ], + limit: 10, + offset: 0, +)); + +$users = $response->getData()->users; +``` + +**Key differences:** + +- Filter conditions must be cast to `(object)`. The old SDK accepts plain associative arrays. +- Sort is now an array of `SortParamRequest` objects instead of an associative array. +- Pagination options (`limit`, `offset`) are named parameters on the payload instead of a separate `$options` array. +- To include deactivated users, pass `includeDeactivatedUsers: true` on the payload. + +## Partial Update Users + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Set and unset fields +$response = $client->partialUpdateUser([ + 'id' => 'user-123', + 'set' => ['name' => 'Jane Doe', 'country' => 'NL'], + 'unset' => ['custom_field'], +]); + +// Batch partial update +$response = $client->partialUpdateUsers([ + [ + 'id' => 'user-1', + 'set' => ['role' => 'admin'], + ], + [ + 'id' => 'user-2', + 'set' => ['role' => 'user'], + ], +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Set and unset fields +$response = $client->updateUsersPartial(new GeneratedModels\UpdateUsersPartialRequest( + users: [ + new GeneratedModels\UpdateUserPartialRequest( + id: 'user-123', + set: (object) ['name' => 'Jane Doe', 'country' => 'NL'], + unset: ['custom_field'], + ), + ], +)); + +// Batch partial update +$response = $client->updateUsersPartial(new GeneratedModels\UpdateUsersPartialRequest( + users: [ + new GeneratedModels\UpdateUserPartialRequest( + id: 'user-1', + set: (object) ['role' => 'admin'], + ), + new GeneratedModels\UpdateUserPartialRequest( + id: 'user-2', + set: (object) ['role' => 'user'], + ), + ], +)); +``` + +**Key differences:** + +- Method renamed from `partialUpdateUser()` / `partialUpdateUsers()` to `updateUsersPartial()`. +- The `set` property must be cast to `(object)`. +- Both single and batch updates use the same `updateUsersPartial()` method with an array of `UpdateUserPartialRequest` objects. + +## Deactivate and Reactivate Users + +### Single User + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Deactivate +$response = $client->deactivateUser('user-123', [ + 'mark_messages_deleted' => true, + 'created_by_id' => 'admin-user', +]); + +// Reactivate +$response = $client->reactivateUser('user-123', [ + 'restore_messages' => true, + 'created_by_id' => 'admin-user', +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Deactivate +$response = $client->deactivateUser('user-123', new GeneratedModels\DeactivateUserRequest( + markMessagesDeleted: true, + createdByID: 'admin-user', +)); + +// Reactivate +$response = $client->reactivateUser('user-123', new GeneratedModels\ReactivateUserRequest( + restoreMessages: true, + createdByID: 'admin-user', +)); +``` + +### Batch (Async) + +Both SDKs support batch deactivation/reactivation as asynchronous operations that return a task ID. + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Batch deactivate +$response = $client->deactivateUsers(['user-1', 'user-2'], [ + 'mark_messages_deleted' => true, + 'created_by_id' => 'admin-user', +]); + +// Batch reactivate +$response = $client->reactivateUsers(['user-1', 'user-2'], [ + 'restore_messages' => true, + 'created_by_id' => 'admin-user', +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Batch deactivate +$response = $client->deactivateUsers(new GeneratedModels\DeactivateUsersRequest( + userIds: ['user-1', 'user-2'], + markMessagesDeleted: true, + createdByID: 'admin-user', +)); +$taskId = $response->getData()->taskID; + +// Batch reactivate +$response = $client->reactivateUsers(new GeneratedModels\ReactivateUsersRequest( + userIds: ['user-1', 'user-2'], + restoreMessages: true, + createdByID: 'admin-user', +)); +$taskId = $response->getData()->taskID; +``` + +**Key differences:** + +- Option keys changed from snake_case strings to camelCase named arguments (e.g. `mark_messages_deleted` becomes `markMessagesDeleted`). +- Options are passed as typed request objects instead of associative arrays. +- The method signatures are otherwise very similar between the two SDKs. + +## Delete Users + +### Single User (Sync) + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->deleteUser('user-123', [ + 'mark_messages_deleted' => true, +]); +``` + +**After (getstream-php):** + +The new SDK does not have a synchronous single-user delete. Use `deleteUsers()` with a single user ID instead: + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->deleteUsers(new GeneratedModels\DeleteUsersRequest( + userIds: ['user-123'], + user: 'soft', + messages: 'soft', +)); +$taskId = $response->getData()->taskID; +``` + +### Batch Delete (Async) + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->deleteUsers(['user-1', 'user-2'], [ + 'user' => 'hard', + 'messages' => 'hard', + 'conversations' => 'hard', +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->deleteUsers(new GeneratedModels\DeleteUsersRequest( + userIds: ['user-1', 'user-2'], + user: 'hard', + messages: 'hard', + conversations: 'hard', +)); +$taskId = $response->getData()->taskID; +``` + +**Key differences:** + +- The old SDK has both `deleteUser()` (sync, single user) and `deleteUsers()` (async, batch). The new SDK only has `deleteUsers()`, which is always async. +- Options are passed as named arguments on a typed request object instead of an associative array. + +## Summary of Method Changes + +| Operation | stream-chat-php | getstream-php | +|-----------|-----------------|---------------| +| Upsert user(s) | `$client->upsertUser($user)` / `$client->upsertUsers($users)` | `$client->updateUsers(new UpdateUsersRequest(...))` | +| Query users | `$client->queryUsers($filter, $sort, $options)` | `$client->queryUsers(new QueryUsersPayload(...))` | +| Partial update | `$client->partialUpdateUser($update)` / `$client->partialUpdateUsers($updates)` | `$client->updateUsersPartial(new UpdateUsersPartialRequest(...))` | +| Deactivate (single) | `$client->deactivateUser($id, $opts)` | `$client->deactivateUser($id, new DeactivateUserRequest(...))` | +| Deactivate (batch) | `$client->deactivateUsers($ids, $opts)` | `$client->deactivateUsers(new DeactivateUsersRequest(...))` | +| Reactivate (single) | `$client->reactivateUser($id, $opts)` | `$client->reactivateUser($id, new ReactivateUserRequest(...))` | +| Reactivate (batch) | `$client->reactivateUsers($ids, $opts)` | `$client->reactivateUsers(new ReactivateUsersRequest(...))` | +| Delete (single, sync) | `$client->deleteUser($id, $opts)` | _(use `deleteUsers()` with one ID)_ | +| Delete (batch, async) | `$client->deleteUsers($ids, $opts)` | `$client->deleteUsers(new DeleteUsersRequest(...))` | From 8447bdab7fdc78f014e2be5c82cec161aad4555c Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:48:07 +0100 Subject: [PATCH 3/9] feat: create migration guide for channels (CHA-2589) Co-Authored-By: Claude Opus 4.6 --- .../migration-to-getstream-php/03-channels.md | 545 ++++++++++++++++++ 1 file changed, 545 insertions(+) create mode 100644 docs/migration-to-getstream-php/03-channels.md diff --git a/docs/migration-to-getstream-php/03-channels.md b/docs/migration-to-getstream-php/03-channels.md new file mode 100644 index 0000000..cab810f --- /dev/null +++ b/docs/migration-to-getstream-php/03-channels.md @@ -0,0 +1,545 @@ +# Channels + +This guide covers migrating channel operations from `stream-chat-php` to `getstream-php`. + +> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. + +## Channel Type Creation + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->createChannelType([ + 'name' => 'support', + 'typing_events' => true, + 'read_events' => true, + 'connect_events' => true, + 'search' => true, + 'reactions' => true, + 'replies' => true, + 'mutes' => true, + 'commands' => ['all'], +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->createChannelType(new GeneratedModels\CreateChannelTypeRequest( + name: 'support', + typingEvents: true, + readEvents: true, + connectEvents: true, + search: true, + reactions: true, + replies: true, + mutes: true, + commands: ['all'], +)); +``` + +**Key differences:** + +- The old SDK accepts a flat associative array. The new SDK uses a typed `CreateChannelTypeRequest` with named arguments. +- Option keys change from snake_case strings to camelCase named arguments. +- The old SDK defaults `commands` to `['all']` if not provided. The new SDK does not auto-set this. + +## Listing Channel Types + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->listChannelTypes(); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->listChannelTypes(); +``` + +**Key differences:** + +- The method name and signature are identical. No changes needed. + +## Getting a Channel Type + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->getChannelType('support'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->getChannelType('support'); +``` + +**Key differences:** + +- The method name and signature are identical. No changes needed. + +## Updating a Channel Type + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->updateChannelType('support', [ + 'typing_events' => false, + 'read_events' => true, + 'replies' => false, +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateChannelType('support', new GeneratedModels\UpdateChannelTypeRequest( + typingEvents: false, + readEvents: true, + replies: false, +)); +``` + +**Key differences:** + +- Settings change from a flat associative array to a typed `UpdateChannelTypeRequest` with named arguments. + +## Deleting a Channel Type + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->deleteChannelType('support'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->deleteChannelType('support'); +``` + +**Key differences:** + +- The method name and signature are identical. No changes needed. + +## Creating a Channel with Members + +In the old SDK, you create a `Channel` object on the client and then call `create()` on it. In the new SDK, you call `getOrCreateChannel()` directly on the client. + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->create('admin-user', ['user-1', 'user-2']); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->getOrCreateChannel('messaging', 'general', new GeneratedModels\ChannelGetOrCreateRequest( + data: new GeneratedModels\ChannelInput( + createdByID: 'admin-user', + members: [ + new GeneratedModels\ChannelMemberRequest(userID: 'user-1'), + new GeneratedModels\ChannelMemberRequest(userID: 'user-2'), + ], + ), +)); +``` + +**Key differences:** + +- The old SDK uses a two-step pattern: `$client->Channel()` returns a `Channel` object, then `$channel->create()` creates it. The new SDK uses a single `getOrCreateChannel()` call. +- Members are `ChannelMemberRequest` objects (with optional `channelRole` and `custom` properties) instead of plain user ID strings. +- The creating user is specified via `createdByID` on `ChannelInput` rather than as the first argument to `create()`. + +### Creating a Distinct Channel (Without an ID) + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Pass null as the channel ID to create a distinct channel based on members +$channel = $client->Channel('messaging', null, ['members' => ['user-1', 'user-2']]); +$response = $channel->create('user-1'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Use getOrCreateDistinctChannel (no channel ID needed) +$response = $client->getOrCreateDistinctChannel('messaging', new GeneratedModels\ChannelGetOrCreateRequest( + data: new GeneratedModels\ChannelInput( + createdByID: 'user-1', + members: [ + new GeneratedModels\ChannelMemberRequest(userID: 'user-1'), + new GeneratedModels\ChannelMemberRequest(userID: 'user-2'), + ], + ), +)); +``` + +**Key differences:** + +- The old SDK passes `null` as the channel ID and includes members in the data array. The new SDK has a dedicated `getOrCreateDistinctChannel()` method that omits the channel ID parameter entirely. + +## Adding Members + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->addMembers(['user-3', 'user-4']); + +// With options (e.g. hide history) +$response = $channel->addMembers(['user-5'], [ + 'hide_history' => true, +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( + addMembers: [ + new GeneratedModels\ChannelMemberRequest(userID: 'user-3'), + new GeneratedModels\ChannelMemberRequest(userID: 'user-4'), + ], +)); + +// With options (e.g. hide history) +$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( + addMembers: [ + new GeneratedModels\ChannelMemberRequest(userID: 'user-5'), + ], + hideHistory: true, +)); +``` + +**Key differences:** + +- The old SDK calls `addMembers()` on a `Channel` object with an array of user ID strings. The new SDK calls `updateChannel()` on the client with `addMembers` containing `ChannelMemberRequest` objects. +- Options like `hide_history` become named arguments on the `UpdateChannelRequest`. + +## Removing Members + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->removeMembers(['user-3', 'user-4']); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( + removeMembers: ['user-3', 'user-4'], +)); +``` + +**Key differences:** + +- The old SDK calls `removeMembers()` on a `Channel` object. The new SDK passes `removeMembers` as a named argument to `updateChannel()`. +- Unlike `addMembers`, `removeMembers` takes plain user ID strings in both SDKs. + +## Querying Channels + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Basic query +$response = $client->queryChannels( + ['type' => 'messaging', 'members' => ['$in' => ['user-1']]], +); + +// With sort and pagination +$response = $client->queryChannels( + ['type' => 'messaging'], + ['last_message_at' => -1], + ['limit' => 10, 'offset' => 0], +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Basic query +$response = $client->queryChannels(new GeneratedModels\QueryChannelsRequest( + filterConditions: (object) [ + 'type' => 'messaging', + 'members' => (object) ['$in' => ['user-1']], + ], +)); + +// With sort and pagination +$response = $client->queryChannels(new GeneratedModels\QueryChannelsRequest( + filterConditions: (object) ['type' => 'messaging'], + sort: [ + new GeneratedModels\SortParamRequest( + field: 'last_message_at', + direction: -1, + ), + ], + limit: 10, + offset: 0, +)); + +$channels = $response->getData()->channels; +``` + +**Key differences:** + +- Filter conditions must be cast to `(object)`. The old SDK accepts plain associative arrays. +- Sort is now an array of `SortParamRequest` objects instead of an associative array. +- Pagination options (`limit`, `offset`) are named parameters on the request instead of a separate `$options` array. +- The old SDK auto-sets `state`, `watch`, and `presence` defaults. The new SDK leaves them as null unless explicitly provided. + +## Updating a Channel + +### Full Update + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->update( + ['name' => 'General Chat', 'image' => 'https://example.com/img.png'], + ['text' => 'Channel updated', 'user_id' => 'admin-user'], +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( + message: new GeneratedModels\MessageRequest( + text: 'Channel updated', + userID: 'admin-user', + ), +)); +``` + +> **Note:** In the new SDK, channel data fields like `name` and `image` are not set via `updateChannel()`. Use `updateChannelPartial()` (see below) to update individual channel properties, or pass a `data` parameter with a `ChannelInput` if a full overwrite is needed. + +### Partial Update + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->updatePartial( + ['name' => 'Updated Name', 'color' => 'blue'], // set + ['old_field'], // unset +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateChannelPartial('messaging', 'general', new GeneratedModels\UpdateChannelPartialRequest( + set: (object) ['name' => 'Updated Name', 'color' => 'blue'], + unset: ['old_field'], +)); +``` + +**Key differences:** + +- The old SDK calls `updatePartial()` on a `Channel` object with positional `$set` and `$unset` arrays. The new SDK calls `updateChannelPartial()` on the client with a typed request object. +- The `set` property must be cast to `(object)`. + +## Deleting Channels + +### Single Channel + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->delete(); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->deleteChannel('messaging', 'general', hardDelete: false); +``` + +**Key differences:** + +- The old SDK calls `delete()` on a `Channel` object. The new SDK calls `deleteChannel()` on the client with the channel type and ID as arguments. +- The new SDK requires an explicit `hardDelete` boolean parameter. + +### Batch Delete + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->deleteChannels(['messaging:general', 'messaging:support']); + +// Hard delete +$response = $client->deleteChannels( + ['messaging:general', 'messaging:support'], + ['hard_delete' => true], +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->deleteChannels(new GeneratedModels\DeleteChannelsRequest( + cids: ['messaging:general', 'messaging:support'], +)); + +// Hard delete +$response = $client->deleteChannels(new GeneratedModels\DeleteChannelsRequest( + cids: ['messaging:general', 'messaging:support'], + hardDelete: true, +)); +``` + +**Key differences:** + +- The old SDK takes a plain array of CIDs and an optional options array. The new SDK uses a typed `DeleteChannelsRequest` with named arguments. + +## Summary of Method Changes + +| Operation | stream-chat-php | getstream-php | +|-----------|-----------------|---------------| +| Create channel type | `$client->createChannelType($data)` | `$client->createChannelType(new CreateChannelTypeRequest(...))` | +| List channel types | `$client->listChannelTypes()` | `$client->listChannelTypes()` | +| Get channel type | `$client->getChannelType($name)` | `$client->getChannelType($name)` | +| Update channel type | `$client->updateChannelType($name, $settings)` | `$client->updateChannelType($name, new UpdateChannelTypeRequest(...))` | +| Delete channel type | `$client->deleteChannelType($name)` | `$client->deleteChannelType($name)` | +| Create channel | `$client->Channel($type, $id)->create($userId, $members)` | `$client->getOrCreateChannel($type, $id, new ChannelGetOrCreateRequest(...))` | +| Create distinct channel | `$client->Channel($type, null, $data)->create($userId)` | `$client->getOrCreateDistinctChannel($type, new ChannelGetOrCreateRequest(...))` | +| Add members | `$channel->addMembers($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(addMembers: [...]))` | +| Remove members | `$channel->removeMembers($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(removeMembers: [...]))` | +| Query channels | `$client->queryChannels($filter, $sort, $opts)` | `$client->queryChannels(new QueryChannelsRequest(...))` | +| Update channel | `$channel->update($data, $message)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(...))` | +| Partial update channel | `$channel->updatePartial($set, $unset)` | `$client->updateChannelPartial($type, $id, new UpdateChannelPartialRequest(...))` | +| Delete channel | `$channel->delete()` | `$client->deleteChannel($type, $id, hardDelete: false)` | +| Batch delete channels | `$client->deleteChannels($cids, $opts)` | `$client->deleteChannels(new DeleteChannelsRequest(...))` | From 5ceaa20611803bb5dfc496cf0db48de11db1da52 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:50:47 +0100 Subject: [PATCH 4/9] feat: add migration guide for messages and reactions Co-Authored-By: Claude Opus 4.6 --- .../04-messages-and-reactions.md | 397 ++++++++++++++++++ 1 file changed, 397 insertions(+) create mode 100644 docs/migration-to-getstream-php/04-messages-and-reactions.md diff --git a/docs/migration-to-getstream-php/04-messages-and-reactions.md b/docs/migration-to-getstream-php/04-messages-and-reactions.md new file mode 100644 index 0000000..acb82c4 --- /dev/null +++ b/docs/migration-to-getstream-php/04-messages-and-reactions.md @@ -0,0 +1,397 @@ +# Messages and Reactions + +This guide covers migrating messaging and reaction operations from `stream-chat-php` to `getstream-php`. + +> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. + +## Sending a Message + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->sendMessage( + ['text' => 'Hello, world!'], + 'user-1', +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( + message: new GeneratedModels\MessageRequest( + text: 'Hello, world!', + userID: 'user-1', + ), +)); +``` + +**Key differences:** + +- 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`. +- The user ID moves from a standalone parameter into the `MessageRequest` as `userID`. +- Message properties change from snake_case array keys to camelCase named arguments. + +## Sending a Message with Options + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->sendMessage( + [ + 'text' => 'Hello!', + 'custom_field' => 'value', + ], + 'user-1', + null, // parentId + ['skip_push' => true], +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( + message: new GeneratedModels\MessageRequest( + text: 'Hello!', + userID: 'user-1', + custom: (object) ['custom_field' => 'value'], + ), + skipPush: true, +)); +``` + +**Key differences:** + +- Options like `skip_push` become named arguments on `SendMessageRequest` instead of a separate options array. +- Custom fields go into the `custom` property (cast to `(object)`) on `MessageRequest`, rather than being mixed in with the top-level message array. + +## Replying to a Message (Threads) + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); + +// Reply in a thread +$response = $channel->sendMessage( + ['text' => 'This is a thread reply'], + 'user-1', + 'parent-message-id', +); + +// Reply in a thread and show in channel +$response = $channel->sendMessage( + ['text' => 'This reply also appears in the channel', 'show_in_channel' => true], + 'user-1', + 'parent-message-id', +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Reply in a thread +$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( + message: new GeneratedModels\MessageRequest( + text: 'This is a thread reply', + userID: 'user-1', + parentID: 'parent-message-id', + ), +)); + +// Reply in a thread and show in channel +$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( + message: new GeneratedModels\MessageRequest( + text: 'This reply also appears in the channel', + userID: 'user-1', + parentID: 'parent-message-id', + showInChannel: true, + ), +)); +``` + +**Key differences:** + +- The old SDK passes `parentId` as a separate third argument to `sendMessage()`. The new SDK sets `parentID` directly on the `MessageRequest`. +- `show_in_channel` moves from the message array into the typed `showInChannel` named argument on `MessageRequest`. + +## Getting a Message + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->getMessage('message-id-123'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->getMessage('message-id-123', showDeletedMessage: false); +``` + +**Key differences:** + +- Both SDKs call `getMessage()` on the client. The new SDK adds a required `showDeletedMessage` boolean parameter. + +## Updating a Message + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->updateMessage([ + 'id' => 'message-id-123', + 'text' => 'Updated message text', + 'user_id' => 'user-1', +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateMessage('message-id-123', new GeneratedModels\UpdateMessageRequest( + message: new GeneratedModels\MessageRequest( + text: 'Updated message text', + userID: 'user-1', + ), +)); +``` + +**Key differences:** + +- 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`. +- The message ID is no longer part of the message body; it is a separate parameter. + +### Partial Update + +The new SDK also supports partial message updates, which the old SDK does not have as a dedicated method. + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateMessagePartial('message-id-123', new GeneratedModels\UpdateMessagePartialRequest( + set: (object) ['text' => 'Partially updated text', 'color' => 'blue'], + unset: ['old_field'], + userID: 'user-1', +)); +``` + +## Deleting a Message + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Soft delete +$response = $client->deleteMessage('message-id-123'); + +// Hard delete +$response = $client->deleteMessage('message-id-123', ['hard' => true]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +// Soft delete +$response = $client->deleteMessage('message-id-123', hard: false, deletedBy: '', deleteForMe: false); + +// Hard delete +$response = $client->deleteMessage('message-id-123', hard: true, deletedBy: '', deleteForMe: false); +``` + +**Key differences:** + +- The old SDK accepts an optional options array for `hard` delete. The new SDK uses explicit named parameters: `hard`, `deletedBy`, and `deleteForMe`. +- 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. + +## Sending a Reaction + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->sendReaction( + 'message-id-123', + ['type' => 'like'], + 'user-1', +); + +// With a score +$response = $channel->sendReaction( + 'message-id-123', + ['type' => 'like', 'score' => 5], + 'user-1', +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->sendReaction('message-id-123', new GeneratedModels\SendReactionRequest( + reaction: new GeneratedModels\ReactionRequest( + type: 'like', + userID: 'user-1', + ), +)); + +// With a score +$response = $client->sendReaction('message-id-123', new GeneratedModels\SendReactionRequest( + reaction: new GeneratedModels\ReactionRequest( + type: 'like', + score: 5, + userID: 'user-1', + ), +)); +``` + +**Key differences:** + +- 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`. +- The user ID moves from a standalone parameter into the `ReactionRequest` as `userID`. +- The new SDK adds `enforceUnique` on `SendReactionRequest` to replace all existing reactions by the user, and `skipPush` to suppress push notifications. + +## Listing Reactions + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); + +// Get reactions for a message +$response = $channel->getReactions('message-id-123'); + +// With pagination +$response = $channel->getReactions('message-id-123', ['limit' => 10, 'offset' => 0]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +// Get reactions for a message +$response = $client->getReactions('message-id-123', limit: 25, offset: 0); + +// With pagination +$response = $client->getReactions('message-id-123', limit: 10, offset: 0); +``` + +**Key differences:** + +- 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. +- Pagination parameters are no longer bundled in an associative array. + +## Deleting a Reaction + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->deleteReaction('message-id-123', 'like', 'user-1'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->deleteReaction('message-id-123', type: 'like', userID: 'user-1'); +``` + +**Key differences:** + +- The old SDK calls `deleteReaction()` on a `Channel` object. The new SDK calls it on the client directly. +- The parameters are the same (message ID, reaction type, user ID), but the new SDK uses named arguments. + +## Summary of Method Changes + +| Operation | stream-chat-php | getstream-php | +|-----------|-----------------|---------------| +| Send message | `$channel->sendMessage($msg, $userId)` | `$client->sendMessage($type, $id, new SendMessageRequest(...))` | +| Send thread reply | `$channel->sendMessage($msg, $userId, $parentId)` | `$client->sendMessage($type, $id, new SendMessageRequest(message: new MessageRequest(parentID: ...)))` | +| Get message | `$client->getMessage($id)` | `$client->getMessage($id, showDeletedMessage: false)` | +| Update message | `$client->updateMessage($msg)` | `$client->updateMessage($id, new UpdateMessageRequest(...))` | +| Partial update message | _(not available)_ | `$client->updateMessagePartial($id, new UpdateMessagePartialRequest(...))` | +| Delete message | `$client->deleteMessage($id, $opts)` | `$client->deleteMessage($id, hard: false, deletedBy: '', deleteForMe: false)` | +| Send reaction | `$channel->sendReaction($msgId, $reaction, $userId)` | `$client->sendReaction($msgId, new SendReactionRequest(...))` | +| List reactions | `$channel->getReactions($msgId, $opts)` | `$client->getReactions($msgId, limit: 25, offset: 0)` | +| Delete reaction | `$channel->deleteReaction($msgId, $type, $userId)` | `$client->deleteReaction($msgId, type: $type, userID: $userId)` | From d7eb23acf4ed009c7316dbc989614f961904f894 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:53:11 +0100 Subject: [PATCH 5/9] feat: add migration guide for moderation (CHA-2591) Covers: adding/removing moderators, banning/unbanning (app-level and channel-level), shadow banning, querying banned users, muting/unmuting users. Each section shows Before/After code blocks with key differences. Co-Authored-By: Claude Opus 4.6 --- .../05-moderation.md | 403 ++++++++++++++++++ 1 file changed, 403 insertions(+) create mode 100644 docs/migration-to-getstream-php/05-moderation.md diff --git a/docs/migration-to-getstream-php/05-moderation.md b/docs/migration-to-getstream-php/05-moderation.md new file mode 100644 index 0000000..ff75278 --- /dev/null +++ b/docs/migration-to-getstream-php/05-moderation.md @@ -0,0 +1,403 @@ +# Moderation + +This guide covers migrating moderation operations from `stream-chat-php` to `getstream-php`. + +> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. + +## Adding and Removing Moderators + +### Adding Moderators to a Channel + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->addModerators(['user-1', 'user-2']); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( + addModerators: ['user-1', 'user-2'], +)); +``` + +**Key differences:** +- Old SDK uses a dedicated `addModerators()` method on the Channel object +- New SDK uses `updateChannel()` with the `addModerators` parameter on `UpdateChannelRequest` +- No separate Channel object in the new SDK; channel type and ID are passed directly + +### Demoting Moderators + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->demoteModerators(['user-1', 'user-2']); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( + demoteModerators: ['user-1', 'user-2'], +)); +``` + +**Key differences:** +- Same pattern as adding moderators: old SDK has `demoteModerators()` on Channel, new SDK uses `updateChannel()` with `demoteModerators` parameter + +## Banning and Unbanning Users + +### App-level Ban + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Ban a user app-wide +$response = $client->banUser('bad-user', [ + 'user_id' => 'admin-user', + 'reason' => 'Spamming', + 'timeout' => 60, // minutes +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Ban a user app-wide +$response = $client->ban(new GeneratedModels\BanRequest( + targetUserID: 'bad-user', + bannedByID: 'admin-user', + reason: 'Spamming', + timeout: 60, // minutes +)); +``` + +**Key differences:** +- Old SDK: `banUser($targetId, $options)` with flat associative array options +- New SDK: `ban(BanRequest)` with typed named arguments +- `user_id` in old SDK becomes `bannedByID` in new SDK +- The new SDK method lives on the moderation trait (`$client->ban()`), not under a `banUser` name + +### Channel-level Ban + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->banUser('bad-user', [ + 'user_id' => 'admin-user', + 'reason' => 'Off-topic messages', +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->ban(new GeneratedModels\BanRequest( + targetUserID: 'bad-user', + bannedByID: 'admin-user', + reason: 'Off-topic messages', + channelCid: 'messaging:general', +)); +``` + +**Key differences:** +- Old SDK: `$channel->banUser()` automatically includes channel type/ID from the Channel object +- New SDK: use the same `ban()` method but pass `channelCid` (format: `type:id`) to scope the ban to a channel + +### Unbanning a User (App-level) + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->unbanUser('bad-user'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->unban( + targetUserID: 'bad-user', + channelCid: '', + createdBy: 'admin-user', + requestData: new GeneratedModels\UnbanRequest(), +); +``` + +**Key differences:** +- Old SDK: `unbanUser($targetId)` with optional options array +- New SDK: `unban()` requires `targetUserID`, `channelCid` (empty string for app-level), `createdBy`, and an `UnbanRequest` object +- The new SDK requires explicitly specifying who is performing the unban (`createdBy`) + +### Unbanning a User (Channel-level) + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->unbanUser('bad-user'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->unban( + targetUserID: 'bad-user', + channelCid: 'messaging:general', + createdBy: 'admin-user', + requestData: new GeneratedModels\UnbanRequest(), +); +``` + +**Key differences:** +- Old SDK: `$channel->unbanUser()` scopes the unban to the channel automatically +- New SDK: pass `channelCid` as `type:id` to scope the unban to a channel + +### Shadow Banning + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +// Shadow ban (app-level) +$response = $client->shadowBan('bad-user', [ + 'user_id' => 'admin-user', +]); + +// Remove shadow ban +$response = $client->removeShadowBan('bad-user', [ + 'user_id' => 'admin-user', +]); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +// Shadow ban (app-level) +$response = $client->ban(new GeneratedModels\BanRequest( + targetUserID: 'bad-user', + bannedByID: 'admin-user', + shadow: true, +)); + +// Remove shadow ban +$response = $client->unban( + targetUserID: 'bad-user', + channelCid: '', + createdBy: 'admin-user', + requestData: new GeneratedModels\UnbanRequest(), +); +``` + +**Key differences:** +- Old SDK has dedicated `shadowBan()` and `removeShadowBan()` methods +- New SDK uses the same `ban()` method with `shadow: true` +- Removing a shadow ban uses the same `unban()` method (no separate method needed) + +### Querying Banned Users + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->queryBannedUsers( + ['channel_cid' => 'messaging:general'], + ['limit' => 10, 'offset' => 0], +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->queryBannedUsers(new GeneratedModels\QueryBannedUsersPayload( + filterConditions: (object) ['channel_cid' => 'messaging:general'], + limit: 10, + offset: 0, +)); +``` + +**Key differences:** +- Old SDK: filter conditions and options are separate array arguments +- New SDK: everything goes into a single `QueryBannedUsersPayload` object with named arguments +- Filter conditions must be cast to `(object)` in the new SDK + +## Muting and Unmuting Users + +### Muting a User + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->muteUser('target-user', 'requesting-user'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->mute(new GeneratedModels\MuteRequest( + targetIds: ['target-user'], + userID: 'requesting-user', +)); +``` + +**Key differences:** +- Old SDK: `muteUser($targetId, $userId)` takes two string arguments +- New SDK: `mute(MuteRequest)` takes a typed request object +- New SDK accepts an array of `targetIds`, allowing you to mute multiple users in one call +- New SDK supports an optional `timeout` parameter (duration in minutes) + +### Muting a User with Timeout + +**Before (stream-chat-php):** + +```php +// The old SDK does not support mute timeouts directly. +// You would need to handle expiration on your own. +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->mute(new GeneratedModels\MuteRequest( + targetIds: ['target-user'], + userID: 'requesting-user', + timeout: 60, // mute for 60 minutes +)); +``` + +**Key differences:** +- Mute timeout is a new capability in `getstream-php` that was not available in the old SDK + +### Unmuting a User + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$response = $client->unmuteUser('target-user', 'requesting-user'); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->unmute(new GeneratedModels\UnmuteRequest( + targetIds: ['target-user'], + userID: 'requesting-user', +)); +``` + +**Key differences:** +- Old SDK: `unmuteUser($targetId, $userId)` takes two string arguments +- New SDK: `unmute(UnmuteRequest)` takes a typed request object +- New SDK accepts an array of `targetIds`, allowing you to unmute multiple users in one call + +## Summary of Method Mapping + +| Operation | stream-chat-php | getstream-php | +|---|---|---| +| Add moderators | `$channel->addModerators($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(addModerators: [...]))` | +| Demote moderators | `$channel->demoteModerators($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(demoteModerators: [...]))` | +| Ban user (app) | `$client->banUser($targetId, $opts)` | `$client->ban(new BanRequest(targetUserID: ..., ...))` | +| Ban user (channel) | `$channel->banUser($targetId, $opts)` | `$client->ban(new BanRequest(targetUserID: ..., channelCid: ..., ...))` | +| Unban user (app) | `$client->unbanUser($targetId)` | `$client->unban($targetUserID, '', $createdBy, new UnbanRequest())` | +| Unban user (channel) | `$channel->unbanUser($targetId)` | `$client->unban($targetUserID, $channelCid, $createdBy, new UnbanRequest())` | +| Shadow ban | `$client->shadowBan($targetId, $opts)` | `$client->ban(new BanRequest(targetUserID: ..., shadow: true, ...))` | +| Remove shadow ban | `$client->removeShadowBan($targetId, $opts)` | `$client->unban($targetUserID, '', $createdBy, new UnbanRequest())` | +| Query banned users | `$client->queryBannedUsers($filter, $opts)` | `$client->queryBannedUsers(new QueryBannedUsersPayload(...))` | +| Mute user | `$client->muteUser($targetId, $userId)` | `$client->mute(new MuteRequest(targetIds: [...], userID: ...))` | +| Unmute user | `$client->unmuteUser($targetId, $userId)` | `$client->unmute(new UnmuteRequest(targetIds: [...], userID: ...))` | From 0a35f46a2884ae58e48d04fc088baa560a613662 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:54:58 +0100 Subject: [PATCH 6/9] feat: add migration guide for devices (CHA-2592) Co-Authored-By: Claude Opus 4.6 --- docs/migration-to-getstream-php/06-devices.md | 140 ++++++++++++++++++ 1 file changed, 140 insertions(+) create mode 100644 docs/migration-to-getstream-php/06-devices.md diff --git a/docs/migration-to-getstream-php/06-devices.md b/docs/migration-to-getstream-php/06-devices.md new file mode 100644 index 0000000..fd9d79b --- /dev/null +++ b/docs/migration-to-getstream-php/06-devices.md @@ -0,0 +1,140 @@ +# Devices + +This guide covers migrating device management operations (push notification setup) from `stream-chat-php` to `getstream-php`. + +## Adding a Device + +### APN (Apple Push Notifications) + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$client->addDevice("device-token-abc", "apn", "user-123"); + +// With a named push provider configuration +$client->addDevice("device-token-abc", "apn", "user-123", "my-apn-provider"); +``` + +**After (getstream-php):** + +```php +use GetStream\ChatClient; +use GetStream\GeneratedModels\CreateDeviceRequest; + +$client = new ChatClient("", ""); + +$client->createDevice(new CreateDeviceRequest( + id: 'device-token-abc', + pushProvider: 'apn', + userID: 'user-123', +)); + +// With a named push provider configuration +$client->createDevice(new CreateDeviceRequest( + id: 'device-token-abc', + pushProvider: 'apn', + userID: 'user-123', + pushProviderName: 'my-apn-provider', +)); +``` + +> **Key differences:** +> - Method renamed from `addDevice()` to `createDevice()` +> - Uses a `CreateDeviceRequest` object with named arguments instead of positional string parameters +> - Push provider and user ID are properties on the request object + +### Firebase (Android Push Notifications) + +**Before (stream-chat-php):** + +```php +$client->addDevice("fcm-token-xyz", "firebase", "user-123"); + +// With a named push provider configuration +$client->addDevice("fcm-token-xyz", "firebase", "user-123", "my-firebase-provider"); +``` + +**After (getstream-php):** + +```php +use GetStream\GeneratedModels\CreateDeviceRequest; + +$client->createDevice(new CreateDeviceRequest( + id: 'fcm-token-xyz', + pushProvider: 'firebase', + userID: 'user-123', +)); + +// With a named push provider configuration +$client->createDevice(new CreateDeviceRequest( + id: 'fcm-token-xyz', + pushProvider: 'firebase', + userID: 'user-123', + pushProviderName: 'my-firebase-provider', +)); +``` + +### VoIP Token (Apple) + +The new SDK adds support for registering Apple VoIP push tokens, which was not available as a dedicated option in the old SDK. + +**After (getstream-php):** + +```php +use GetStream\GeneratedModels\CreateDeviceRequest; + +$client->createDevice(new CreateDeviceRequest( + id: 'voip-token-abc', + pushProvider: 'apn', + userID: 'user-123', + voipToken: true, +)); +``` + +## Listing Devices for a User + +**Before (stream-chat-php):** + +```php +$response = $client->getDevices("user-123"); +``` + +**After (getstream-php):** + +```php +$response = $client->listDevices('user-123'); +``` + +> **Key differences:** +> - Method renamed from `getDevices()` to `listDevices()` +> - Response is typed as `ListDevicesResponse` instead of a generic `StreamResponse` + +## Deleting a Device + +**Before (stream-chat-php):** + +```php +$client->deleteDevice("device-token-abc", "user-123"); +``` + +**After (getstream-php):** + +```php +$client->deleteDevice('device-token-abc', 'user-123'); +``` + +> **Key differences:** +> - The method signature is the same: `deleteDevice(string $id, string $userID)` +> - Parameter names changed from `$deviceId` to `$id` and `$userId` to `$userID`, but since both are positional strings this has no practical impact + +## Method Mapping Summary + +| Operation | stream-chat-php | getstream-php | +|-----------|----------------|---------------| +| Add device | `$client->addDevice($deviceId, $provider, $userId, $providerName)` | `$client->createDevice(new CreateDeviceRequest(...))` | +| List devices | `$client->getDevices($userId)` | `$client->listDevices($userID)` | +| Delete device | `$client->deleteDevice($deviceId, $userId)` | `$client->deleteDevice($id, $userID)` | From 35658861400f455f63e51f9a89190c4d1a26a28b Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:56:30 +0100 Subject: [PATCH 7/9] feat: add migration guide index with overview and quickstart (CHA-2593) Co-Authored-By: Claude Opus 4.6 --- docs/migration-to-getstream-php/README.md | 91 +++++++++++++++++++++++ 1 file changed, 91 insertions(+) create mode 100644 docs/migration-to-getstream-php/README.md diff --git a/docs/migration-to-getstream-php/README.md b/docs/migration-to-getstream-php/README.md new file mode 100644 index 0000000..2337478 --- /dev/null +++ b/docs/migration-to-getstream-php/README.md @@ -0,0 +1,91 @@ +# Migrating from stream-chat-php to getstream-php + +## Why Migrate? + +Stream has released **[getstream-php](https://github.com/GetStream/getstream-php)**, a new full-product PHP SDK that covers Chat, Video, Moderation, and Feeds in a single package. It is generated from OpenAPI specs, which means it stays up to date with the latest API features automatically. + +**getstream-php** is the long-term-supported SDK going forward. **stream-chat-php** will enter maintenance mode and continue receiving critical bug fixes, but new features and API coverage will only be added to getstream-php. + +If you are starting a new project, use **getstream-php**. If you have an existing project using stream-chat-php, we encourage you to migrate at your convenience. There is no rush, as stream-chat-php is not going away, but migrating gives you access to the latest features and the best developer experience. + +## Key Differences + +| | **stream-chat-php** | **getstream-php** | +|---|---|---| +| **Package** | `get-stream/stream-chat` | `getstream/getstream-php` | +| **Namespace** | `GetStream\StreamChat\Client` | `GetStream\Client` / `GetStream\ChatClient` | +| **Client init** | `new Client($apiKey, $apiSecret)` | `ClientBuilder::fromEnv()->build()` or `new Client(apiKey: ..., apiSecret: ...)` | +| **API style** | Associative arrays for everything | Typed model classes with named arguments | +| **Channel operations** | `$client->Channel($type, $id)->method()` | `$client->methodName($type, $id, ...)` | +| **Custom fields** | Top-level array keys | `custom: (object) [...]` property | +| **Filters / Sort** | Associative arrays | `(object)` casts and `SortParamRequest` objects | +| **Response types** | Associative arrays | Typed response objects | +| **Autoloading** | PSR-0 | PSR-4 | +| **Product coverage** | Chat only | Chat, Video, Moderation, Feeds | + +## Quick Before/After Example + +The most common operation (initialize client and send a message): + +**Before (stream-chat-php):** + +```php +use GetStream\StreamChat\Client; + +$client = new Client("", ""); + +$channel = $client->Channel('messaging', 'general'); +$response = $channel->sendMessage( + ['text' => 'Hello, world!'], + 'user-1', +); +``` + +**After (getstream-php):** + +```php +use GetStream\ClientBuilder; +use GetStream\GeneratedModels; + +$client = ClientBuilder::fromEnv()->build(); + +$response = $client->sendMessage( + 'messaging', + 'general', + new GeneratedModels\SendMessageRequest( + message: new GeneratedModels\MessageRequest( + text: 'Hello, world!', + userID: 'user-1', + ), + ), +); +``` + +## Migration Guides by Topic + +| # | Topic | Guide | +|---|-------|-------| +| 1 | Setup and Authentication | [01-setup-and-auth.md](./01-setup-and-auth.md) | +| 2 | Users | [02-users.md](./02-users.md) | +| 3 | Channels | [03-channels.md](./03-channels.md) | +| 4 | Messages and Reactions | [04-messages-and-reactions.md](./04-messages-and-reactions.md) | +| 5 | Moderation | [05-moderation.md](./05-moderation.md) | +| 6 | Devices | [06-devices.md](./06-devices.md) | + +Each guide provides side-by-side "Before" and "After" code examples for every operation, along with notes on key differences. + +## Continued Support for stream-chat-php + +stream-chat-php is not being removed or abandoned. It will continue to receive: + +- Critical bug fixes +- Security patches +- Requested features on a case-by-case basis + +However, all new API features, generated model types, and multi-product support will only be available in getstream-php. We recommend migrating when it makes sense for your project timeline. + +## Resources + +- [getstream-php on GitHub](https://github.com/GetStream/getstream-php) +- [getstream-php on Packagist](https://packagist.org/packages/getstream/getstream-php) +- [Stream Chat documentation](https://getstream.io/chat/docs/) From afb4b046410cce36fb46b2951c5a46d52c427c57 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 14:57:30 +0100 Subject: [PATCH 8/9] feat: add deprecation notice to stream-chat-php README Co-Authored-By: Claude Opus 4.6 --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index e22a436..54c9bce 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ +> **Note:** [`getstream-php`](https://github.com/GetStream/getstream-php) is the new full-product PHP SDK for Stream, covering Chat, Video, Moderation, and Feeds with long-term support. +> +> **`stream-chat-php` is now in maintenance mode.** It will continue to receive critical fixes and requested features, so it is safe to keep using. However, we encourage existing users to migrate when convenient and strongly recommend that new projects start with `getstream-php`. +> +> Already using `stream-chat-php`? See the [Migration Guide](docs/migration-to-getstream-php/README.md) for side-by-side examples covering every use case. + # Official PHP SDK for [Stream Chat](https://getstream.io/chat/) [![build](https://github.com/GetStream/stream-chat-php/workflows/build/badge.svg)](https://github.com/GetStream/stream-chat-php/actions) [![Latest Stable Version](https://poser.pugx.org/get-stream/stream-chat/v/stable)](https://packagist.org/packages/get-stream/stream-chat) From eb22452d95f38dea6bb3a61dbaf62968c27a2966 Mon Sep 17 00:00:00 2001 From: Yun Wang Date: Fri, 6 Mar 2026 15:46:04 +0100 Subject: [PATCH 9/9] chore: update link to the migration guide --- README.md | 2 +- .../01-setup-and-auth.md | 178 ------ docs/migration-to-getstream-php/02-users.md | 409 ------------- .../migration-to-getstream-php/03-channels.md | 545 ------------------ .../04-messages-and-reactions.md | 397 ------------- .../05-moderation.md | 403 ------------- docs/migration-to-getstream-php/06-devices.md | 140 ----- docs/migration-to-getstream-php/README.md | 91 --- 8 files changed, 1 insertion(+), 2164 deletions(-) delete mode 100644 docs/migration-to-getstream-php/01-setup-and-auth.md delete mode 100644 docs/migration-to-getstream-php/02-users.md delete mode 100644 docs/migration-to-getstream-php/03-channels.md delete mode 100644 docs/migration-to-getstream-php/04-messages-and-reactions.md delete mode 100644 docs/migration-to-getstream-php/05-moderation.md delete mode 100644 docs/migration-to-getstream-php/06-devices.md delete mode 100644 docs/migration-to-getstream-php/README.md diff --git a/README.md b/README.md index 54c9bce..7e53e88 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ > > **`stream-chat-php` is now in maintenance mode.** It will continue to receive critical fixes and requested features, so it is safe to keep using. However, we encourage existing users to migrate when convenient and strongly recommend that new projects start with `getstream-php`. > -> Already using `stream-chat-php`? See the [Migration Guide](docs/migration-to-getstream-php/README.md) for side-by-side examples covering every use case. +> Check out the [Migration Guide](https://github.com/GetStream/getstream-php/tree/master/docs/migration-from-stream-chat-php) for side-by-side examples covering common use cases. # Official PHP SDK for [Stream Chat](https://getstream.io/chat/) diff --git a/docs/migration-to-getstream-php/01-setup-and-auth.md b/docs/migration-to-getstream-php/01-setup-and-auth.md deleted file mode 100644 index 0c1f63d..0000000 --- a/docs/migration-to-getstream-php/01-setup-and-auth.md +++ /dev/null @@ -1,178 +0,0 @@ -# Setup and Authentication - -This guide covers migrating client setup, configuration, and token generation from `stream-chat-php` to `getstream-php`. - -## Installation - -**Before (stream-chat-php):** - -```bash -composer require get-stream/stream-chat -``` - -**After (getstream-php):** - -```bash -composer require getstream/getstream-php -``` - -## Client Instantiation - -### Direct Constructor - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// With optional timeout (seconds) -$client = new Client("", "", timeout: 5.0); -``` - -**After (getstream-php):** - -```php -use GetStream\Client; - -$client = new Client( - apiKey: "", - apiSecret: "", -); - -// With optional base URL or custom HTTP client -$client = new Client( - apiKey: "", - apiSecret: "", - baseUrl: "https://chat.stream-io-api.com", -); -``` - -### ClientBuilder (New) - -The new SDK introduces a `ClientBuilder` with a fluent interface. This pattern has no equivalent in the old SDK. - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -// Build from environment variables (STREAM_API_KEY, STREAM_API_SECRET, STREAM_BASE_URL) -$client = ClientBuilder::fromEnv()->build(); - -// Build from a custom .env file path -$client = ClientBuilder::fromEnv('/path/to/.env')->build(); - -// Mix environment and explicit values -$client = ClientBuilder::fromEnv() - ->apiKey("") - ->apiSecret("") - ->baseUrl("") - ->build(); - -// Skip .env file loading entirely -$client = ClientBuilder::fromEnv() - ->skipEnvLoad() - ->apiKey("") - ->apiSecret("") - ->build(); -``` - -### Environment Variables - -The environment variable names have changed: - -| Purpose | stream-chat-php | getstream-php | -|---------|-----------------|---------------| -| API Key | `STREAM_KEY` | `STREAM_API_KEY` | -| API Secret | `STREAM_SECRET` | `STREAM_API_SECRET` | -| Base URL | `STREAM_CHAT_URL`, `STREAM_BASE_CHAT_URL`, or `STREAM_BASE_URL` | `STREAM_BASE_URL` | -| Timeout | `STREAM_CHAT_TIMEOUT` | _(configure via HTTP client)_ | - -## Namespace Changes - -Update your `use` statements: - -| Purpose | stream-chat-php | getstream-php | -|---------|-----------------|---------------| -| Client | `GetStream\StreamChat\Client` | `GetStream\Client` | -| Chat Client | _(same class)_ | `GetStream\ChatClient` | -| Builder | _(none)_ | `GetStream\ClientBuilder` | - -`ChatClient` extends `Client` and adds all chat-specific methods via `ChatTrait`. For chat operations, you can use either `Client` or `ChatClient` directly. - -## User Token Generation - -### Token Without Expiration - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); -$token = $client->createToken("user-id-123"); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); -$token = $client->createUserToken("user-id-123"); -``` - -### Token With Expiration - -The expiration parameter changed from an absolute Unix timestamp to a relative duration in seconds. - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Expiration is an absolute Unix timestamp -$expiration = time() + 3600; // 1 hour from now -$token = $client->createToken("user-id-123", $expiration); - -// With both expiration and issued-at -$issuedAt = time(); -$expiration = $issuedAt + 3600; -$token = $client->createToken("user-id-123", $expiration, $issuedAt); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -// Expiration is a duration in seconds (relative, not absolute) -$token = $client->createUserToken( - userId: "user-id-123", - expiration: 3600, // expires 1 hour from now -); - -// With additional custom claims -$token = $client->createUserToken( - userId: "user-id-123", - claims: ['role' => 'admin'], - expiration: 3600, -); -``` - -> **Important:** In `stream-chat-php`, `createToken()` expects an absolute Unix timestamp for expiration. In `getstream-php`, `createUserToken()` expects a duration in seconds. If you are computing `time() + 3600` in your old code, simply pass `3600` to the new SDK. - -## Summary of Method Changes - -| Operation | stream-chat-php | getstream-php | -|-----------|-----------------|---------------| -| Create client | `new Client($key, $secret)` | `new Client(apiKey: $key, apiSecret: $secret)` or `ClientBuilder::fromEnv()->build()` | -| Generate user token | `$client->createToken($userId)` | `$client->createUserToken($userId)` | -| Token with expiry | `$client->createToken($userId, time() + 3600)` | `$client->createUserToken($userId, expiration: 3600)` | -| Token with claims | _(not supported)_ | `$client->createUserToken($userId, claims: [...])` | diff --git a/docs/migration-to-getstream-php/02-users.md b/docs/migration-to-getstream-php/02-users.md deleted file mode 100644 index 5d779ea..0000000 --- a/docs/migration-to-getstream-php/02-users.md +++ /dev/null @@ -1,409 +0,0 @@ -# Users - -This guide covers migrating user management operations from `stream-chat-php` to `getstream-php`. - -> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. - -## Upsert a Single User - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->upsertUser([ - 'id' => 'user-123', - 'name' => 'John Doe', - 'role' => 'admin', - 'custom_field' => 'value', -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateUsers(new GeneratedModels\UpdateUsersRequest( - users: [ - 'user-123' => new GeneratedModels\UserRequest( - id: 'user-123', - name: 'John Doe', - role: 'admin', - custom: (object) ['custom_field' => 'value'], - ), - ], -)); - -$user = $response->getData()->users['user-123']; -``` - -**Key differences:** - -- The old SDK accepts a flat associative array. The new SDK uses typed `UserRequest` model objects. -- Custom fields are placed in the `custom` property (cast to `object`) instead of being mixed into the top-level array. -- The `users` parameter is keyed by user ID. -- There is no dedicated `upsertUser()` method in the new SDK. Use `updateUsers()` with a single entry. - -## Batch Upsert Users - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->upsertUsers([ - ['id' => 'user-1', 'name' => 'Alice'], - ['id' => 'user-2', 'name' => 'Bob'], -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateUsers(new GeneratedModels\UpdateUsersRequest( - users: [ - 'user-1' => new GeneratedModels\UserRequest( - id: 'user-1', - name: 'Alice', - ), - 'user-2' => new GeneratedModels\UserRequest( - id: 'user-2', - name: 'Bob', - ), - ], -)); - -$users = $response->getData()->users; -``` - -**Key differences:** - -- The old SDK takes a plain array of user arrays and indexes them by ID internally. The new SDK requires you to key the array by user ID yourself. - -## Query Users - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Query by ID -$response = $client->queryUsers( - ['id' => ['$in' => ['user-1', 'user-2']]], -); - -// With sort and pagination -$response = $client->queryUsers( - ['role' => 'admin'], - ['last_active' => -1], // sort descending - ['limit' => 10, 'offset' => 0], -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Query by ID -$response = $client->queryUsers(new GeneratedModels\QueryUsersPayload( - filterConditions: (object) [ - 'id' => (object) ['$in' => ['user-1', 'user-2']], - ], -)); - -// With sort and pagination -$response = $client->queryUsers(new GeneratedModels\QueryUsersPayload( - filterConditions: (object) ['role' => (object) ['$eq' => 'admin']], - sort: [ - new GeneratedModels\SortParamRequest( - field: 'last_active', - direction: -1, - ), - ], - limit: 10, - offset: 0, -)); - -$users = $response->getData()->users; -``` - -**Key differences:** - -- Filter conditions must be cast to `(object)`. The old SDK accepts plain associative arrays. -- Sort is now an array of `SortParamRequest` objects instead of an associative array. -- Pagination options (`limit`, `offset`) are named parameters on the payload instead of a separate `$options` array. -- To include deactivated users, pass `includeDeactivatedUsers: true` on the payload. - -## Partial Update Users - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Set and unset fields -$response = $client->partialUpdateUser([ - 'id' => 'user-123', - 'set' => ['name' => 'Jane Doe', 'country' => 'NL'], - 'unset' => ['custom_field'], -]); - -// Batch partial update -$response = $client->partialUpdateUsers([ - [ - 'id' => 'user-1', - 'set' => ['role' => 'admin'], - ], - [ - 'id' => 'user-2', - 'set' => ['role' => 'user'], - ], -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Set and unset fields -$response = $client->updateUsersPartial(new GeneratedModels\UpdateUsersPartialRequest( - users: [ - new GeneratedModels\UpdateUserPartialRequest( - id: 'user-123', - set: (object) ['name' => 'Jane Doe', 'country' => 'NL'], - unset: ['custom_field'], - ), - ], -)); - -// Batch partial update -$response = $client->updateUsersPartial(new GeneratedModels\UpdateUsersPartialRequest( - users: [ - new GeneratedModels\UpdateUserPartialRequest( - id: 'user-1', - set: (object) ['role' => 'admin'], - ), - new GeneratedModels\UpdateUserPartialRequest( - id: 'user-2', - set: (object) ['role' => 'user'], - ), - ], -)); -``` - -**Key differences:** - -- Method renamed from `partialUpdateUser()` / `partialUpdateUsers()` to `updateUsersPartial()`. -- The `set` property must be cast to `(object)`. -- Both single and batch updates use the same `updateUsersPartial()` method with an array of `UpdateUserPartialRequest` objects. - -## Deactivate and Reactivate Users - -### Single User - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Deactivate -$response = $client->deactivateUser('user-123', [ - 'mark_messages_deleted' => true, - 'created_by_id' => 'admin-user', -]); - -// Reactivate -$response = $client->reactivateUser('user-123', [ - 'restore_messages' => true, - 'created_by_id' => 'admin-user', -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Deactivate -$response = $client->deactivateUser('user-123', new GeneratedModels\DeactivateUserRequest( - markMessagesDeleted: true, - createdByID: 'admin-user', -)); - -// Reactivate -$response = $client->reactivateUser('user-123', new GeneratedModels\ReactivateUserRequest( - restoreMessages: true, - createdByID: 'admin-user', -)); -``` - -### Batch (Async) - -Both SDKs support batch deactivation/reactivation as asynchronous operations that return a task ID. - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Batch deactivate -$response = $client->deactivateUsers(['user-1', 'user-2'], [ - 'mark_messages_deleted' => true, - 'created_by_id' => 'admin-user', -]); - -// Batch reactivate -$response = $client->reactivateUsers(['user-1', 'user-2'], [ - 'restore_messages' => true, - 'created_by_id' => 'admin-user', -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Batch deactivate -$response = $client->deactivateUsers(new GeneratedModels\DeactivateUsersRequest( - userIds: ['user-1', 'user-2'], - markMessagesDeleted: true, - createdByID: 'admin-user', -)); -$taskId = $response->getData()->taskID; - -// Batch reactivate -$response = $client->reactivateUsers(new GeneratedModels\ReactivateUsersRequest( - userIds: ['user-1', 'user-2'], - restoreMessages: true, - createdByID: 'admin-user', -)); -$taskId = $response->getData()->taskID; -``` - -**Key differences:** - -- Option keys changed from snake_case strings to camelCase named arguments (e.g. `mark_messages_deleted` becomes `markMessagesDeleted`). -- Options are passed as typed request objects instead of associative arrays. -- The method signatures are otherwise very similar between the two SDKs. - -## Delete Users - -### Single User (Sync) - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->deleteUser('user-123', [ - 'mark_messages_deleted' => true, -]); -``` - -**After (getstream-php):** - -The new SDK does not have a synchronous single-user delete. Use `deleteUsers()` with a single user ID instead: - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->deleteUsers(new GeneratedModels\DeleteUsersRequest( - userIds: ['user-123'], - user: 'soft', - messages: 'soft', -)); -$taskId = $response->getData()->taskID; -``` - -### Batch Delete (Async) - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->deleteUsers(['user-1', 'user-2'], [ - 'user' => 'hard', - 'messages' => 'hard', - 'conversations' => 'hard', -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->deleteUsers(new GeneratedModels\DeleteUsersRequest( - userIds: ['user-1', 'user-2'], - user: 'hard', - messages: 'hard', - conversations: 'hard', -)); -$taskId = $response->getData()->taskID; -``` - -**Key differences:** - -- The old SDK has both `deleteUser()` (sync, single user) and `deleteUsers()` (async, batch). The new SDK only has `deleteUsers()`, which is always async. -- Options are passed as named arguments on a typed request object instead of an associative array. - -## Summary of Method Changes - -| Operation | stream-chat-php | getstream-php | -|-----------|-----------------|---------------| -| Upsert user(s) | `$client->upsertUser($user)` / `$client->upsertUsers($users)` | `$client->updateUsers(new UpdateUsersRequest(...))` | -| Query users | `$client->queryUsers($filter, $sort, $options)` | `$client->queryUsers(new QueryUsersPayload(...))` | -| Partial update | `$client->partialUpdateUser($update)` / `$client->partialUpdateUsers($updates)` | `$client->updateUsersPartial(new UpdateUsersPartialRequest(...))` | -| Deactivate (single) | `$client->deactivateUser($id, $opts)` | `$client->deactivateUser($id, new DeactivateUserRequest(...))` | -| Deactivate (batch) | `$client->deactivateUsers($ids, $opts)` | `$client->deactivateUsers(new DeactivateUsersRequest(...))` | -| Reactivate (single) | `$client->reactivateUser($id, $opts)` | `$client->reactivateUser($id, new ReactivateUserRequest(...))` | -| Reactivate (batch) | `$client->reactivateUsers($ids, $opts)` | `$client->reactivateUsers(new ReactivateUsersRequest(...))` | -| Delete (single, sync) | `$client->deleteUser($id, $opts)` | _(use `deleteUsers()` with one ID)_ | -| Delete (batch, async) | `$client->deleteUsers($ids, $opts)` | `$client->deleteUsers(new DeleteUsersRequest(...))` | diff --git a/docs/migration-to-getstream-php/03-channels.md b/docs/migration-to-getstream-php/03-channels.md deleted file mode 100644 index cab810f..0000000 --- a/docs/migration-to-getstream-php/03-channels.md +++ /dev/null @@ -1,545 +0,0 @@ -# Channels - -This guide covers migrating channel operations from `stream-chat-php` to `getstream-php`. - -> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. - -## Channel Type Creation - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->createChannelType([ - 'name' => 'support', - 'typing_events' => true, - 'read_events' => true, - 'connect_events' => true, - 'search' => true, - 'reactions' => true, - 'replies' => true, - 'mutes' => true, - 'commands' => ['all'], -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->createChannelType(new GeneratedModels\CreateChannelTypeRequest( - name: 'support', - typingEvents: true, - readEvents: true, - connectEvents: true, - search: true, - reactions: true, - replies: true, - mutes: true, - commands: ['all'], -)); -``` - -**Key differences:** - -- The old SDK accepts a flat associative array. The new SDK uses a typed `CreateChannelTypeRequest` with named arguments. -- Option keys change from snake_case strings to camelCase named arguments. -- The old SDK defaults `commands` to `['all']` if not provided. The new SDK does not auto-set this. - -## Listing Channel Types - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->listChannelTypes(); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->listChannelTypes(); -``` - -**Key differences:** - -- The method name and signature are identical. No changes needed. - -## Getting a Channel Type - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->getChannelType('support'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->getChannelType('support'); -``` - -**Key differences:** - -- The method name and signature are identical. No changes needed. - -## Updating a Channel Type - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->updateChannelType('support', [ - 'typing_events' => false, - 'read_events' => true, - 'replies' => false, -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateChannelType('support', new GeneratedModels\UpdateChannelTypeRequest( - typingEvents: false, - readEvents: true, - replies: false, -)); -``` - -**Key differences:** - -- Settings change from a flat associative array to a typed `UpdateChannelTypeRequest` with named arguments. - -## Deleting a Channel Type - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->deleteChannelType('support'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->deleteChannelType('support'); -``` - -**Key differences:** - -- The method name and signature are identical. No changes needed. - -## Creating a Channel with Members - -In the old SDK, you create a `Channel` object on the client and then call `create()` on it. In the new SDK, you call `getOrCreateChannel()` directly on the client. - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->create('admin-user', ['user-1', 'user-2']); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->getOrCreateChannel('messaging', 'general', new GeneratedModels\ChannelGetOrCreateRequest( - data: new GeneratedModels\ChannelInput( - createdByID: 'admin-user', - members: [ - new GeneratedModels\ChannelMemberRequest(userID: 'user-1'), - new GeneratedModels\ChannelMemberRequest(userID: 'user-2'), - ], - ), -)); -``` - -**Key differences:** - -- The old SDK uses a two-step pattern: `$client->Channel()` returns a `Channel` object, then `$channel->create()` creates it. The new SDK uses a single `getOrCreateChannel()` call. -- Members are `ChannelMemberRequest` objects (with optional `channelRole` and `custom` properties) instead of plain user ID strings. -- The creating user is specified via `createdByID` on `ChannelInput` rather than as the first argument to `create()`. - -### Creating a Distinct Channel (Without an ID) - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Pass null as the channel ID to create a distinct channel based on members -$channel = $client->Channel('messaging', null, ['members' => ['user-1', 'user-2']]); -$response = $channel->create('user-1'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Use getOrCreateDistinctChannel (no channel ID needed) -$response = $client->getOrCreateDistinctChannel('messaging', new GeneratedModels\ChannelGetOrCreateRequest( - data: new GeneratedModels\ChannelInput( - createdByID: 'user-1', - members: [ - new GeneratedModels\ChannelMemberRequest(userID: 'user-1'), - new GeneratedModels\ChannelMemberRequest(userID: 'user-2'), - ], - ), -)); -``` - -**Key differences:** - -- The old SDK passes `null` as the channel ID and includes members in the data array. The new SDK has a dedicated `getOrCreateDistinctChannel()` method that omits the channel ID parameter entirely. - -## Adding Members - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->addMembers(['user-3', 'user-4']); - -// With options (e.g. hide history) -$response = $channel->addMembers(['user-5'], [ - 'hide_history' => true, -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( - addMembers: [ - new GeneratedModels\ChannelMemberRequest(userID: 'user-3'), - new GeneratedModels\ChannelMemberRequest(userID: 'user-4'), - ], -)); - -// With options (e.g. hide history) -$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( - addMembers: [ - new GeneratedModels\ChannelMemberRequest(userID: 'user-5'), - ], - hideHistory: true, -)); -``` - -**Key differences:** - -- The old SDK calls `addMembers()` on a `Channel` object with an array of user ID strings. The new SDK calls `updateChannel()` on the client with `addMembers` containing `ChannelMemberRequest` objects. -- Options like `hide_history` become named arguments on the `UpdateChannelRequest`. - -## Removing Members - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->removeMembers(['user-3', 'user-4']); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( - removeMembers: ['user-3', 'user-4'], -)); -``` - -**Key differences:** - -- The old SDK calls `removeMembers()` on a `Channel` object. The new SDK passes `removeMembers` as a named argument to `updateChannel()`. -- Unlike `addMembers`, `removeMembers` takes plain user ID strings in both SDKs. - -## Querying Channels - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Basic query -$response = $client->queryChannels( - ['type' => 'messaging', 'members' => ['$in' => ['user-1']]], -); - -// With sort and pagination -$response = $client->queryChannels( - ['type' => 'messaging'], - ['last_message_at' => -1], - ['limit' => 10, 'offset' => 0], -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Basic query -$response = $client->queryChannels(new GeneratedModels\QueryChannelsRequest( - filterConditions: (object) [ - 'type' => 'messaging', - 'members' => (object) ['$in' => ['user-1']], - ], -)); - -// With sort and pagination -$response = $client->queryChannels(new GeneratedModels\QueryChannelsRequest( - filterConditions: (object) ['type' => 'messaging'], - sort: [ - new GeneratedModels\SortParamRequest( - field: 'last_message_at', - direction: -1, - ), - ], - limit: 10, - offset: 0, -)); - -$channels = $response->getData()->channels; -``` - -**Key differences:** - -- Filter conditions must be cast to `(object)`. The old SDK accepts plain associative arrays. -- Sort is now an array of `SortParamRequest` objects instead of an associative array. -- Pagination options (`limit`, `offset`) are named parameters on the request instead of a separate `$options` array. -- The old SDK auto-sets `state`, `watch`, and `presence` defaults. The new SDK leaves them as null unless explicitly provided. - -## Updating a Channel - -### Full Update - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->update( - ['name' => 'General Chat', 'image' => 'https://example.com/img.png'], - ['text' => 'Channel updated', 'user_id' => 'admin-user'], -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( - message: new GeneratedModels\MessageRequest( - text: 'Channel updated', - userID: 'admin-user', - ), -)); -``` - -> **Note:** In the new SDK, channel data fields like `name` and `image` are not set via `updateChannel()`. Use `updateChannelPartial()` (see below) to update individual channel properties, or pass a `data` parameter with a `ChannelInput` if a full overwrite is needed. - -### Partial Update - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->updatePartial( - ['name' => 'Updated Name', 'color' => 'blue'], // set - ['old_field'], // unset -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateChannelPartial('messaging', 'general', new GeneratedModels\UpdateChannelPartialRequest( - set: (object) ['name' => 'Updated Name', 'color' => 'blue'], - unset: ['old_field'], -)); -``` - -**Key differences:** - -- The old SDK calls `updatePartial()` on a `Channel` object with positional `$set` and `$unset` arrays. The new SDK calls `updateChannelPartial()` on the client with a typed request object. -- The `set` property must be cast to `(object)`. - -## Deleting Channels - -### Single Channel - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->delete(); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->deleteChannel('messaging', 'general', hardDelete: false); -``` - -**Key differences:** - -- The old SDK calls `delete()` on a `Channel` object. The new SDK calls `deleteChannel()` on the client with the channel type and ID as arguments. -- The new SDK requires an explicit `hardDelete` boolean parameter. - -### Batch Delete - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->deleteChannels(['messaging:general', 'messaging:support']); - -// Hard delete -$response = $client->deleteChannels( - ['messaging:general', 'messaging:support'], - ['hard_delete' => true], -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->deleteChannels(new GeneratedModels\DeleteChannelsRequest( - cids: ['messaging:general', 'messaging:support'], -)); - -// Hard delete -$response = $client->deleteChannels(new GeneratedModels\DeleteChannelsRequest( - cids: ['messaging:general', 'messaging:support'], - hardDelete: true, -)); -``` - -**Key differences:** - -- The old SDK takes a plain array of CIDs and an optional options array. The new SDK uses a typed `DeleteChannelsRequest` with named arguments. - -## Summary of Method Changes - -| Operation | stream-chat-php | getstream-php | -|-----------|-----------------|---------------| -| Create channel type | `$client->createChannelType($data)` | `$client->createChannelType(new CreateChannelTypeRequest(...))` | -| List channel types | `$client->listChannelTypes()` | `$client->listChannelTypes()` | -| Get channel type | `$client->getChannelType($name)` | `$client->getChannelType($name)` | -| Update channel type | `$client->updateChannelType($name, $settings)` | `$client->updateChannelType($name, new UpdateChannelTypeRequest(...))` | -| Delete channel type | `$client->deleteChannelType($name)` | `$client->deleteChannelType($name)` | -| Create channel | `$client->Channel($type, $id)->create($userId, $members)` | `$client->getOrCreateChannel($type, $id, new ChannelGetOrCreateRequest(...))` | -| Create distinct channel | `$client->Channel($type, null, $data)->create($userId)` | `$client->getOrCreateDistinctChannel($type, new ChannelGetOrCreateRequest(...))` | -| Add members | `$channel->addMembers($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(addMembers: [...]))` | -| Remove members | `$channel->removeMembers($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(removeMembers: [...]))` | -| Query channels | `$client->queryChannels($filter, $sort, $opts)` | `$client->queryChannels(new QueryChannelsRequest(...))` | -| Update channel | `$channel->update($data, $message)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(...))` | -| Partial update channel | `$channel->updatePartial($set, $unset)` | `$client->updateChannelPartial($type, $id, new UpdateChannelPartialRequest(...))` | -| Delete channel | `$channel->delete()` | `$client->deleteChannel($type, $id, hardDelete: false)` | -| Batch delete channels | `$client->deleteChannels($cids, $opts)` | `$client->deleteChannels(new DeleteChannelsRequest(...))` | diff --git a/docs/migration-to-getstream-php/04-messages-and-reactions.md b/docs/migration-to-getstream-php/04-messages-and-reactions.md deleted file mode 100644 index acb82c4..0000000 --- a/docs/migration-to-getstream-php/04-messages-and-reactions.md +++ /dev/null @@ -1,397 +0,0 @@ -# Messages and Reactions - -This guide covers migrating messaging and reaction operations from `stream-chat-php` to `getstream-php`. - -> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. - -## Sending a Message - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->sendMessage( - ['text' => 'Hello, world!'], - 'user-1', -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( - message: new GeneratedModels\MessageRequest( - text: 'Hello, world!', - userID: 'user-1', - ), -)); -``` - -**Key differences:** - -- 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`. -- The user ID moves from a standalone parameter into the `MessageRequest` as `userID`. -- Message properties change from snake_case array keys to camelCase named arguments. - -## Sending a Message with Options - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->sendMessage( - [ - 'text' => 'Hello!', - 'custom_field' => 'value', - ], - 'user-1', - null, // parentId - ['skip_push' => true], -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( - message: new GeneratedModels\MessageRequest( - text: 'Hello!', - userID: 'user-1', - custom: (object) ['custom_field' => 'value'], - ), - skipPush: true, -)); -``` - -**Key differences:** - -- Options like `skip_push` become named arguments on `SendMessageRequest` instead of a separate options array. -- Custom fields go into the `custom` property (cast to `(object)`) on `MessageRequest`, rather than being mixed in with the top-level message array. - -## Replying to a Message (Threads) - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); - -// Reply in a thread -$response = $channel->sendMessage( - ['text' => 'This is a thread reply'], - 'user-1', - 'parent-message-id', -); - -// Reply in a thread and show in channel -$response = $channel->sendMessage( - ['text' => 'This reply also appears in the channel', 'show_in_channel' => true], - 'user-1', - 'parent-message-id', -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Reply in a thread -$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( - message: new GeneratedModels\MessageRequest( - text: 'This is a thread reply', - userID: 'user-1', - parentID: 'parent-message-id', - ), -)); - -// Reply in a thread and show in channel -$response = $client->sendMessage('messaging', 'general', new GeneratedModels\SendMessageRequest( - message: new GeneratedModels\MessageRequest( - text: 'This reply also appears in the channel', - userID: 'user-1', - parentID: 'parent-message-id', - showInChannel: true, - ), -)); -``` - -**Key differences:** - -- The old SDK passes `parentId` as a separate third argument to `sendMessage()`. The new SDK sets `parentID` directly on the `MessageRequest`. -- `show_in_channel` moves from the message array into the typed `showInChannel` named argument on `MessageRequest`. - -## Getting a Message - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->getMessage('message-id-123'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->getMessage('message-id-123', showDeletedMessage: false); -``` - -**Key differences:** - -- Both SDKs call `getMessage()` on the client. The new SDK adds a required `showDeletedMessage` boolean parameter. - -## Updating a Message - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->updateMessage([ - 'id' => 'message-id-123', - 'text' => 'Updated message text', - 'user_id' => 'user-1', -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateMessage('message-id-123', new GeneratedModels\UpdateMessageRequest( - message: new GeneratedModels\MessageRequest( - text: 'Updated message text', - userID: 'user-1', - ), -)); -``` - -**Key differences:** - -- 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`. -- The message ID is no longer part of the message body; it is a separate parameter. - -### Partial Update - -The new SDK also supports partial message updates, which the old SDK does not have as a dedicated method. - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateMessagePartial('message-id-123', new GeneratedModels\UpdateMessagePartialRequest( - set: (object) ['text' => 'Partially updated text', 'color' => 'blue'], - unset: ['old_field'], - userID: 'user-1', -)); -``` - -## Deleting a Message - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Soft delete -$response = $client->deleteMessage('message-id-123'); - -// Hard delete -$response = $client->deleteMessage('message-id-123', ['hard' => true]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -// Soft delete -$response = $client->deleteMessage('message-id-123', hard: false, deletedBy: '', deleteForMe: false); - -// Hard delete -$response = $client->deleteMessage('message-id-123', hard: true, deletedBy: '', deleteForMe: false); -``` - -**Key differences:** - -- The old SDK accepts an optional options array for `hard` delete. The new SDK uses explicit named parameters: `hard`, `deletedBy`, and `deleteForMe`. -- 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. - -## Sending a Reaction - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->sendReaction( - 'message-id-123', - ['type' => 'like'], - 'user-1', -); - -// With a score -$response = $channel->sendReaction( - 'message-id-123', - ['type' => 'like', 'score' => 5], - 'user-1', -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->sendReaction('message-id-123', new GeneratedModels\SendReactionRequest( - reaction: new GeneratedModels\ReactionRequest( - type: 'like', - userID: 'user-1', - ), -)); - -// With a score -$response = $client->sendReaction('message-id-123', new GeneratedModels\SendReactionRequest( - reaction: new GeneratedModels\ReactionRequest( - type: 'like', - score: 5, - userID: 'user-1', - ), -)); -``` - -**Key differences:** - -- 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`. -- The user ID moves from a standalone parameter into the `ReactionRequest` as `userID`. -- The new SDK adds `enforceUnique` on `SendReactionRequest` to replace all existing reactions by the user, and `skipPush` to suppress push notifications. - -## Listing Reactions - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); - -// Get reactions for a message -$response = $channel->getReactions('message-id-123'); - -// With pagination -$response = $channel->getReactions('message-id-123', ['limit' => 10, 'offset' => 0]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -// Get reactions for a message -$response = $client->getReactions('message-id-123', limit: 25, offset: 0); - -// With pagination -$response = $client->getReactions('message-id-123', limit: 10, offset: 0); -``` - -**Key differences:** - -- 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. -- Pagination parameters are no longer bundled in an associative array. - -## Deleting a Reaction - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->deleteReaction('message-id-123', 'like', 'user-1'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->deleteReaction('message-id-123', type: 'like', userID: 'user-1'); -``` - -**Key differences:** - -- The old SDK calls `deleteReaction()` on a `Channel` object. The new SDK calls it on the client directly. -- The parameters are the same (message ID, reaction type, user ID), but the new SDK uses named arguments. - -## Summary of Method Changes - -| Operation | stream-chat-php | getstream-php | -|-----------|-----------------|---------------| -| Send message | `$channel->sendMessage($msg, $userId)` | `$client->sendMessage($type, $id, new SendMessageRequest(...))` | -| Send thread reply | `$channel->sendMessage($msg, $userId, $parentId)` | `$client->sendMessage($type, $id, new SendMessageRequest(message: new MessageRequest(parentID: ...)))` | -| Get message | `$client->getMessage($id)` | `$client->getMessage($id, showDeletedMessage: false)` | -| Update message | `$client->updateMessage($msg)` | `$client->updateMessage($id, new UpdateMessageRequest(...))` | -| Partial update message | _(not available)_ | `$client->updateMessagePartial($id, new UpdateMessagePartialRequest(...))` | -| Delete message | `$client->deleteMessage($id, $opts)` | `$client->deleteMessage($id, hard: false, deletedBy: '', deleteForMe: false)` | -| Send reaction | `$channel->sendReaction($msgId, $reaction, $userId)` | `$client->sendReaction($msgId, new SendReactionRequest(...))` | -| List reactions | `$channel->getReactions($msgId, $opts)` | `$client->getReactions($msgId, limit: 25, offset: 0)` | -| Delete reaction | `$channel->deleteReaction($msgId, $type, $userId)` | `$client->deleteReaction($msgId, type: $type, userID: $userId)` | diff --git a/docs/migration-to-getstream-php/05-moderation.md b/docs/migration-to-getstream-php/05-moderation.md deleted file mode 100644 index ff75278..0000000 --- a/docs/migration-to-getstream-php/05-moderation.md +++ /dev/null @@ -1,403 +0,0 @@ -# Moderation - -This guide covers migrating moderation operations from `stream-chat-php` to `getstream-php`. - -> All `getstream-php` examples assume the client is already instantiated. See [01-setup-and-auth.md](./01-setup-and-auth.md) for client setup. - -## Adding and Removing Moderators - -### Adding Moderators to a Channel - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->addModerators(['user-1', 'user-2']); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( - addModerators: ['user-1', 'user-2'], -)); -``` - -**Key differences:** -- Old SDK uses a dedicated `addModerators()` method on the Channel object -- New SDK uses `updateChannel()` with the `addModerators` parameter on `UpdateChannelRequest` -- No separate Channel object in the new SDK; channel type and ID are passed directly - -### Demoting Moderators - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->demoteModerators(['user-1', 'user-2']); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->updateChannel('messaging', 'general', new GeneratedModels\UpdateChannelRequest( - demoteModerators: ['user-1', 'user-2'], -)); -``` - -**Key differences:** -- Same pattern as adding moderators: old SDK has `demoteModerators()` on Channel, new SDK uses `updateChannel()` with `demoteModerators` parameter - -## Banning and Unbanning Users - -### App-level Ban - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Ban a user app-wide -$response = $client->banUser('bad-user', [ - 'user_id' => 'admin-user', - 'reason' => 'Spamming', - 'timeout' => 60, // minutes -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Ban a user app-wide -$response = $client->ban(new GeneratedModels\BanRequest( - targetUserID: 'bad-user', - bannedByID: 'admin-user', - reason: 'Spamming', - timeout: 60, // minutes -)); -``` - -**Key differences:** -- Old SDK: `banUser($targetId, $options)` with flat associative array options -- New SDK: `ban(BanRequest)` with typed named arguments -- `user_id` in old SDK becomes `bannedByID` in new SDK -- The new SDK method lives on the moderation trait (`$client->ban()`), not under a `banUser` name - -### Channel-level Ban - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->banUser('bad-user', [ - 'user_id' => 'admin-user', - 'reason' => 'Off-topic messages', -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->ban(new GeneratedModels\BanRequest( - targetUserID: 'bad-user', - bannedByID: 'admin-user', - reason: 'Off-topic messages', - channelCid: 'messaging:general', -)); -``` - -**Key differences:** -- Old SDK: `$channel->banUser()` automatically includes channel type/ID from the Channel object -- New SDK: use the same `ban()` method but pass `channelCid` (format: `type:id`) to scope the ban to a channel - -### Unbanning a User (App-level) - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->unbanUser('bad-user'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->unban( - targetUserID: 'bad-user', - channelCid: '', - createdBy: 'admin-user', - requestData: new GeneratedModels\UnbanRequest(), -); -``` - -**Key differences:** -- Old SDK: `unbanUser($targetId)` with optional options array -- New SDK: `unban()` requires `targetUserID`, `channelCid` (empty string for app-level), `createdBy`, and an `UnbanRequest` object -- The new SDK requires explicitly specifying who is performing the unban (`createdBy`) - -### Unbanning a User (Channel-level) - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->unbanUser('bad-user'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->unban( - targetUserID: 'bad-user', - channelCid: 'messaging:general', - createdBy: 'admin-user', - requestData: new GeneratedModels\UnbanRequest(), -); -``` - -**Key differences:** -- Old SDK: `$channel->unbanUser()` scopes the unban to the channel automatically -- New SDK: pass `channelCid` as `type:id` to scope the unban to a channel - -### Shadow Banning - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -// Shadow ban (app-level) -$response = $client->shadowBan('bad-user', [ - 'user_id' => 'admin-user', -]); - -// Remove shadow ban -$response = $client->removeShadowBan('bad-user', [ - 'user_id' => 'admin-user', -]); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -// Shadow ban (app-level) -$response = $client->ban(new GeneratedModels\BanRequest( - targetUserID: 'bad-user', - bannedByID: 'admin-user', - shadow: true, -)); - -// Remove shadow ban -$response = $client->unban( - targetUserID: 'bad-user', - channelCid: '', - createdBy: 'admin-user', - requestData: new GeneratedModels\UnbanRequest(), -); -``` - -**Key differences:** -- Old SDK has dedicated `shadowBan()` and `removeShadowBan()` methods -- New SDK uses the same `ban()` method with `shadow: true` -- Removing a shadow ban uses the same `unban()` method (no separate method needed) - -### Querying Banned Users - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->queryBannedUsers( - ['channel_cid' => 'messaging:general'], - ['limit' => 10, 'offset' => 0], -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->queryBannedUsers(new GeneratedModels\QueryBannedUsersPayload( - filterConditions: (object) ['channel_cid' => 'messaging:general'], - limit: 10, - offset: 0, -)); -``` - -**Key differences:** -- Old SDK: filter conditions and options are separate array arguments -- New SDK: everything goes into a single `QueryBannedUsersPayload` object with named arguments -- Filter conditions must be cast to `(object)` in the new SDK - -## Muting and Unmuting Users - -### Muting a User - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->muteUser('target-user', 'requesting-user'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->mute(new GeneratedModels\MuteRequest( - targetIds: ['target-user'], - userID: 'requesting-user', -)); -``` - -**Key differences:** -- Old SDK: `muteUser($targetId, $userId)` takes two string arguments -- New SDK: `mute(MuteRequest)` takes a typed request object -- New SDK accepts an array of `targetIds`, allowing you to mute multiple users in one call -- New SDK supports an optional `timeout` parameter (duration in minutes) - -### Muting a User with Timeout - -**Before (stream-chat-php):** - -```php -// The old SDK does not support mute timeouts directly. -// You would need to handle expiration on your own. -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->mute(new GeneratedModels\MuteRequest( - targetIds: ['target-user'], - userID: 'requesting-user', - timeout: 60, // mute for 60 minutes -)); -``` - -**Key differences:** -- Mute timeout is a new capability in `getstream-php` that was not available in the old SDK - -### Unmuting a User - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$response = $client->unmuteUser('target-user', 'requesting-user'); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->unmute(new GeneratedModels\UnmuteRequest( - targetIds: ['target-user'], - userID: 'requesting-user', -)); -``` - -**Key differences:** -- Old SDK: `unmuteUser($targetId, $userId)` takes two string arguments -- New SDK: `unmute(UnmuteRequest)` takes a typed request object -- New SDK accepts an array of `targetIds`, allowing you to unmute multiple users in one call - -## Summary of Method Mapping - -| Operation | stream-chat-php | getstream-php | -|---|---|---| -| Add moderators | `$channel->addModerators($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(addModerators: [...]))` | -| Demote moderators | `$channel->demoteModerators($userIds)` | `$client->updateChannel($type, $id, new UpdateChannelRequest(demoteModerators: [...]))` | -| Ban user (app) | `$client->banUser($targetId, $opts)` | `$client->ban(new BanRequest(targetUserID: ..., ...))` | -| Ban user (channel) | `$channel->banUser($targetId, $opts)` | `$client->ban(new BanRequest(targetUserID: ..., channelCid: ..., ...))` | -| Unban user (app) | `$client->unbanUser($targetId)` | `$client->unban($targetUserID, '', $createdBy, new UnbanRequest())` | -| Unban user (channel) | `$channel->unbanUser($targetId)` | `$client->unban($targetUserID, $channelCid, $createdBy, new UnbanRequest())` | -| Shadow ban | `$client->shadowBan($targetId, $opts)` | `$client->ban(new BanRequest(targetUserID: ..., shadow: true, ...))` | -| Remove shadow ban | `$client->removeShadowBan($targetId, $opts)` | `$client->unban($targetUserID, '', $createdBy, new UnbanRequest())` | -| Query banned users | `$client->queryBannedUsers($filter, $opts)` | `$client->queryBannedUsers(new QueryBannedUsersPayload(...))` | -| Mute user | `$client->muteUser($targetId, $userId)` | `$client->mute(new MuteRequest(targetIds: [...], userID: ...))` | -| Unmute user | `$client->unmuteUser($targetId, $userId)` | `$client->unmute(new UnmuteRequest(targetIds: [...], userID: ...))` | diff --git a/docs/migration-to-getstream-php/06-devices.md b/docs/migration-to-getstream-php/06-devices.md deleted file mode 100644 index fd9d79b..0000000 --- a/docs/migration-to-getstream-php/06-devices.md +++ /dev/null @@ -1,140 +0,0 @@ -# Devices - -This guide covers migrating device management operations (push notification setup) from `stream-chat-php` to `getstream-php`. - -## Adding a Device - -### APN (Apple Push Notifications) - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$client->addDevice("device-token-abc", "apn", "user-123"); - -// With a named push provider configuration -$client->addDevice("device-token-abc", "apn", "user-123", "my-apn-provider"); -``` - -**After (getstream-php):** - -```php -use GetStream\ChatClient; -use GetStream\GeneratedModels\CreateDeviceRequest; - -$client = new ChatClient("", ""); - -$client->createDevice(new CreateDeviceRequest( - id: 'device-token-abc', - pushProvider: 'apn', - userID: 'user-123', -)); - -// With a named push provider configuration -$client->createDevice(new CreateDeviceRequest( - id: 'device-token-abc', - pushProvider: 'apn', - userID: 'user-123', - pushProviderName: 'my-apn-provider', -)); -``` - -> **Key differences:** -> - Method renamed from `addDevice()` to `createDevice()` -> - Uses a `CreateDeviceRequest` object with named arguments instead of positional string parameters -> - Push provider and user ID are properties on the request object - -### Firebase (Android Push Notifications) - -**Before (stream-chat-php):** - -```php -$client->addDevice("fcm-token-xyz", "firebase", "user-123"); - -// With a named push provider configuration -$client->addDevice("fcm-token-xyz", "firebase", "user-123", "my-firebase-provider"); -``` - -**After (getstream-php):** - -```php -use GetStream\GeneratedModels\CreateDeviceRequest; - -$client->createDevice(new CreateDeviceRequest( - id: 'fcm-token-xyz', - pushProvider: 'firebase', - userID: 'user-123', -)); - -// With a named push provider configuration -$client->createDevice(new CreateDeviceRequest( - id: 'fcm-token-xyz', - pushProvider: 'firebase', - userID: 'user-123', - pushProviderName: 'my-firebase-provider', -)); -``` - -### VoIP Token (Apple) - -The new SDK adds support for registering Apple VoIP push tokens, which was not available as a dedicated option in the old SDK. - -**After (getstream-php):** - -```php -use GetStream\GeneratedModels\CreateDeviceRequest; - -$client->createDevice(new CreateDeviceRequest( - id: 'voip-token-abc', - pushProvider: 'apn', - userID: 'user-123', - voipToken: true, -)); -``` - -## Listing Devices for a User - -**Before (stream-chat-php):** - -```php -$response = $client->getDevices("user-123"); -``` - -**After (getstream-php):** - -```php -$response = $client->listDevices('user-123'); -``` - -> **Key differences:** -> - Method renamed from `getDevices()` to `listDevices()` -> - Response is typed as `ListDevicesResponse` instead of a generic `StreamResponse` - -## Deleting a Device - -**Before (stream-chat-php):** - -```php -$client->deleteDevice("device-token-abc", "user-123"); -``` - -**After (getstream-php):** - -```php -$client->deleteDevice('device-token-abc', 'user-123'); -``` - -> **Key differences:** -> - The method signature is the same: `deleteDevice(string $id, string $userID)` -> - Parameter names changed from `$deviceId` to `$id` and `$userId` to `$userID`, but since both are positional strings this has no practical impact - -## Method Mapping Summary - -| Operation | stream-chat-php | getstream-php | -|-----------|----------------|---------------| -| Add device | `$client->addDevice($deviceId, $provider, $userId, $providerName)` | `$client->createDevice(new CreateDeviceRequest(...))` | -| List devices | `$client->getDevices($userId)` | `$client->listDevices($userID)` | -| Delete device | `$client->deleteDevice($deviceId, $userId)` | `$client->deleteDevice($id, $userID)` | diff --git a/docs/migration-to-getstream-php/README.md b/docs/migration-to-getstream-php/README.md deleted file mode 100644 index 2337478..0000000 --- a/docs/migration-to-getstream-php/README.md +++ /dev/null @@ -1,91 +0,0 @@ -# Migrating from stream-chat-php to getstream-php - -## Why Migrate? - -Stream has released **[getstream-php](https://github.com/GetStream/getstream-php)**, a new full-product PHP SDK that covers Chat, Video, Moderation, and Feeds in a single package. It is generated from OpenAPI specs, which means it stays up to date with the latest API features automatically. - -**getstream-php** is the long-term-supported SDK going forward. **stream-chat-php** will enter maintenance mode and continue receiving critical bug fixes, but new features and API coverage will only be added to getstream-php. - -If you are starting a new project, use **getstream-php**. If you have an existing project using stream-chat-php, we encourage you to migrate at your convenience. There is no rush, as stream-chat-php is not going away, but migrating gives you access to the latest features and the best developer experience. - -## Key Differences - -| | **stream-chat-php** | **getstream-php** | -|---|---|---| -| **Package** | `get-stream/stream-chat` | `getstream/getstream-php` | -| **Namespace** | `GetStream\StreamChat\Client` | `GetStream\Client` / `GetStream\ChatClient` | -| **Client init** | `new Client($apiKey, $apiSecret)` | `ClientBuilder::fromEnv()->build()` or `new Client(apiKey: ..., apiSecret: ...)` | -| **API style** | Associative arrays for everything | Typed model classes with named arguments | -| **Channel operations** | `$client->Channel($type, $id)->method()` | `$client->methodName($type, $id, ...)` | -| **Custom fields** | Top-level array keys | `custom: (object) [...]` property | -| **Filters / Sort** | Associative arrays | `(object)` casts and `SortParamRequest` objects | -| **Response types** | Associative arrays | Typed response objects | -| **Autoloading** | PSR-0 | PSR-4 | -| **Product coverage** | Chat only | Chat, Video, Moderation, Feeds | - -## Quick Before/After Example - -The most common operation (initialize client and send a message): - -**Before (stream-chat-php):** - -```php -use GetStream\StreamChat\Client; - -$client = new Client("", ""); - -$channel = $client->Channel('messaging', 'general'); -$response = $channel->sendMessage( - ['text' => 'Hello, world!'], - 'user-1', -); -``` - -**After (getstream-php):** - -```php -use GetStream\ClientBuilder; -use GetStream\GeneratedModels; - -$client = ClientBuilder::fromEnv()->build(); - -$response = $client->sendMessage( - 'messaging', - 'general', - new GeneratedModels\SendMessageRequest( - message: new GeneratedModels\MessageRequest( - text: 'Hello, world!', - userID: 'user-1', - ), - ), -); -``` - -## Migration Guides by Topic - -| # | Topic | Guide | -|---|-------|-------| -| 1 | Setup and Authentication | [01-setup-and-auth.md](./01-setup-and-auth.md) | -| 2 | Users | [02-users.md](./02-users.md) | -| 3 | Channels | [03-channels.md](./03-channels.md) | -| 4 | Messages and Reactions | [04-messages-and-reactions.md](./04-messages-and-reactions.md) | -| 5 | Moderation | [05-moderation.md](./05-moderation.md) | -| 6 | Devices | [06-devices.md](./06-devices.md) | - -Each guide provides side-by-side "Before" and "After" code examples for every operation, along with notes on key differences. - -## Continued Support for stream-chat-php - -stream-chat-php is not being removed or abandoned. It will continue to receive: - -- Critical bug fixes -- Security patches -- Requested features on a case-by-case basis - -However, all new API features, generated model types, and multi-product support will only be available in getstream-php. We recommend migrating when it makes sense for your project timeline. - -## Resources - -- [getstream-php on GitHub](https://github.com/GetStream/getstream-php) -- [getstream-php on Packagist](https://packagist.org/packages/getstream/getstream-php) -- [Stream Chat documentation](https://getstream.io/chat/docs/)