Download the PHP package highperapp/realtime without Composer

HighPer Real-Time Web Library

A high-performance, pluggable real-time web library for the HighPer PHP framework, supporting WebSocket, Server-Sent Events (SSE), and WebTransport protocols.

Features

• 🚀 High Performance: Built on AMPHP for maximum concurrency (C10M capability)
• 🔌 Pluggable Architecture: Optional installation and configuration
• 🌐 Multi-Protocol Support: WebSocket, SSE, WebTransport (HTTP/3 + QUIC)
• ⚙️ Environment Driven: Complete configuration through environment variables
• 📡 Broadcasting: Memory, Redis, and NATS broadcasting drivers
• 🔒 Security: JWT authentication, rate limiting, CORS support
• 📊 Modular Observability: Optional monitoring and tracing standalone libraries
• 🔍 Zero-Config Telemetry: Auto-discovery with graceful degradation
• 🛡️ Enterprise Features: Security monitoring, distributed tracing, metrics export
• 🎯 Protocol Abstraction: Unified API across all real-time protocols
• 🔄 Zero-Downtime: Connection migration support for deployments
• 📦 HighPer Integration: Native integration with HighPer framework

Installation

Quick Start

1. Basic Setup

2. Auto-Integration

The library automatically integrates with your HighPer application when real-time environment variables are detected:

3. Manual Integration

For more control, manually register the service provider:

Protocol Usage

WebSocket Example

Server-Sent Events Example

Broadcasting Example

Configuration

Environment Variables

Create a .env file or add to your existing .env (see .env.example for all options):

Programmatic Configuration

Use Cases

1. Gaming Application

2. Financial Trading Platform

3. Live Collaboration Tool

4. Live Dashboard

Monitoring and Observability

Modular Observability Architecture

HighPer Real-time integrates with separate standalone libraries for flexible observability:

• highperapp/monitoring - Performance metrics, security monitoring, health checks
• highperapp/tracing - Distributed tracing, OpenTelemetry integration

Installation Options

Option 1: Monitoring Only (Nano Apps)

Benefits: Metrics, security, health checks (~5MB overhead)

Option 2: Tracing Only (Debug/Development)

Benefits: Distributed tracing, correlation IDs (~8MB overhead)

Option 3: Full Observability (Enterprise)

Benefits: Complete observability stack (~12MB overhead)

Zero-Configuration Features

Automatic when libraries are installed:

• ✅ Real-time Protocol Auto-Instrumentation: WebSocket, SSE, HTTP/3, WebTransport
• ✅ Graceful Degradation: Missing libraries don't break functionality
• ✅ Smart Sampling: Environment-based optimization
• ✅ Health Check Endpoints: Kubernetes-ready probes
• ✅ Export Integration: Prometheus metrics, Jaeger/Zipkin tracing

Health Check Endpoints

Sample Health Check Response

Automatic Protocol Instrumentation

Your existing code gets automatic monitoring without any changes:

Prometheus Metrics Example

Advanced Configuration

Configure observability libraries independently:

Security Monitoring

Automatic threat detection for:

• SQL injection attempts
• XSS attacks
• Brute force patterns
• Rate limiting violations
• Geographic anomalies
• Suspicious user agents

Custom Metrics and Tracing (Optional)

Add business-specific observability when libraries are available:

Security

JWT Authentication

Rate Limiting

Deployment

Docker Deployment

Kubernetes Deployment

Performance Optimization

Connection Pooling

Memory Management

Load Balancing

Testing

The library includes comprehensive tests covering unit, integration, performance, concurrency, and reliability testing.

Test Structure

Running Tests

Test Environment Configuration

Tests use the following environment configuration (see phpunit.xml):

Test Categories

Unit Tests

• Configuration Testing: Validates environment variable parsing, default values, and config validation
• Protocol Interface Testing: Tests protocol implementation contracts and method signatures
• Connection Pool Testing: Tests connection management, limits, cleanup, and statistics

Integration Tests

• Service Provider Integration: Tests automatic service registration and bootstrapping
• Multi-Protocol Support: Tests WebSocket, SSE, and WebTransport integration
• Broadcasting: Tests cross-protocol message broadcasting
• Connection Lifecycle: Tests complete connection establishment, management, and cleanup

Performance Tests

• Message Processing Latency: Measures message handling performance (target: <100ms average)
• Throughput Testing: Tests message processing rate (target: >1000 msg/sec)
• Memory Usage: Monitors memory consumption under load (target: <50MB for 1000 connections)
• Broadcast Performance: Tests message delivery to multiple connections
• Connection Establishment: Measures connection setup time
• Concurrent Handling: Tests performance under concurrent load

Concurrency Tests

• Race Condition Protection: Tests data integrity under concurrent access
• Deadlock Prevention: Validates resource locking mechanisms
• Resource Contention: Tests behavior under high resource contention
• Concurrent Connections: Tests handling of simultaneous connection attempts
• Concurrent Broadcasting: Tests concurrent message broadcasting

Reliability Tests

• Connection Recovery: Tests automatic reconnection and recovery mechanisms
• Heartbeat Mechanism: Validates connection health monitoring
• Graceful Degradation: Tests system behavior under various failure conditions
• Load Balancing: Tests failover and load distribution reliability
• Data Integrity: Validates data consistency under failure scenarios

Performance Benchmarks

The library targets the following performance benchmarks:

Continuous Integration

The test suite is designed for CI/CD integration:

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add comprehensive tests (required for all changes)
5. Run the test suite: composer test
6. Run performance tests: composer test -- --group performance
7. Ensure all tests pass and coverage is maintained
8. Commit your changes (git commit -m 'Add amazing feature')
9. Push to the branch (git push origin feature/amazing-feature)
10. Submit a pull request

Testing Requirements for Contributors

• Unit tests required for all new functionality
• Integration tests required for new protocols or major features
• Performance tests required for performance-critical changes
• Minimum 90% code coverage for new code
• All existing tests must pass before merge
• Performance benchmarks must not regress by more than 10%

Development Environment Setup

License

MIT License - see LICENSE file for details.

Support

• Documentation: HighPer Framework Documentation
• Issues: GitHub Issues
• Community: HighPer Community
• Performance Issues: Use performance test results when reporting
• Security Issues: Please report privately to [email protected]