Weave Code
Event Laravel Package
hyperf/event
hyperf/event is a lightweight event dispatcher for Hyperf applications. Define events and listeners, dispatch synchronously or via async mechanisms, and keep your domain decoupled. Integrates cleanly with Hyperf’s DI and coroutine-friendly runtime.
At a glance
Frequently asked questions about Event
- Can I use hyperf/event in a pure Laravel app without Hyperf installed?
- No, the package requires Hyperf’s runtime (Swoole 5.1+) for coroutine-based performance. However, the LaravelEventAdapter lets you integrate Hyperf’s event system into Laravel apps by proxying events to a separate Hyperf worker. This avoids rewriting your Laravel event logic but adds network latency between Laravel and Hyperf.
- How do I migrate from Laravel’s EventServiceProvider to hyperf/event?
- Replace `EventServiceProvider` with `LaravelEventAdapter` in your Laravel config. Bind listeners to the Hyperf dispatcher via `config/app.php` under the `hyperf` section. Start with non-critical events (e.g., logging) to test compatibility. Use the `FALLBACK_TO_REDIS` config option to route events to Laravel’s queue if Hyperf fails.
- Does hyperf/event support Laravel’s queue system (ShouldQueue) for async events?
- No, it replaces Laravel’s queue system with Hyperf’s coroutine-based execution. Events marked as `ShouldQueue` in Laravel will dispatch synchronously via Hyperf’s async mechanisms. For true queue compatibility, use the `FALLBACK_TO_REDIS` mode, but this sacrifices Hyperf’s low-latency benefits. Prioritize events via Hyperf’s middleware instead.
- What Laravel versions are officially supported by hyperf/event?
- The package targets Laravel 8.x–10.x and Hyperf 2.0+. Test thoroughly with your Laravel version, as the adapter layer may introduce edge cases (e.g., transaction handling). Check the [GitHub issues](https://github.com/hyperf/event/issues) for version-specific bugs. Avoid Laravel 7.x due to missing PSR-14 compatibility.
- How do I handle binary payloads (e.g., protobuf) in WebSocket events?
- Use `EventWebSocket::sendBinary()` to emit binary data. The package buffers payloads up to 1MB by default (configurable via `hyperf.event.websocket.max_payload_size`). For fragmented data, implement a custom `WebSocketHandler` to reassemble chunks. Test with your target payload size—WebSocket frame limits may still apply at the transport layer.
- Will hyperf/event break Laravel’s transaction management (e.g., rollbacks)?
- Transactions are not automatically rolled back across Laravel and Hyperf. If a Laravel transaction fails, pending Hyperf events may still process unless you use `EventTransaction` middleware with explicit rollback logic. For distributed transactions, consider compensating actions (e.g., undo events) or a saga pattern.
- Can I run hyperf/event in serverless environments like AWS Lambda?
- Yes, but with caveats. Hyperf workers must run alongside Laravel (e.g., in the same Lambda function or warm pool). Use `hyperf:event:coldstart-mitigate` to preload workers. Avoid cold starts by deploying Hyperf in a separate container (e.g., Fargate) or using provisioned concurrency. Monitor memory usage—Swoole’s coroutines consume more resources than Laravel’s synchronous I/O.
- Are there alternatives to hyperf/event for high-performance Laravel events?
- For Laravel-only solutions, consider `spatie/laravel-event-sourcing` (CQRS) or `laravel-horizon` (queue optimization). For Hyperf integration, `hyperf/async-queue` offers queue-based async events but lacks WebSocket or binary payload support. If you need PSR-14 compliance without Hyperf, use `league/event` or `symfony/event-dispatcher` with Laravel’s adapter.
- How do I debug event dispatching issues between Laravel and Hyperf?
- Use `hyperf:event:trace` to log event flows and `laravel-telescope` for Laravel-side observability. Check Hyperf’s `logs/hyperf.log` for coroutine errors. Enable `APP_DEBUG=true` in Laravel and `HYPERF_DEBUG=true` in Hyperf. For network issues, verify the `hyperf.event.adapter.redis` connection settings if using fallback mode.
- What’s the performance impact of using hyperf/event vs. Laravel’s native event system?
- Hyperf’s coroutine-based dispatch achieves **<50ms latency** for WebSocket events (vs. **200–500ms** in Laravel’s synchronous system). Async dispatch adds **<10ms overhead** but requires Swoole 5.1+. Benchmark with `hyperf:event:bench`—real-world performance depends on payload size, network topology, and Hyperf worker scaling. Avoid mixing synchronous Laravel events with Hyperf’s async system for consistency.
Weaver
How can I help you explore Laravel packages today?