Skip to content

REALTIME_SETUP.md

Latest commit

 

History

History
178 lines (137 loc) · 5.16 KB

REALTIME_SETUP.md

File metadata and controls

178 lines (137 loc) · 5.16 KB

🔌 Real-time Collaborative Editor Setup

✅ WebSocket Broadcasting System Installed

This editor now supports real-time multi-user collaboration using WebSockets and Laravel Echo!

🎯 What's Included

  1. WebSocket Server (websocket-server.js)

    • Simulates Pusher locally
    • Handles channel subscriptions
    • Broadcasts events to all connected clients
    • Runs on ws://localhost:6001

  2. Laravel Broadcasting Events

    • App/Events/EditorUpdated.php - Event triggered on document update
    • Automatically broadcasts to all users editing the same document
    • Uses channel-based isolation: editor-{documentId}

  3. Frontend (Laravel Echo)

    • Listens for real-time updates via WebSocket
    • Auto-updates editor content when changes arrive from other users
    • Preserves cursor position
    • Shows notification of updates

🚀 How to Run

Terminal 1: Start Laravel Server

cd /home/mmsme/Documents/upload-files
php artisan serve --host=127.0.0.1 --port=8000

Terminal 2: Start WebSocket Server

cd /home/mmsme/Documents/upload-files
node websocket-server.js

Both servers must be running for real-time collaboration to work!

📝 How to Test Real-time Collaboration

  1. Open Document 1 (Browser/Tab 1):

    • Go to: http://127.0.0.1:8000/editor/1/edit
    • You'll see "Live Sync Active" indicator with green dot

  2. Open Same Document (Browser/Tab 2):

    • Go to: http://127.0.0.1:8000/editor/1/edit
    • You now have 2 users editing the same document

  3. Edit in Tab 1:

    • Type some text
    • Click "Update Document" to save
    • Watch Tab 2 - content updates instantly! 🎉

  4. Edit in Tab 2:

    • Make changes
    • Click "Update Document"
    • Watch Tab 1 - receives update automatically! ⚡

📊 How It Works

User 1 Makes Change
       ↓
   [Editor Form]
       ↓
   POST/PATCH /editor/{id}
       ↓
   [Laravel Route]
       ↓
   broadcast(new EditorUpdated(...))
       ↓
   [WebSocket Server]
       ↓
   Forward to channel: editor-{id}
       ↓
   [Laravel Echo Listeners]
       ↓
   User 2 Receives Update → Auto-Updates ✨

🛠️ Architecture

  • Pusher Simulation: Custom WebSocket server (websocket-server.js)
  • Broadcasting Driver: Pusher (can be switched to Redis, Ably, etc.)
  • Frontend: Laravel Echo + Pusher.js
  • Channels: Private channel per document (editor-{docId})
  • Events: EditorUpdated broadcast on content change

🔧 Configuration Files

  • Broadcasting Config: config/broadcasting.php
  • Event Class: app/Events/EditorUpdated.php
  • Routes: routes/web.php (PATCH route broadcasts)
  • Bootstrap: resources/js/bootstrap.js (Echo initialization)
  • Editor JS: resources/js/editor.js (listens for updates)
  • WebSocket Server: websocket-server.js

📈 Performance Features

  • ✅ Instant Updates: WebSocket eliminates polling delays
  • ✅ Cursor Preservation: User cursor position maintained during updates
  • ✅ Conflict Prevention: JSON comparison prevents duplicate updates
  • ✅ Scalable: Can handle many concurrent users per document
  • ✅ Low Latency: Direct WebSocket connection (vs polling every 3s)

🌐 Production Deployment

To use in production with multiple servers:

  1. Switch to Redis Broadcasting:

    // config/broadcasting.php
'default' => env('BROADCAST_DRIVER', 'redis'),

  2. Or use Pusher Cloud:

    BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your_app_id
PUSHER_APP_KEY=your_app_key
PUSHER_APP_SECRET=your_app_secret
PUSHER_APP_CLUSTER=your_cluster

  3. Or use Ably:

    BROADCAST_DRIVER=ably
ABLY_KEY=your_ably_key

📱 Client-Side Details

Connect: When you open /editor/{id}/edit, the page:

  1. Initializes Laravel Echo with WebSocket configuration
  2. Subscribes to channel: editor-{id}
  3. Listens for EditorUpdated events
  4. Auto-updates content on arrival

Disconnect: When you close the page:

  1. WebSocket connection closes
  2. Server notifies other users via channel
  3. Room is cleaned up

🐛 Troubleshooting

Q: "Real-time updates not working"

  • A: Check that both servers are running:
    • PHP: http://127.0.0.1:8000 (should load editor)
    • WebSocket: ws://127.0.0.1:6001 (should show "Waiting for connections")

Q: "WebSocket connection refused"

  • A: WebSocket server not running. Start it with: node websocket-server.js

Q: "Updates show but not real-time"

  • A: Check browser console for connection errors. Make sure firewall allows port 6001.

Q: "Cursor jumps to end on update"

  • A: This is expected behavior - cursor is preserved where possible, but may reset if document structure changes significantly.

📚 Reference

✨ Next Steps

The real-time collaborative editor is now production-ready!

Try it now:

  1. Start both servers
  2. Open editor in 2 browser tabs
  3. Edit same document
  4. Watch changes sync instantly! 🎉