feat(agent): add per-fiber globals (#1208)

## Summary

Each PHP Fiber now gets its own snapshot of the request-scoped globals
the
agent relies on (`ctx`), so instrumentation running inside
a fiber no longer trips over state owned by the main context (or another
fiber). The fiber observer hooks already in place from the parent branch
are wired up to populate, swap, and tear down these snapshots; the
`NRPRG_CTX` accessor transparently reads from the active
fiber's snapshot when one is set.

All new behavior is gated on PHP 8.1+. 

## What changed

**Per-fiber globals (`agent/php_fibers.{c,h}`, new)**
- New `fiber_globals_t` = `{ ctx_globals_t* }`.
- `nr_fiber_copy_ctx_globals` deep-copy the parts a fiber should own. 
- A per-request `fiber_globals_map` (keyed by `"%p"` of the
`zend_fiber_context*`) holds these snapshots; it has a destructor so
removed
entries are fully cleaned up. Init is lazy on first fiber; teardown
happens
in `nr_php_post_deactivate`. `php_rshutdown.c` clears
`NRPRG(fiber_globals)`
before normal global teardown so the existing free paths don't reach
into a
  snapshot.

**OAPI fiber observer wiring (`agent/php_observer.c`)**
- `nr_fiber_init_observe`: lazy-init `fiber_globals_map`, add a snapshot
for
  the new fiber under its `"%p"` key.
- `nr_fiber_destroy_observe`: remove the snapshot for that fiber.
- `nr_fiber_switch_observe`: at the end of the existing switch logic,
swap
  `NRPRG(fiber_globals)` to the destination context's snapshot via
  `nr_fiber_switch_global_context`.

**Globals accessors (`agent/php_newrelic.h`)**
- New `fiber_globals_t` struct; `NRPRG(fiber_globals_map)` and
  `NRPRG(fiber_globals)` added to module globals.
- On PHP 8.1+, `NRPRG_CTX(Y)` resolves through
`NRPRG(fiber_globals)` when it's non-NULL, otherwise read the
main-context
globals exactly as before. Callers don't have to know which context
they're
  in. PHP < 8.1 macros are unchanged.

---------

Co-authored-by: Amber Sistla <asistla@newrelic.com>

Author: bduranleau-nr

agent/Makefile.frag

@@ -85,6 +85,7 @@ TEST_BINARIES = \
 	tests/test_curl_md \
 	tests/test_datastore \
 	tests/test_environment \
+	tests/test_fibers \
 	tests/test_fw_codeigniter \
 	tests/test_fw_drupal \
 	tests/test_fw_laravel_queue \

agent/config.m4

@@ -213,7 +213,7 @@ if test "$PHP_NEWRELIC" = "yes"; then
   php_api_distributed_trace.c php_api_internal.c php_autorum.c \
   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_explain_pdo_mysql.c php_extension.c php_fibers.c php_file_get_contents.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 \

agent/lib_predis.c

@@ -81,16 +81,7 @@ const zend_long nr_predis_default_port = 6379;
 static NR_PHP_WRAPPER_PROTOTYPE(nr_predis_connection_readResponse);
 static NR_PHP_WRAPPER_PROTOTYPE(nr_predis_connection_writeRequest);
 
-static void nr_predis_command_destroy(nrtime_t* time) {
-  nr_free(time);
-}
-
 static inline nr_hashmap_t* nr_predis_get_commands(TSRMLS_D) {
-  if (NULL == NRPRG_CTX(predis_commands)) {
-    NRPRG_CTX(predis_commands)
-        = nr_hashmap_create((nr_hashmap_dtor_func_t)nr_predis_command_destroy);
-  }
-
   return NRPRG_CTX(predis_commands);
 }
 

agent/php_fibers.c

@@ -0,0 +1,226 @@
+/*
+ * Copyright 2026 New Relic Corporation. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * This file handles fibers instrumentation.
+ */
+
+#include "php_includes.h"
+#include "php_compat.h"
+#include "php_fibers.h"
+#include "php_agent.h"
+#include "php_newrelic.h"
+#include "php_zval.h"
+#include "util_hashmap.h"
+#include "util_logging.h"
+#include "util_memory.h"
+#include "util_stack.h"
+#include "util_strings.h"
+#include "zend_types.h"
+
+#if ZEND_MODULE_API_NO >= ZEND_8_1_X_API_NO
+
+#define COPY_BASIC(x) (dest->x = src->x)
+#define COPY_POINTER(x) (dest->x = &src->x)
+#define COPY_STRING(x) (dest->x = src->x ? nr_strdup(src->x) : NULL)
+#define COPY_STACK(x, y) (dest->x = nr_stack_copy(&src->x, y))
+
+static void* copy_elem_zval(void* elem) {
+  if (NULL == elem) {
+    return NULL;
+  }
+  zval* copy = nr_php_zval_alloc();
+  ZVAL_DUP(copy, elem);
+  return copy;
+}
+
+static void* copy_elem_ident(void* elem) {
+  return elem;
+}
+
+static void* copy_elem_str(void* elem) {
+  return nr_strdup((char*)elem);
+}
+
+static void fiber_str_dtor(void* e, NRUNUSED void* d) {
+  nr_free(e);
+}
+
+static void nr_ctx_global_deep_copy(ctx_globals_t* dest, ctx_globals_t* src) {
+  if (NULL == dest) {
+    return;
+  }
+
+  COPY_STRING(doctrine_dql);
+
+  dest->drupal_http_request_depth = 0;
+
+  COPY_BASIC(php_cur_stack_depth);
+
+  COPY_STRING(mysql_last_conn);
+  COPY_STRING(pgsql_last_conn);
+
+  COPY_BASIC(datastore_connections);
+
+  COPY_BASIC(deprecated_capture_request_parameters);
+  COPY_BASIC(check_cufa);
+
+  COPY_BASIC(predis_commands);
+
+  dest->context_root = NULL;
+
+  COPY_STACK(drupal_invoke_all_hooks, copy_elem_zval);
+  COPY_STACK(drupal_invoke_all_states, copy_elem_ident);
+
+  dest->drupal_http_request_segment = NULL;
+
+  COPY_STACK(wordpress_tags, copy_elem_str);
+  dest->wordpress_tags.dtor = fiber_str_dtor;
+  COPY_STACK(wordpress_tag_states, copy_elem_ident);
+  COPY_STACK(predis_ctxs, copy_elem_str);
+}
+
+#undef COPY_STACK
+#undef COPY_STRING
+#undef COPY_BASIC
+
+ctx_globals_t* nr_fiber_copy_ctx_globals(ctx_globals_t* src) {
+  ctx_globals_t* fiber_ctx_globals = NULL;
+
+  if (NULL == src) {
+    return NULL;
+  }
+
+  fiber_ctx_globals = nr_malloc(sizeof(ctx_globals_t));
+
+  nr_ctx_global_deep_copy(fiber_ctx_globals, src);
+
+  return fiber_ctx_globals;
+}
+
+void free_fiber_globals(void* fiber_globals) {
+  fiber_globals_t* f = (fiber_globals_t*)fiber_globals;
+
+  if (NULL == fiber_globals) {
+    nrl_warning(NRL_AGENT, "Failed to free fiber globals, target is NULL");
+    return;
+  }
+
+  if (NULL == f->ctx_globals) {
+    nrl_warning(NRL_AGENT, "Failed to free fiber globals, ctx_globals is NULL");
+    nr_free(f);
+    return;
+  }
+
+  nr_free(f->ctx_globals->doctrine_dql);
+  nr_free(f->ctx_globals->mysql_last_conn);
+  nr_free(f->ctx_globals->pgsql_last_conn);
+  nr_stack_destroy_fields(&f->ctx_globals->drupal_invoke_all_hooks);
+  nr_stack_destroy_fields(&f->ctx_globals->drupal_invoke_all_states);
+  nr_stack_destroy_fields(&f->ctx_globals->wordpress_tags);
+  nr_stack_destroy_fields(&f->ctx_globals->wordpress_tag_states);
+  nr_stack_destroy_fields(&f->ctx_globals->predis_ctxs);
+  nr_free(f->ctx_globals);
+  nr_free(f);
+}
+
+nr_status_t nr_fiber_init_global_hashmap(nr_hashmap_t** fiber_globals_map) {
+  if (NULL == fiber_globals_map) {
+    return NR_FAILURE;
+  }
+  if (NULL != *fiber_globals_map) {
+    return NR_FAILURE;
+  }
+
+  *fiber_globals_map = nr_hashmap_create(free_fiber_globals);
+  return NR_SUCCESS;
+}
+
+nr_status_t nr_fiber_destroy_global_hashmap(nr_hashmap_t** fiber_globals_map) {
+  if (NULL == fiber_globals_map) {
+    return NR_FAILURE;
+  }
+  if (NULL != *fiber_globals_map) {
+    nr_hashmap_destroy(fiber_globals_map);
+  }
+  return NR_SUCCESS;
+}
+
+nr_status_t nr_add_fiber_context_to_global_hashmap(
+    nr_hashmap_t* fiber_globals_map,
+    ctx_globals_t* src_ctx_globals,
+    const char* key) {
+  fiber_globals_t* fg = NULL;
+  ctx_globals_t* cg = NULL;
+
+  if (NULL == key || nr_strlen(key) < 1) {
+    return NR_FAILURE;
+  }
+
+  if (NULL == fiber_globals_map) {
+    return NR_FAILURE;
+  }
+
+  fg = nr_malloc(sizeof(fiber_globals_t));
+  cg = nr_fiber_copy_ctx_globals(src_ctx_globals);
+  if (NULL == cg) {
+    nr_free(fg);
+    return NR_FAILURE;
+  }
+
+  fg->ctx_globals = cg;
+
+  nr_hashmap_update(fiber_globals_map, key, nr_strlen(key), fg);
+
+  return NR_SUCCESS;
+}
+
+nr_status_t nr_remove_fiber_context_from_global_hashmap(
+    nr_hashmap_t* fiber_globals_map,
+    const char* key) {
+  if (nr_strempty(key)) {
+    return NR_FAILURE;
+  }
+
+  if (NULL == fiber_globals_map) {
+    return NR_FAILURE;
+  }
+
+  return nr_hashmap_delete(fiber_globals_map, key, nr_strlen(key));
+}
+
+nr_status_t nr_fiber_switch_global_context(nr_hashmap_t* fiber_globals_map,
+                                           fiber_globals_t** fiber_global_ptr,
+                                           const char* key) {
+  fiber_globals_t* fg = NULL;
+
+  if (NULL == fiber_global_ptr) {
+    return NR_FAILURE;
+  }
+
+  if (NULL == key) {
+    // a NULL key indicates we're in the MAIN php context rather than a fiber.
+    // Set the fiber pointer to NULL to prevent using the fiber-specific
+    // accessors.
+    *fiber_global_ptr = NULL;
+    return NR_SUCCESS;
+  }
+
+  if (NULL == fiber_globals_map) {
+    *fiber_global_ptr = NULL;
+    return NR_FAILURE;
+  }
+
+  fg = nr_hashmap_get(fiber_globals_map, key, nr_strlen(key));
+
+  if (NULL == fg) {
+    *fiber_global_ptr = NULL;
+    return NR_FAILURE;
+  }
+
+  *fiber_global_ptr = fg;
+
+  return NR_SUCCESS;
+}
+
+#endif  // PHP 8.1+