Weave Code
Laravel Octane Middleware Laravel Package
tideways/laravel-octane-middleware
Tideways middleware for Laravel Octane that adds request profiling and performance monitoring to long-running workers, helping you trace slow routes and spot bottlenecks with minimal setup.
A Tideways Middleware for Laravel Octane
Frequently asked questions about Laravel Octane Middleware
- What does tideways/laravel-octane-middleware actually do?
- It is a Laravel middleware that wraps each Octane request in a Tideways transaction so traces, timings and errors are captured per request even though Octane keeps workers resident between requests. It does not replace Tideways itself; it plugs your existing Tideways setup into Octane's worker lifecycle. Transaction naming is handled per request, which is what makes route-level analysis in the Tideways UI possible.
- How do I install the Tideways middleware for Laravel Octane?
- Install it with composer require tideways/laravel-octane-middleware, and make sure the Tideways PHP extension and daemon are already installed and reporting for your application. Middleware registration follows Laravel's normal conventions, so you can attach it globally or scope it to specific route groups. Check the repository for the supported PHP and Laravel matrix before you bump your constraint.
- Which Laravel versions are supported? Does it work with Laravel 13?
- Version 1.7 adds Laravel 13 support and expands the CI matrix across PHP and Laravel version combinations. Because it is a minor release with no API changes, it should be a drop-in upgrade for applications already on Laravel 11 or 12. The release notes do not state the minimum supported Laravel or PHP version, or whether an older major was dropped, so confirm the exact matrix in the repository before upgrading.
- Is upgrading from v1.6 to v1.7 a breaking change?
- No. Version 1.7 is described as a compatibility and CI release: no new features, no API surface changes and no stated breaking changes. The one open question is whether the PHP floor moved as a side effect of adding Laravel 13 support, since the notes do not confirm the supported floor. Run composer update --dry-run first and review the resolved dependency graph before rolling the bump out.
- Why is standard Tideways instrumentation not enough with Laravel Octane?
- Octane boots the framework once and reuses workers, so the request lifecycle hooks that normal PHP-FPM instrumentation relies on fire far less often than expected. Instrumentation that assumes one boot per request can miss transactions entirely or attribute timings to the wrong request. This middleware explicitly marks the start and end of each Octane request so the transaction is opened and closed at the right boundaries.
- How do I control which routes get profiled by the middleware?
- Configuration happens through Laravel's standard middleware registration rather than a bespoke config format, so you can attach it globally or restrict it to specific route groups. Scoping it lets you exclude health checks, static asset routes and other noisy endpoints from your trace volume. Because transaction names are set per request, the routes you do instrument stay clearly separated in Tideways.
- What is the performance overhead of this middleware in production?
- The package is designed as a lightweight, drop-in layer: it mostly manages transaction lifecycle around Octane's request boundaries and leaves the actual profiling work to the Tideways extension. In practice overhead is dominated by your Tideways sampling settings rather than the middleware itself. Benchmark on a staging worker using your production sampling rate before enabling it across every service.
- Can I use this package without Octane, on standard PHP-FPM?
- The package is built specifically for Octane's persistent-worker model, and its value is filling the request-boundary gap that Octane creates. On PHP-FPM, Tideways' standard auto-instrumentation already covers each request, so this middleware adds nothing there. Only install it on Octane or similar long-running worker deployments.
- How actively is the package maintained and tested?
- Version 1.7 expanded the CI matrix to test a mixture of PHP and Laravel version combinations and shipped support for Laravel 13, which indicates active maintenance against the current framework major. A CI matrix is a meaningful quality signal but only covers the combinations the maintainers chose, so lowest-supported-PHP with newest-Laravel is the usual gap to verify yourself. There is no published EOL or support-window policy in the release notes, so ask the maintainer if you need long-term guarantees.
- What are the alternatives to this middleware for monitoring Laravel Octane?
- You could rely on Tideways extension-level instrumentation if your version handles persistent workers, write a custom middleware that starts and stops a Tideways transaction yourself, or evaluate a different APM agent. Laravel Telescope is useful for local debugging but is not a production APM substitute and adds storage overhead. This package's advantage is that it is maintained by Tideways and already encodes the Octane lifecycle handling.
Weaver
How can I help you explore Laravel packages today?