diff --git a/docs/worker.md b/docs/worker.md index 81c18266a..b87549d4e 100644 --- a/docs/worker.md +++ b/docs/worker.md @@ -179,3 +179,13 @@ $handler = static function () use ($workerServer) { // ... ``` + +## Worker Mode for Extension Developers + +### Request Lifecycle + +In worker mode FrankenPHP only goes through `RINIT` and `RSHUTDOWN` once per worker thread. In case you need to observe a worker request start and end, you can not rely on `RINIT` and `RSHUTDOWN` phases of the extension lifecycle. Instead, you are able to hook into the `sapi_module.activate` / `sapi_module.deactivate` function pointers to achieve the same effect (you can validate that the current SAPI is FrankenPHP by checking the value of `sapi_module.name`). + +Upon entering the `frankenphp_handle_request()` function, FrankenPHP calls `sapi_deactivate()` in internals which calls the `sapi_module.deactivate` hook if initialized and finaly blocks until a request arrives. Once a request arrives for the worker to handle, FrankenPHP calls `sapi_activate()` in internals which calls the `sapi_module.activate` hook if initialized. + +Be aware that FrankenPHP worker mode injects a dummy request to start the worker even before the first request arrives. diff --git a/frankenphp.c b/frankenphp.c index 102af2db7..db3d8c481 100644 --- a/frankenphp.c +++ b/frankenphp.c @@ -122,7 +122,12 @@ static void frankenphp_release_temporary_streams() { ZEND_HASH_FOREACH_END(); } -/* Adapted from php_request_shutdown */ +/* Adapted from php_request_shutdown + * This mimics the RSHUTDOWN phase from PHP for the worker mode. In case you + * need to observe the end of a request being handled, you can hook into the + * `sapi_module.deactivate` function pointer which gets called from + * `sapi_deactivate()`. + * */ static void frankenphp_worker_request_shutdown() { /* Flush all output buffers */ zend_try { php_output_end_all(); } @@ -170,7 +175,12 @@ void frankenphp_add_assoc_str_ex(zval *track_vars_array, char *key, add_assoc_str_ex(track_vars_array, key, keylen, val); } -/* Adapted from php_request_startup() */ +/* Adapted from php_request_startup() + * This mimics the RINIT phase from PHP for the worker mode. In case you need to + * observe a new request being handled, you can hook into the + * `sapi_module.activate` function pointer which gets called from + * `sapi_activate()`. + * */ static int frankenphp_worker_request_startup() { int retval = SUCCESS;