Download the PHP package neuralpin/notifyli without Composer

Notifyli: Real-time Communication with Redis Notifications

A WebSocket-based real-time messaging system that enables users to communicate in private and public channels. Built-in Redis broker allows external systems to send notifications to specific users in their designated channels.

Overview

Primary Goal: Enable real-time user-to-user communication in private/public channels via WebSocket.

Secondary Feature: Redis-based notification broker for sending automated messages from external systems to connected users.

Key Architecture

• User Identification: Each user must identify themselves with a user_id and connect to a specific room (channel)
• Private Channels: Users typically connect to personal /user/{user_id} rooms to receive notifications
• Public Channels: Users can join shared rooms for group communication
• External Integration: Third-party systems orchestrate notifications via Redis broker, targeting specific users and channels

Important: The UI MUST initialize with a user_id and room before the WebSocket connection is established. This allows the system to:

1. Route direct notifications to the correct user
2. Allow external systems to target specific users for automated notifications
3. Maintain user state in Redis for offline notification handling

Example Implementation Files

This repository includes three example implementations that demonstrate how to integrate the system:

• server.php - Example WebSocket server initialization. Demonstrates how to configure and start the messaging server with your environment settings.

• notification-bridge.php - Example notification bridge implementation. Shows how to listen to Redis pub/sub and forward notifications to connected users via WebSocket.

• public/index.php - Example client UI implementation. Demonstrates user authentication with user_id, room selection, and real-time message handling.

These are reference implementations. Adapt them to your specific infrastructure and requirements.

Cloud Production Deployment

This guide covers deploying all three components in a production cloud environment.

Prerequisites

• Cloud server (Ubuntu 20.04+ recommended) with root access
• PHP 8.2 or higher installed
• Redis server installed and running
• Nginx web server
• Domain name with DNS configured
• SSL certificates (Let's Encrypt recommended)

Architecture Overview

Step 1: Server Preparation

Step 2: Deploy Application Code

Step 3: Configure Environment

Create /var/www/notifyli/.env:

Step 4: Configure Nginx (Web UI + WebSocket Proxy)

Create /etc/nginx/sites-available/notifyli.conf:

Enable the site:

Step 5: SSL Certificate (Let's Encrypt)

Step 6: Configure Firewall

Step 7: Create Log Directories

Step 8: Configure Supervisor

Install Supervisor:

Create /etc/supervisor/conf.d/notifyli.conf:

Step 9: Enable and Start Services

Step 10: Verify Deployment

Managing Services

Maintenance & Monitoring

Daily Restart (Required)

Create a cron job to restart services daily at 3 AM to mitigate PHP daemon memory growth over time:

Add:

Log Rotation

Create /etc/logrotate.d/notifyli:

Monitoring

Integration Guide

Client UI Integration (Example: public/index.php)

The example UI demonstrates key integration points:

Required Fields:

• user_id: Unique identifier for the user (required for targeted notifications)
• room: Channel identifier (e.g., "lobby", "/user/123")
• name: Display name for messages

WebSocket Connection:

Message Types:

Regular chat message (user to user):

Direct notification (system to user):

External System Integration (Publishing Notifications)

External applications can send notifications to connected users via Redis pub/sub.

PHP Integration:

Direct Redis Integration (Any Language):

Message Format:

External Redis Check by client_id

If your external system is connected to the same Redis instance, you can detect active users by searching client_id inside the room hashes (notifyli:connections:{room}).

Single room check:

All rooms check (returns matching room key, user field, and payload):

If this returns data, the user session with that client_id is currently connected.

Testing Notifications (console/send-notification.php)

For development and testing:

Production Operations

Service Management

Monitoring

Check Service Health:

Monitor Redis:

Monitor WebSocket Server:

Monitor Nginx:

Troubleshooting

WebSocket Server Won't Start:

Notification Bridge Won't Connect:

Notifications Not Delivered:

High Memory Usage:

SSL Certificate Issues:

Performance Tuning

PHP-FPM Optimization (/etc/php/8.2/fpm/pool.d/www.conf):

Nginx Optimization:

Redis Optimization (/etc/redis/redis.conf):

System Limits (/etc/security/limits.conf):

Backup & Recovery

Backup Redis Data:

Backup Application:

API Reference

PHP API (for External Systems)

WebSocket Protocol

Client → Server (user sends message):

Server → Client (broadcast or notification):

Redis Commands

Project Structure

Architecture Components

1. WebSocket Server (server.php)

• Handles persistent connections from clients
• Routes messages between users in same room
• Tracks connections in Redis for notification routing
• Non-blocking I/O for high concurrency

2. Notification Bridge (notification-bridge.php)

• Subscribes to Redis pub/sub channel notifyli:messages
• Receives notifications from external systems
• Verifies user is connected before forwarding
• Maintains persistent WebSocket connection to server
• Auto-reconnects on connection failure

3. Web UI Client (public/index.php)

• Authenticates user with user_id and room
• Establishes WebSocket connection
• Sends/receives real-time messages
• Displays notifications from external systems
• Persists settings in localStorage

4. Redis State Manager

• Stores active user connections
• Key format: notifyli:connections:{room} (Hash)
• Fields: user_{id} → JSON (name, connected_at, client_id)
• TTL: Removed on disconnect

5. Redis Message Broker

• Pub/sub channel: notifyli:messages
• Message routing logic
• Connection state queries
• Used by external systems to send notifications

Performance Characteristics

• Concurrent Connections: 1000+ per server (tested)
• Message Latency: <10ms (local network)
• Redis Overhead: ~1ms per pub/sub message
• Memory: ~2-5KB per WebSocket connection
• Keepalive Interval: 25 seconds (configurable)
• Connection Timeout: 7 days (nginx proxy)

Security Considerations

• SSL/TLS encryption for WebSocket connections (WSS)
• Deny access to .env and sensitive files in nginx
• Run services as www-data (limited privileges)
• Supervisor-managed daemons with auto-restart
• Firewall rules (UFW) to restrict access
• Redis should bind to 127.0.0.1 (not exposed publicly)
• Rotate logs to prevent disk exhaustion
• SSL certificates auto-renewed (Let's Encrypt)

License

This project is licensed under GPL-3.0-or-later.