[CHA-2587] add migration guide for stream-chat-php

[mogita]

No description provided.

[Copilot]

Pull request overview

This PR adds a comprehensive migration guide for users moving from stream-chat-php to getstream-php. The guide explains the rationale for migrating and provides side-by-side "Before" and "After" code examples across six topics: setup/auth, users, channels, messages/reactions, moderation, and devices.

Changes:

• New migration guide overview file (README.md) with key differences table and links to topic guides
• Six new topic-specific migration guides covering setup, users, channels, messages/reactions, moderation, and devices
• Updated root README.md with a pointer to the migration guide

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
docs/migration-from-stream-chat-php/README.md	Overview doc with key differences table and topic index
docs/migration-from-stream-chat-php/01-setup-and-auth.md	Client initialization, env vars, namespaces, token generation migration
docs/migration-from-stream-chat-php/02-users.md	User upsert, query, partial update, deactivate/reactivate, delete migration
docs/migration-from-stream-chat-php/03-channels.md	Channel type CRUD, member management, query/update/delete channel migration
docs/migration-from-stream-chat-php/04-messages-and-reactions.md	Message send/update/delete and reaction CRUD migration
docs/migration-from-stream-chat-php/05-moderation.md	Moderator add/demote, ban/unban, shadow ban, mute/unmute migration
docs/migration-from-stream-chat-php/06-devices.md	Device registration, listing, and deletion migration
README.md	Added link to the new migration guide

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

All "After (getstream-php)" examples in this guide use $client = ClientBuilder::fromEnv()->build() followed by chat-specific method calls (sendMessage, getMessage, updateMessage, deleteMessage, sendReaction, getReactions, deleteReaction, etc.). These methods exist only in ChatTrait, which is included in ChatClient, not in the plain Client returned by ClientBuilder::fromEnv()->build(). These code examples will produce a fatal error ("Call to undefined method") at runtime. The client instantiation should use ChatClient directly (e.g., new ChatClient($apiKey, $apiSecret)) or a future ClientBuilder::fromEnv()->buildChatClient() method.

[Copilot]

All "After (getstream-php)" examples use $client = ClientBuilder::fromEnv()->build() followed by calls to methods that only exist in ChatTrait (e.g., getOrCreateChannel, getOrCreateDistinctChannel, updateChannel, updateChannelPartial, deleteChannel, deleteChannels, queryChannels, createChannelType, updateChannelType). The plain Client returned by build() does not include these methods. The client instantiation should use ChatClient directly to access these methods.

[Copilot]

The ban, unban, mute, and unmute methods called on $client throughout this guide (e.g., $client->ban(...), $client->unban(...), $client->mute(...), $client->unmute(...)) exist only in ModerationTrait, which is included in ModerationClient. The Client object returned by ClientBuilder::fromEnv()->build() does not include these methods. Use ClientBuilder::fromEnv()->buildModerationClient() to get a ModerationClient that has these methods.

Additionally, queryBannedUsers is in ChatTrait (on ChatClient), not in ModerationClient, so calling it on a ModerationClient would also fail. For queryBannedUsers, a ChatClient must be used instead.

[Copilot]

The examples for adding and demoting moderators use $client->updateChannel(...), which is in ChatTrait and only available on ChatClient, not the plain Client returned by ClientBuilder::fromEnv()->build().

[Copilot]

The APN device section instantiates the client using new ChatClient("<api-key>", "<api-secret>") with positional arguments, while 01-setup-and-auth.md documents the preferred style as new Client(apiKey: ..., apiSecret: ...) with named arguments. Additionally, device operations (createDevice, listDevices, deleteDevice) are in CommonTrait and are available on the plain Client, so ChatClient is unnecessarily specific here. For consistency with the rest of the migration guides, consider using ClientBuilder::fromEnv()->build() (which returns a Client and has all device methods) with the named argument constructor style shown in 01-setup-and-auth.md.

[Copilot]

The migration guide uses $client = ClientBuilder::fromEnv()->build() throughout all "After (getstream-php)" examples in sections covering chat operations (sending messages, managing channels, etc.) and moderation operations. However, ClientBuilder::fromEnv()->build() returns a plain Client object, which only includes CommonTrait.

• Chat-specific methods (sendMessage, getMessage, updateMessage, deleteMessage, getOrCreateChannel, updateChannel, queryChannels, sendReaction, etc.) are only available on ChatClient (which uses ChatTrait).
• Moderation-specific methods (ban, unban, mute, unmute) are only available on ModerationClient (which uses ModerationTrait).

There is no buildChatClient() method on ClientBuilder. The integration tests (see tests/Integration/ChatTestCase.php line 347) explicitly note "Channel API Wrappers (since PHP SDK lacks a ChatClient)" and work around this by calling makeRequest() directly.

The correct approach for chat operations is to instantiate ChatClient directly: new ChatClient($apiKey, $apiSecret) or new \GetStream\ChatClient(apiKey: ..., apiSecret: ...). Similarly, moderation-specific methods require ModerationClient (available via ClientBuilder::fromEnv()->buildModerationClient()).

This issue affects all "After (getstream-php)" examples in this guide that call chat or moderation-specific methods on a Client returned by ClientBuilder::fromEnv()->build().