laravel/octane

Laravel Octane is a high-performance server for Laravel applications that maintains long-running PHP workers to improve request throughput. It supports multiple server runtimes, including RoadRunner, Swoole, and FrankenPHP, while providing mechanisms to manage state isolation and prevent memory leaks between requests. The system also offers utilities for concurrent task execution, interval-based caching, and comprehensive testing fakes to ensure reliability in persistent worker environments.

New stub files are provided to support running Laravel applications with FrankenPHP. The Caddyfile stub configures the server to use the FrankenPHP worker, enables Brotli and gzip compression for compressible routes (excluding Mercure paths), redacts authorization headers in logs, and allows for extra configuration directives. The frankenphp-worker.php stub sets default application paths and delegates to the Octane FrankenPHP worker implementation. An empty rr.yaml stub is also added for RoadRunner compatibility.

src/Commands/stubs · high confidence

This change introduces a new client implementation for FrankenPHP, allowing Laravel Octane to run on the FrankenPHP server. It adds a client class that marshals requests and handles responses, a server process inspector to manage the FrankenPHP process lifecycle (start, stop, reload) via its admin API, a state file handler to persist server state, and a utility to locate the FrankenPHP binary.

src/FrankenPhp · high confidence

Introduced the \FindsRoadRunnerBinary\ trait in \src/RoadRunner/Concerns\, which provides a \findRoadRunnerBinary\ method to automatically detect the RoadRunner executable. The method first checks for a local \rr\ binary in the project root, then falls back to searching the system PATH via Symfony's \ExecutableFinder\, while explicitly excluding binaries located within \vendor/bin/rr\ to prevent conflicts.

src/RoadRunner/Concerns · high confidence

New documentation resources have been added to guide developers using Laravel Octane, specifically targeting the long-running PHP worker environment. The \core.blade.php\ file provides high-level best practices, such as avoiding request-specific state in singletons and using scoped bindings. Additionally, a comprehensive \octane-development\ skill (\SKILL.md\) has been introduced to assist with driver detection (Swoole, RoadRunner, FrankenPHP), state isolation, memory management, concurrency handling, and testing strategies, ensuring applications do not suffer from state leakage or memory leaks common in persistent worker setups.

resources · high confidence

Introduces \OctaneStore\ and \OctaneArrayStore\ to support Laravel Octane's stateful environment. \OctaneStore\ implements the \Store\ interface using Swoole tables and integrates \laravel/serializable-closure\ to handle closure-based cache resolvers, enabling the new \interval()\ method for caching values that refresh at specified time intervals. \OctaneArrayStore\ extends the standard \ArrayStore\ to provide compatible stubs for interval functionality in non-Swoole contexts.

src/Cache · high confidence

Laravel Octane now supports FrankenPHP alongside RoadRunner and Swoole. The \octane:install\ command allows users to select FrankenPHP as their server, automatically installing the necessary dependencies and configuring the \.gitignore\ file. The \octane:start\ command now delegates to a new \octane:frankenphp\ command, which manages the FrankenPHP binary and Caddyfile configuration, including options for HTTPS, HTTP-to-HTTPS redirection, and admin server ports. The \octane:status\, \octane:reload\, and \octane:stop\ commands have been updated to handle FrankenPHP server instances, ensuring consistent lifecycle management across all supported servers.

src/Commands · high confidence

The \src/Concerns\ directory now includes \ProvidesConcurrencySupport\, introducing a \concurrently\ method that allows resolving multiple callbacks via background tasks with configurable timeouts. The \RegistersTickHandlers\ trait adds a \tick\ method to register callbacks that execute at specified intervals using the Octane cache and event dispatcher. Additionally, \ProvidesDefaultConfigurationOptions\ has been significantly expanded: it now includes \FlushLocaleState\ for request preparation, and for operation preparation, it adds listeners to provide new application instances to the database, session, filesystem, log, cache, and session managers, alongside flushing listeners for database query logs, Monolog state, and various caches (Str, Translator, Vite, Once). It also registers preparation listeners for first-party packages like Livewire, Inertia, Scout, and Socialite, and adds \db.transactions\ to the list of services to warm.

src/Concerns · high confidence

The src/Exceptions directory now includes several new exception types to improve error handling in Laravel Octane. DdException allows the dd() helper to function correctly in Octane by rendering variable dumps via HTML. TaskException and TaskTimeoutException provide specific error reporting for background tasks, including propagation of original exception details and timeout handling. TaskExceptionResult facilitates serialization and reconstruction of these task exceptions. Additionally, ServerShutdownException, WorkerException, and ValueTooLargeForColumnException are introduced to handle server shutdowns, worker errors, and Swoole table column size constraints respectively.

src/Exceptions · high confidence

This update adds support for the FrankenPHP server, registering its process inspector and state file in the service provider. It also refactors the core request lifecycle: the Worker now captures output buffers and wraps responses in a new OctaneResponse class, while the ApplicationFactory is updated to locate the bootstrap file in either the standard 'bootstrap' directory or a new '.laravel' directory. Additionally, the ApplicationGateway now flushes the controller after request termination to prevent state leakage, and the PSR-7 marshaling logic switches from RoadRunner's Diactoros factories to Laminas Diactoros factories.

src · high confidence

The \src/Commands/Concerns\ directory has been reorganized into specific traits to improve code structure and maintainability. \InstallsFrankenPhpDependencies\ and \InstallsRoadRunnerDependencies\ now handle the distinct logic for downloading and verifying their respective server binaries, including version checks and user prompts. \InteractsWithServers\ centralizes the server lifecycle management, including the watcher loop, signal handling, and port availability checks. \InteractsWithIO\ manages console output formatting, request logging, and error suppression, while \InteractsWithEnvironmentVariables\ and \InteractsWithTerminal\ provide utilities for environment clearing and terminal width detection.

src/Commands/Concerns · high confidence

This change introduces new fix scripts to address specific Symfony file handling issues within the Laravel Octane environment. It adds a fix for Symfony uploaded file moving by overriding \move\_uploaded\_file\ to use \rename\ directly, resolving compatibility issues with RoadRunner. It also adds a workaround for the \dd\ function in FrankenPHP environments by throwing a specific exception. Additionally, it refines the existing file validation fix by correcting the namespace syntax for the \is\_uploaded\_file\ override.

fixes · high confidence

This change introduces a new action to enforce max execution times by monitoring worker timers and terminating processes that exceed the limit, while also fixing how PUT, PATCH, and DELETE requests with form-encoded bodies are parsed by replacing the ParameterBag instantiation with a direct replace call. Additionally, the Swoole request conversion now correctly appends the query string to the request URI when it is missing, ensuring consistent URL handling for incoming requests.

src/Swoole/Actions · high confidence

This change introduces a comprehensive set of new event listeners in src/Listeners to ensure proper state isolation between requests in the Octane worker. New listeners handle flushing specific caches (Vite, Str, Translator, Array, Once), resetting Monolog and log contexts, and closing Monolog handlers on worker stop. It also adds listeners to provide the new sandbox application instance to core managers (Cache, Database, Filesystem, Log, Session, Router, etc.) and to prepare third-party integrations (Livewire, Inertia, Scout, Socialite) for the next operation. Additionally, it includes listeners to flush uploaded files, reset database query logs and durations, and enforce request schemes.

src/Listeners · high confidence

The Octane configuration file has been significantly updated to support additional servers (Swoole, FrankenPHP) and improve event handling. The server type is now configurable via the OCTANE\_SERVER environment variable. New event listeners have been added: EnsureUploadedFilesCanBeMoved for RequestReceived, CloseMonologHandlers for WorkerStopping, and FlushOnce for OperationTerminated. The WriteExceptionToStderr listener was replaced with ReportException. New configuration sections include 'tables' and 'cache' for Swoole-specific shared memory, a 'watch' list for file monitoring, 'max\_execution\_time' for request limits, and 'state\_file' for server state tracking. RoadRunner-specific options are also now exposed.

config · high confidence

The Swoole handlers have been restructured to improve reliability and observability. OnWorkerStart now explicitly manages opcode cache clearing (APCu and Opcache) based on the new \clear\_opcache\ configuration, and shuts down the server gracefully if the worker fails to boot. Request logging is now controlled by environment (local/testing) and streamed via a dedicated \Stream\ class. Additionally, OnServerStart introduces a configurable \maxExecutionTime\ feature that uses a timer to enforce request duration limits, replacing the previous hardcoded tick mechanism with a more flexible, conditional approach.

src/Swoole/Handlers · high confidence

The contracts in src/Contracts have been updated to support new concurrency patterns and cleaner type definitions. New interfaces DispatchesCoroutines, OperationTerminated, and ServerProcessInspector are added to handle coroutine resolution, operation termination context, and server process management respectively. The existing ConcurrentOperationDispatcher interface is renamed to DispatchesTasks, simplifying its API by merging task resolution and dispatching into single methods with explicit timeout and exception handling. Additionally, the Client interface now expects an OctaneResponse instead of a generic Symfony Response, and several interfaces (ServesStaticFiles, StoppableClient, Worker) have had their PHPDoc comments cleaned up for consistency.

src/Contracts · high confidence

The Swoole server now uses a dedicated \WorkerState\ class to manage worker context, enabling configurable Swoole server modes and SSL support via the \octaneConfig\. A new max execution time feature is implemented using Swoole timer tables to track and enforce request limits. The file watcher has been replaced with a new Node.js implementation (\file-watcher.cjs\) that supports Chokidar v4 wildcards and allows users to configure watch paths, replacing the previous hardcoded directory list.

bin · high confidence

The repository now includes an UPGRADE.md guide detailing the migration from 1.x to 2.x, specifically requiring PHP 8.1+, Laravel 10.10.1+, and updated RoadRunner dependencies (spiral/roadrunner-http ^3.0.1 and spiral/roadrunner-cli ^2.5.0). The README has been updated with a proper introduction and a logo supporting dark/light themes, while the CHANGELOG has been populated with release notes for versions up to v2.22.0. Additionally, a phpstan.neon.dist configuration file has been added to support PHPStan 2, and the phpunit.xml.dist has been simplified with explicit testing environment variables.

(repo-wide) · high confidence

The Swoole server now ensures a cleaner shutdown by killing the manager process alongside workers and master, and automatically detects the correct number of CPUs in containerized environments by reading cgroup quotas. Task dispatching behavior has changed: local tasks now throw specific timeout or exception errors instead of returning false, and a new HTTP-based task dispatcher is available for distributed scenarios. Additionally, static file serving now supports custom headers via configuration and correctly resolves files within symlinked directories, while HTTP status codes are sent with their proper reason phrases.

src/Swoole · high confidence

The RequestTerminated, TaskTerminated, and TickTerminated events now implement the OperationTerminated contract and utilize the new HasApplicationAndSandbox trait, allowing listeners to access both the base application and sandbox instances. A new TickReceived event has also been added to represent tick operations, ensuring consistent access to application context across all terminated and tick-related events.

src/Events · high confidence

The doc block for the Octane facade now includes static method signatures for tick, table, invokeRoute, concurrently, hasRouteFor, and route, improving IDE autocompletion and type hinting for these specific Octane capabilities.

src/Facades · high confidence

The RoadRunner integration now targets RoadRunner v3, switching the underlying client from PSR7Client to PSR7Worker and updating the reload mechanism to use the v3 RPC protocol (version=3) with a dedicated RPC port. This change also fixes a behavioral issue where StreamedResponse callbacks were not correctly resolved; the client now properly handles StreamedResponse and BinaryFileResponse types, ensuring that output buffers are merged and stream callbacks are executed via the new HTTP worker interface.

src/RoadRunner · high confidence

The in-memory table implementation now enforces column size constraints for string data. When using Swoole or OpenSwoole tables, attempting to set a string value that exceeds the defined column size will throw a \ValueTooLargeForColumnException\ instead of silently truncating or corrupting data. This validation is applied automatically during row updates via the \set\ method, ensuring data integrity for string columns defined with specific sizes.

src/Tables · high confidence

Added test fixtures for symlinked static files; Added tests for Octane listener state-flushing and error-handling behaviors; Expanded test coverage for Laravel Octane core components; Moved and enhanced testing fakes to public namespace.

This update shifts Laravel Octane to version 2.x, raising the minimum PHP version to 8.2.0 and expanding framework support to include Laravel 11, 12, and 13. It introduces compatibility with RoadRunner v3 by updating the \spiral/roadrunner-http\ dependency and adding conflicts for older RoadRunner versions, while also dropping the \spatie/laravel-package-tools\ and \spatie/once\ dependencies. The package now supports modern tooling with PHPStan 2, PHPUnit 13, and Laravel Prompts, and updates core HTTP message handling to use \laminas/laminas-diactoros\ v3.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 64.

• Code Health 70
• Architecture 86
• Maturity 51
• Readiness 77
• Security 77

• 300 commits — 237 feature/other, 63 fixes

• (root) — 104 commits
• src/Commands — 65 commits
• .github/workflows — 20 commits
• src/Swoole — 15 commits
• (repo) — 12 commits
• .github/ISSUE_TEMPLATE — 8 commits
• bin/frankenphp-worker.php — 8 commits
• src/Concerns — 7 commits
• src/Listeners — 7 commits
• bin/bootstrap.php — 6 commits
• config/octane.php — 6 commits
• src/FrankenPhp — 5 commits
• tests/Listeners — 4 commits
• bin/file-watcher.cjs — 3 commits
• src/RoadRunner — 3 commits
• src/Worker.php — 3 commits
• .github/SECURITY.md — 2 commits
• art/.DS_Store — 2 commits
• bin/createSwooleServer.php — 2 commits
• resources/boost — 2 commits

• fix: Apply fixes from StyleCI
• fix: Apply fixes from StyleCI
• fix: Apply fixes from StyleCI
• fix: Apply fixes from StyleCI
• fix: Apply fixes from StyleCI
• fix: Apply fixes from StyleCI
• fix: Apply fixes from StyleCI
• fix: Apply fixes from StyleCI
• fix: Fix #851 bug report (#853)
• fix: Fix APP_PUBLIC_PATH fallback logic in frankenphp-worker (#1085)
• fix: Fix Caddyfile when env var values contain spaces (#786)
• fix: Fix FlushUploadedFiles listener (#1044)
• fix: Fix ServerProcessInspector::adminUrl() (#1021)
• fix: Fix Swoole auto worker count in containers (#1101)
• fix: Fix Swoole in-memory table size (#818)
• fix: Fix argument in RoadRunner process reset command (#1023)
• fix: Fix buffer error (issue #922) (#923)
• fix: Fix code styling
• fix: Fix code styling
• fix: Fix code styling
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

laravel/octane was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.