Instrument requests in FrankenPHP worker mode

Wrap callable passed to `frankenphp_handle_request` to emulate PHP request's
lifecycle events in begin and end handlers of the callable.  This way each
handled request becomes a distinct transaction. This method does not rely on
internal implementation of FrankenPHP worker mode but rather relies on its
public interface that must be implemented by any application using FrankenPHP
worker mode.

Also reset the state (end the transaction) after initial RINIT executed when
worker script is started.

Author: lavarou

agent/config.m4

@@ -221,7 +221,7 @@ if test "$PHP_NEWRELIC" = "yes"; then
   php_call.c php_curl.c php_curl_md.c php_datastore.c php_environment.c \
   php_error.c php_execute.c php_explain.c php_explain_mysqli.c \
   php_explain_pdo_mysql.c php_extension.c php_file_get_contents.c \
-  php_globals.c php_hash.c php_header.c php_httprequest_send.c \
+  php_frankenphp.c php_globals.c php_hash.c php_header.c php_httprequest_send.c \
   php_internal_instrument.c php_memcached.c php_minit.c php_mshutdown.c php_mysql.c \
   php_mysqli.c php_newrelic.c php_nrini.c php_observer.c php_output.c php_pdo.c \
   php_pdo_mysql.c php_pdo_pgsql.c php_pgsql.c php_psr7.c php_redis.c \

agent/php_frankenphp.c

@@ -0,0 +1,57 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "php_frankenphp.h"
+#include "php_agent.h"
+#include "php_user_instrument.h"
+#include "php_wrapper.h"
+
+#ifdef ZTS
+
+static void nr_php_frankenphp_request_handler_fcall_begin(
+    zend_execute_data* execute_data NRUNUSED) {
+  nrl_verbosedebug(NRL_INSTRUMENT,
+                   "frankenphp_request_handler_fcall_begin started");
+  // emulate rinit
+  nr_php_txn_begin(0, 0);
+  nrl_verbosedebug(NRL_INSTRUMENT,
+                   "frankenphp_request_handler_fcall_begin done");
+}
+
+static void nr_php_frankenphp_request_handler_fcall_end(
+    zend_execute_data* execute_data NRUNUSED,
+    zval* return_value NRUNUSED) {
+  nrl_verbosedebug(NRL_INSTRUMENT,
+                   "frankenphp_request_handler_fcall_end started");
+  // emulate rshutdown
+  nr_php_txn_end(0, 0);
+  nrl_verbosedebug(NRL_INSTRUMENT, "frankenphp_request_handler_fcall_end done");
+}
+
+// Wrap the request handler with before and after hooks to emulate rinit and
+// rshutdown
+void nr_php_frankenphp_handle_request(INTERNAL_FUNCTION_PARAMETERS) {
+  zval* function = NULL;
+  zend_function* zf;
+  nruserfn_t* wr = NULL;
+
+  // Always end current transaction started when worker was started
+  // Maybe store package data?
+  nr_php_txn_end(1, 0);
+
+  zend_parse_parameters_ex(ZEND_PARSE_PARAMS_QUIET, ZEND_NUM_ARGS(), "z",
+                           &function);
+  zf = nr_php_zval_to_function(function);
+
+  wr = nr_php_wrap_callable(zf, NULL);
+  if (NULL == wr) {
+    nrl_verbosedebug(NRL_INSTRUMENT,
+                     "Failed to create wraprec for frankenphp request handler");
+    return;
+  }
+  wr->fcall_handlers.begin = nr_php_frankenphp_request_handler_fcall_begin;
+  wr->fcall_handlers.end = nr_php_frankenphp_request_handler_fcall_end;
+}
+#endif /* ZTS */

agent/php_frankenphp.h

@@ -0,0 +1,17 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef PHP_FRANKENPHP_H
+#define PHP_FRANKENPHP_H
+
+#include "php_includes.h"
+
+#ifdef ZTS
+
+extern void nr_php_frankenphp_handle_request(INTERNAL_FUNCTION_PARAMETERS);
+
+#endif
+
+#endif

agent/php_internal_instrument.c

@@ -12,6 +12,7 @@
 #include "php_explain.h"
 #include "php_explain_mysqli.h"
 #include "php_file_get_contents.h"
+#include "php_frankenphp.h"
 #include "php_globals.h"
 #include "php_hash.h"
 #include "php_httprequest_send.h"
@@ -113,6 +114,28 @@ static void nr_php_instrument_delegate(nrinternalfn_t* wraprec,
   (wraprec->inner_wrapper)(INTERNAL_FUNCTION_PARAM_PASSTHRU, wraprec);
 }
 
+#if ZEND_MODULE_API_NO >= ZEND_8_0_X_API_NO
+/*
+ * This delegate is used for the wrappers, which need to execute its inner
+ * wrapper on every call, even when not recording. This can be used for starting
+ * the transaction and thus needs to execute its inner wrapper to start
+ * recording.
+ */
+static void nr_php_instrument_delegate_always(nrinternalfn_t* wraprec,
+                                              INTERNAL_FUNCTION_PARAMETERS) {
+  if ((NULL == wraprec) || (NULL == wraprec->oldhandler)
+      || (NULL == wraprec->inner_wrapper)) {
+    /*
+     * This conditional should never happen:  The wraprec and its fields
+     * should be properly populated during construction.  Perhaps this should
+     * be changed into some sort of assertion.
+     */
+    return;
+  }
+  (wraprec->inner_wrapper)(INTERNAL_FUNCTION_PARAM_PASSTHRU, wraprec);
+}
+#endif
+
 #define NR_OUTER_WRAPPER_NAME(RAW) _nr_outer_wrapper_function_##RAW
 #define NR_OUTER_GLOBAL_NAME(RAW) _nr_outer_wrapper_global_##RAW
 #define NR_INNER_WRAPPER_NAME(RAW) _nr_inner_wrapper_function_##RAW
@@ -142,6 +165,13 @@ static void nr_php_instrument_delegate(nrinternalfn_t* wraprec,
     nr_php_instrument_delegate(NR_OUTER_GLOBAL_NAME(RAW),         \
                                INTERNAL_FUNCTION_PARAM_PASSTHRU); \
   }
+#define NR_OUTER_WRAPPER_DELEGATE_ALWAYS(RAW)                            \
+  static nrinternalfn_t* NR_OUTER_GLOBAL_NAME(RAW) = NULL;               \
+  static void ZEND_FASTCALL NR_OUTER_WRAPPER_NAME(RAW)(                  \
+      INTERNAL_FUNCTION_PARAMETERS) {                                    \
+    nr_php_instrument_delegate_always(NR_OUTER_GLOBAL_NAME(RAW),         \
+                                      INTERNAL_FUNCTION_PARAM_PASSTHRU); \
+  }
 #endif /* PHP < 7.3 */
 
 /*
@@ -3069,6 +3099,18 @@ NR_INNER_WRAPPER(exception_common) {
   }
 }
 
+#ifdef ZTS
+NR_INNER_WRAPPER(frankenphp_handle_request) {
+  nrl_verbosedebug(NRL_INIT, "frankenphp_handle_request started");
+
+  nr_php_frankenphp_handle_request(INTERNAL_FUNCTION_PARAM_PASSTHRU);
+
+  // Let frankenphp take over
+  nr_wrapper->oldhandler(INTERNAL_FUNCTION_PARAM_PASSTHRU);
+  nrl_verbosedebug(NRL_INIT, "frankenphp_handle_request done");
+}
+#endif
+
 NR_OUTER_WRAPPER(mysql_select_db)
 NR_OUTER_WRAPPER(mysql_selectdb)
 NR_OUTER_WRAPPER(mysql_close)
@@ -3379,6 +3421,10 @@ NR_OUTER_WRAPPER(dl)
 NR_OUTER_WRAPPER(set_exception_handler)
 NR_OUTER_WRAPPER(restore_exception_handler)
 
+#ifdef ZTS
+NR_OUTER_WRAPPER_DELEGATE_ALWAYS(frankenphp_handle_request)
+#endif /* ZTS */
+
 nrinternalfn_t* nr_wrapped_internal_functions = NULL;
 
 static nrinternalfn_t* nr_get_wraprec(void) {
@@ -3948,6 +3994,10 @@ void nr_php_generate_internal_wrap_records(void) {
                       exception_common, 0, 0)
   NR_INTERNAL_WRAPREC("restore_exception_handler", restore_exception_handler,
                       exception_common, 0, 0)
+#ifdef ZTS
+  NR_INTERNAL_WRAPREC("frankenphp_handle_request", frankenphp_handle_request,
+                      frankenphp_handle_request, 0, 0)
+#endif
 }
 
 /*

agent/php_observer.c

@@ -75,6 +75,7 @@
 static zend_observer_fcall_handlers nr_php_fcall_register_handlers(
     zend_execute_data* execute_data) {
   zend_observer_fcall_handlers handlers = {NULL, NULL};
+  nruserfn_t* wr = NULL;
   if (NULL == execute_data) {
     return handlers;
   }
@@ -83,7 +84,11 @@ static zend_observer_fcall_handlers nr_php_fcall_register_handlers(
     return handlers;
   }
 
-  if (0 == nr_php_recording()) {
+  if (0 == nr_php_recording()
+#ifdef ZTS
+      && !nr_streq(sapi_module.name, "frankenphp")
+#endif
+  ) {
     return handlers;
   }
 
@@ -110,23 +115,33 @@ static zend_observer_fcall_handlers nr_php_fcall_register_handlers(
     return handlers;
   }
 
-  if (!ZEND_OP_ARRAY_EXTENSION(
-          NR_OP_ARRAY, NR_PHP_PROCESS_GLOBALS(op_array_extension_handle))) {
+  // clang-format off
+  wr = ZEND_OP_ARRAY_EXTENSION(NR_OP_ARRAY, NR_PHP_PROCESS_GLOBALS(op_array_extension_handle));
+  if (NULL == wr) {
     zend_string* func_name = NR_OP_ARRAY->function_name;
-    zend_string* scope_name
-        = OP_ARRAY_IS_A_METHOD(NR_OP_ARRAY) ? NR_OP_ARRAY->scope->name : NULL;
-    nruserfn_t* wr
-        = nr_php_user_instrument_wraprec_hashmap_get(func_name, scope_name);
-    // store the wraprec in the op_array extension for the duration of the
-    // request for later lookup
-    ZEND_OP_ARRAY_EXTENSION(NR_OP_ARRAY,
-                            NR_PHP_PROCESS_GLOBALS(op_array_extension_handle))
-        = wr;
+    zend_string* scope_name = OP_ARRAY_IS_A_METHOD(NR_OP_ARRAY) ? NR_OP_ARRAY->scope->name : NULL;
+    wr = nr_php_user_instrument_wraprec_hashmap_get(func_name, scope_name);
+    // store the wraprec in the op_array extension for the duration of the request for later lookup
+    ZEND_OP_ARRAY_EXTENSION(NR_OP_ARRAY, NR_PHP_PROCESS_GLOBALS(op_array_extension_handle)) = wr;
+  } else {
+    if (nrl_should_print(NRL_VERBOSEDEBUG, NRL_INSTRUMENT)) {
+      nrl_verbosedebug(NRL_INSTRUMENT, "%s - wraprec already installed", __func__);
+    }
   }
 
+  // use default handlers for all user functions
   handlers.begin = nr_php_observer_fcall_begin;
   handlers.end = nr_php_observer_fcall_end;
+
+  // override default handlers with wraprec's custom handlers
+  if (NULL != wr) {
+    if (NULL != wr->fcall_handlers.begin)
+      handlers.begin = wr->fcall_handlers.begin;
+    if (NULL != wr->fcall_handlers.end)
+      handlers.end = wr->fcall_handlers.end;
+  }
   return handlers;
+  // clang-format on
 }
 
 #if ZEND_MODULE_API_NO > ZEND_8_0_X_API_NO /* PHP8.1+ */

agent/php_user_instrument.h

@@ -110,6 +110,9 @@ typedef struct _nruserfn_t {
 #if ZEND_MODULE_API_NO >= ZEND_7_4_X_API_NO
   char* wordpress_plugin_theme;
 #endif
+#if ZEND_MODULE_API_NO >= ZEND_8_0_X_API_NO
+  zend_observer_fcall_handlers fcall_handlers;
+#endif
 } nruserfn_t;
 
 #if ZEND_MODULE_API_NO >= ZEND_8_0_X_API_NO