Download the PHP package saravanasai/stream-pulse without Composer

Reliable Event Streaming for Laravel Applications

StreamPulse provides a seamless event streaming experience for Laravel developers. With a clean, intuitive API that feels native to the Laravel ecosystem, you can build robust, event-driven applications with minimal setup and configuration.

BETA VERSION - StreamPulse is currently in beta. We'd love your feedback to help shape its future! Star the repo, open issues, or contribute to make StreamPulse even better.

Why StreamPulse?

• Laravel-native experience - API designed to feel natural to Laravel developers
• Simplified event streaming - Complex Redis Streams concepts abstracted away
• Transaction awareness - Events can be tied to database transactions
• Resilient processing - Built-in support for retries and dead letter queues
• Real-time monitoring - Beautiful dashboard for stream visualization and management

Quick Start

Installation

Note: StreamPulse is designed for distributed systems where events can be published in one Laravel application and consumed in another. Events are persisted in Redis, allowing for communication between separate applications.

Basic Usage

Key Features

• Simple, Laravel-style API for publishing and consuming events
• Redis Streams integration with plans for additional drivers
• Consumer group support for distributed event processing
• Dead letter queue for failed message handling
• Transaction-aware publishing to ensure data consistency
• UI Dashboard for monitoring streams and events

Installation

You can install the package via composer:

You can publish the config file with:

You can also publish the views to customize the UI dashboard:

Redis Requirements

You need Redis 5.0+ properly configured in your Laravel application.

Usage Examples

Publishing Events

StreamPulse provides a simple API for publishing events to any configured topic:

Transaction-Aware Event Publishing

Publish events only after a database transaction successfully commits:

Consuming Events with Handlers

The recommended way to consume events is to register handlers for your topics:

The consumer command will handle all the complexities of polling, acknowledgments, retries, and DLQ management for you.

Stream Retention Management

StreamPulse automatically manages Redis streams to prevent unbounded growth:

StreamPulse uses Redis's built-in XLEN and XTRIM commands to manage stream size. The retention value specifies the maximum number of messages that should be kept in each stream. When new messages are published, older messages exceeding this limit are automatically trimmed from the stream.

Key retention considerations:

• Higher retention values provide longer message history but consume more memory
• Lower retention values minimize memory usage but reduce how far back you can access messages
• Topic-specific overrides allow you to balance memory usage based on each stream's importance
• Automatic trimming occurs during publish operations to maintain the configured limits
• Scheduled trimming is also performed via Laravel's scheduler to ensure streams remain within size limits even during periods of low publishing activity. In local environments, make sure to run php artisan schedule:run command to enable this feature.

Configuration

The published configuration file includes several sections to customize StreamPulse's behavior:

Key Configuration Options

• Default Driver: Currently Redis Streams is the only implemented driver, with NATS planned for future releases.
• Strict Mode: Prevents accidental topic creation in production by limiting to only explicitly defined topics.
• Auto Processing: Automatically schedules a task to process pending messages and move them to DLQ after exceeding retry limits.
• Global Defaults:
  • max_retries: Number of retry attempts before moving to DLQ
  • dlq: Dead letter queue name for failed messages
  • retention: Maximum number of messages to retain per stream
  • min_idle_time: Minimum time in milliseconds before re-processing pending messages
  • preserve_order: Whether to enforce strict message ordering
• Topics: Configure specific topics with custom settings that override defaults
• Drivers: Backend-specific settings (currently Redis)
• UI Settings: Configure the included web dashboard

Advanced Usage

Low-level Consumption API

For more control, you can use the low-level consumption API:

UI Dashboard

StreamPulse includes a web dashboard for monitoring and inspecting your streams and events:

Dashboard Features

• View all available streams/topics
• Browse events by topic with pagination - coming soon
• Examine event details including payload and metadata - coming soon
• Track failed events across all topics - coming soon
• Real-time monitoring of stream activity - coming soon
• Visual analytics of event processing - coming soon

Accessing the Dashboard

The dashboard is available at the route /stream-pulse and is protected by the web and auth middleware by default.

Routes include:

• Dashboard: /stream-pulse
• Topic Events: /stream-pulse/topics/{topic}

Architecture

StreamPulse uses Redis Streams as the default driver, which provides:

• Persistent message storage
• Consumer groups for distributed processing
• Automatic tracking of processed messages
• Dead letter queues for failed messages
• Exactly-once delivery semantics

The architecture is designed with a driver-based approach, allowing for seamless integration of new streaming technologies as they become available.

License

The MIT License (MIT). Please see License File for more information.