Migration Guide

Step-by-step guide to migrate WireChat from v0.2.x to v0.3.x

Migrating from v0.2.x to v0.3.x

Version 0.3.0 introduces a major architectural shift from config-based to Panel-based settings. This provides a cleaner, more extensible way to define WireChat environments (e.g., user, admin, support panels).

This is a breaking change that requires manual migration steps. Please backup your database and code before proceeding.

What Changed in v0.3.x

The major changes include:

• Panels replace config-based settings: Each chat environment is now defined as a Panel provider
• Namespace change: Namu\WireChat → Wirechat\Wirechat
• New trait name: Chatable → InteractsWithWireChat
• New accessor methods: Prefixed with wirechat (e.g., getWirechatAvatarUrlAttribute)
• Storage config keys: attachments.* → storage.*
• UUID config key: uuids → uses_uuid_for_conversations
• Polymorphic columns: Support for both UUID and bigint IDs

1. Step 1: Update Composer Package
2. First, update your composer.json to use the new package name:
3. composer remove namu/wirechat
   composer require wirechat/wirechat:^0.3
   

4. Step 2: Upgrade Namespace References
5. Run the namespace upgrade command to automatically update all references from Namu\WireChat to Wirechat\Wirechat:
6. php artisan wirechat:upgrade-namespace-to-v0.3x
   

7. Use the --dry-run flag to preview changes without applying them:

   php artisan wirechat:upgrade-namespace-to-v0.3x --dry-run
   
8. This command will:
10. On Windows, you’ll need Git Bash or WSL to run this command. Alternatively, manually replace namespaces in your IDE.

11. Step 3: Upgrade Polymorphic Columns
12. Run the morph columns upgrade command to ensure polymorphic relationships work with both UUID and bigint IDs:
13. php artisan wirechat:upgrade-morph-columns
    

14. Preview changes first:

    php artisan wirechat:upgrade-morph-columns --dry-run
    
15. This command will:
17. Step 4: Update User Model
18. Update your User model to use the new trait and interface:
19. Before (v0.2.x):
20. use Namu\WireChat\Traits\Chatable;
    
    class User extends Authenticatable
    {
        use Chatable;
    }
    

21. After (v0.3.x):
22. use Wirechat\Wirechat\Contracts\WireChatUser;
    use Wirechat\Wirechat\Traits\InteractsWithWireChat;
    
    class User extends Authenticatable implements WireChatUser
    {
        use InteractsWithWireChat;
    }
    

23. The old Chatable trait is backwards-compatible for now but deprecated.

24. Step 5: Update Accessor Methods
25. Update your custom accessor methods to use the new wirechat prefix:
26. Before (v0.2.x):
27. public function getAvatarUrlAttribute(): ?string
    public function getProfileUrlAttribute(): ?string  
    public function getDisplayNameAttribute(): string
    

28. After (v0.3.x):
29. public function getWirechatAvatarUrlAttribute(): ?string
    public function getWirechatProfileUrlAttribute(): ?string
    public function getWirechatDisplayNameAttribute(): string
    

30. Step 6: Update Configuration
31. Update your config/wirechat.php file to use the new configuration keys:
32. Before (v0.2.x):
33. return [
        'uuids' => false,
        'attachments' => [
            'disk' => 'public',
            'disk_visibility' => 'public',
        ],
    ];
    

34. After (v0.3.x):
35. return [
        'uses_uuid_for_conversations' => false,
        'storage' => [
            'disk' => 'public',
            'visibility' => 'public',
            'directories' => [
                'attachments' => 'attachments',
            ],
        ],
    ];
    

36. Step 7: Update Broadcasting Channels
37. If you’re listening to participant channels, update to the new encoded format:
38. Before (v0.1.x):
39. let userId = @js(auth()->id());
    
    Echo.private(`participant.${userId}`)
        .listen('.Namu\\Wirechat\\Events\\NotifyParticipant', (e) => {
            console.log(e);
        });
    

40. After (v0.3.x):
41. let userId = @js(auth()->id());
    let encodedType = @js(Wirechat\Wirechat\Helpers\MorphClassResolver::encode(auth()->user()->getMorphClass()));
    
    Echo.private(`participant.${encodedType}.${userId}`)
        .listen('.Wirechat\\Wirechat\\Events\\NotifyParticipant', (e) => {
            console.log(e);
        });
    

42. Step 8: Clear Caches
43. Clear all Laravel caches to ensure changes take effect:
44. php artisan view:clear
    php artisan config:clear
    php artisan cache:clear
    

New Features in v0.3.x

Panel-Based Configuration

Generate new panel providers for different chat environments:

php artisan make:wirechat-panel AdminPanel

This creates a dedicated panel provider where you can customize user search, storage, routes, and more.

Conditional Route Registration

Control when panel routes are registered:

$panel->registerRoutes(fn () => auth()->check());

Panel-Specific User Search

Customize user search per panel:

$panel->searchUsersUsing(function ($query) {
    return User::where('name', 'like', "%{$query}%")
        ->where('is_admin', true)
        ->limit(10)
        ->get();
});

TailwindCSS v4.0+ Support

Full support for the latest TailwindCSS version with improved theming.

Deprecated Features

These features still work but will be removed in a future version:

• ❌ namu/wirechat package name
• ❌ Namu\WireChat namespace
• ❌ Chatable trait (use InteractsWithWireChat)
• ❌ Legacy accessor methods without wirechat prefix
• ❌ uuids config key (use uses_uuid_for_conversations)
• ❌ attachments.* config keys (use storage.*)

Troubleshooting

If you encounter issues during migration, see the Troubleshooting Guide for common problems and solutions.