refactor: rename PHP API

Author: nicolas-grekas

background_worker.go

@@ -271,15 +271,15 @@ func getLookup(thread *phpThread) *backgroundWorkerLookup {
 	return nil
 }
 
-// go_frankenphp_worker_get_vars starts background workers if needed, waits for them
+// go_frankenphp_get_vars starts background workers if needed, waits for them
 // to be ready, takes read locks, copies vars via C helper, and releases locks.
 // All locking/unlocking happens within this single Go call.
 //
 // callerVersions/outVersions: if callerVersions is non-nil and all versions match,
 // the copy is skipped entirely (returns 1). outVersions receives current versions.
 //
-//export go_frankenphp_worker_get_vars
-func go_frankenphp_worker_get_vars(threadIndex C.uintptr_t, names **C.char, nameLens *C.size_t, nameCount C.int, timeoutMs C.int, returnValue *C.zval, callerVersions *C.uint64_t, outVersions *C.uint64_t) *C.char {
+//export go_frankenphp_get_vars
+func go_frankenphp_get_vars(threadIndex C.uintptr_t, names **C.char, nameLens *C.size_t, nameCount C.int, timeoutMs C.int, returnValue *C.zval, callerVersions *C.uint64_t, outVersions *C.uint64_t) *C.char {
 	thread := phpThreads[threadIndex]
 	lookup := getLookup(thread)
 	if lookup == nil {
@@ -365,13 +365,13 @@ func go_frankenphp_worker_get_vars(threadIndex C.uintptr_t, names **C.char, name
 	return nil
 }
 
-//export go_frankenphp_worker_set_vars
-func go_frankenphp_worker_set_vars(threadIndex C.uintptr_t, varsPtr unsafe.Pointer, oldPtr *unsafe.Pointer) *C.char {
+//export go_frankenphp_set_vars
+func go_frankenphp_set_vars(threadIndex C.uintptr_t, varsPtr unsafe.Pointer, oldPtr *unsafe.Pointer) *C.char {
 	thread := phpThreads[threadIndex]
 
 	bgHandler, ok := thread.handler.(*backgroundWorkerThread)
 	if !ok || bgHandler.worker.backgroundWorker == nil {
-		return C.CString("frankenphp_worker_set_vars() can only be called from a background worker")
+		return C.CString("frankenphp_set_vars() can only be called from a background worker")
 	}
 
 	sk := bgHandler.worker.backgroundWorker

docs/background-workers.md

@@ -1,13 +1,13 @@
 # Background Workers
 
 Background workers are long-running PHP scripts that run outside the HTTP request cycle.
-They observe their environment and publish configuration that HTTP [workers](worker.md) can read in real time.
+They observe their environment and publish variables that HTTP [workers](worker.md) can read in real time.
 
 ## How It Works
 
 1. A background worker runs its own event loop (subscribe to Redis, watch files, poll an API...)
-2. It calls `frankenphp_worker_set_vars()` to publish a snapshot of key-value pairs
-3. HTTP workers call `frankenphp_worker_get_vars()` to read the latest snapshot
+2. It calls `frankenphp_set_vars()` to publish a snapshot of key-value pairs
+3. HTTP workers call `frankenphp_get_vars()` to read the latest snapshot
 4. The first `get_vars()` call blocks until the background worker has published - no startup race condition
 
 ## Configuration
@@ -42,15 +42,15 @@ example.com {
 
 ## PHP API
 
-### `frankenphp_worker_get_vars(string|array $name, float $timeout = 30.0): array`
+### `frankenphp_get_vars(string|array $name, float $timeout = 30.0): array`
 
-Starts a background worker (at-most-once) and returns its published variables.
+Starts a background worker (at-most-once) and returns its published vars.
 
 ```php
-$redis = frankenphp_worker_get_vars('redis-watcher');
+$redis = frankenphp_get_vars('redis-watcher');
 // ['MASTER_HOST' => '10.0.0.1', 'MASTER_PORT' => 6379]
 
-$all = frankenphp_worker_get_vars(['redis-watcher', 'feature-flags']);
+$all = frankenphp_get_vars(['redis-watcher', 'feature-flags']);
 // ['redis-watcher' => [...], 'feature-flags' => [...]]
 ```
 
@@ -60,18 +60,19 @@ $all = frankenphp_worker_get_vars(['redis-watcher', 'feature-flags']);
 - Throws `RuntimeException` on timeout, missing entrypoint, or background worker crash
 - Works in both worker and non-worker mode
 
-### `frankenphp_worker_set_vars(array $vars): void`
+### `frankenphp_set_vars(array $vars): void`
 
-Publishes a snapshot of key-value pairs from inside a background worker.
-Each call **replaces** the entire snapshot atomically.
+Publishes vars from inside a background worker.
+Each call **replaces** the entire vars array atomically.
 If the new value is identical (`===`) to the previous one, the call is a no-op.
 
-Supported types: `null`, `bool`, `int`, `float`, `string`, `array` (nested), and **enums**.
+Values can be `null`, scalars (`bool`, `int`, `float`, `string`), nested `array`s, or **enum**s.
+Objects, resources, and references are rejected.
 
 - Throws `RuntimeException` if not called from a background worker context
 - Throws `ValueError` if values contain objects, resources, or references
 
-### `frankenphp_worker_get_signaling_stream(): resource`
+### `frankenphp_get_worker_handle(): resource`
 
 Returns a readable stream for receiving signals from FrankenPHP.
 On shutdown or restart, the stream is closed - `fgets()` returns `false` (EOF).
@@ -81,7 +82,7 @@ Use `stream_select()` to wait between iterations instead of `sleep()`:
 function background_worker_should_stop(float $timeout = 0): bool
 {
     static $stream;
-    $stream ??= frankenphp_worker_get_signaling_stream();
+    $stream ??= frankenphp_get_worker_handle();
     $s = (int) $timeout;
 
     return match (@stream_select(...[[$stream], [], [], $s, (int) (($timeout - $s) * 1e6)])) {
@@ -118,7 +119,7 @@ function run_config_watcher(): void
     $redis->pconnect('127.0.0.1');
 
     do {
-        frankenphp_worker_set_vars([
+        frankenphp_set_vars([
             'maintenance' => (bool) $redis->get('maintenance_mode'),
             'feature_flags' => json_decode($redis->get('features'), true),
         ]);
@@ -134,23 +135,23 @@ to integrate the signaling stream into the event loop:
 ```php
 function run_redis_watcher(): void
 {
-    $signalingStream = frankenphp_worker_get_signaling_stream();
+    $signalingStream = frankenphp_get_worker_handle();
     $sentinel = Amp\Redis\createRedisClient('tcp://sentinel-host:26379');
 
     $subscription = $sentinel->subscribe('+switch-master');
 
     Amp\async(function () use ($subscription) {
         foreach ($subscription as $message) {
             [$name, $oldIp, $oldPort, $newIp, $newPort] = explode(' ', $message);
-            frankenphp_worker_set_vars([
+            frankenphp_set_vars([
                 'MASTER_HOST' => $newIp,
                 'MASTER_PORT' => (int) $newPort,
             ]);
         }
     });
 
     $master = $sentinel->rawCommand('SENTINEL', 'get-master-addr-by-name', 'mymaster');
-    frankenphp_worker_set_vars([
+    frankenphp_set_vars([
         'MASTER_HOST' => $master[0],
         'MASTER_PORT' => (int) $master[1],
     ]);
@@ -174,7 +175,7 @@ $app = new App();
 $app->boot();
 
 while (frankenphp_handle_request(function () use ($app) {
-    $config = frankenphp_worker_get_vars('config-watcher');
+    $config = frankenphp_get_vars('config-watcher');
 
     $_SERVER += ['APP_REDIS_HOST' => $config['MASTER_HOST'], 'APP_REDIS_PORT' => $config['MASTER_PORT']];
     $app->handle($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER);
@@ -186,8 +187,8 @@ while (frankenphp_handle_request(function () use ($app) {
 ### Graceful Degradation
 
 ```php
-if (function_exists('frankenphp_worker_get_vars')) {
-    $config = frankenphp_worker_get_vars('config-watcher');
+if (function_exists('frankenphp_get_vars')) {
+    $config = frankenphp_get_vars('config-watcher');
 } else {
     $config = ['MASTER_HOST' => getenv('REDIS_HOST') ?: '127.0.0.1'];
 }

frankenphp.c

@@ -838,54 +838,53 @@ PHP_FUNCTION(frankenphp_handle_request) {
 /* Persistent zval helpers: validation, deep-copy, immutable detection, enums */
 #include "bg_worker_vars.h"
 
-PHP_FUNCTION(frankenphp_worker_set_vars) {
-  zval *vars_array = NULL;
+PHP_FUNCTION(frankenphp_set_vars) {
+  zval *vars = NULL;
 
   ZEND_PARSE_PARAMETERS_START(1, 1);
-  Z_PARAM_ARRAY(vars_array);
+  Z_PARAM_ARRAY(vars);
   ZEND_PARSE_PARAMETERS_END();
 
   /* Skip if the new value is identical to the last one.
    * Always update the cache so the next comparison can use pointer equality. */
   if (Z_TYPE(last_set_vars_zval) != IS_UNDEF &&
-      zend_is_identical(vars_array, &last_set_vars_zval)) {
+      zend_is_identical(vars, &last_set_vars_zval)) {
     zval_ptr_dtor(&last_set_vars_zval);
-    ZVAL_COPY(&last_set_vars_zval, vars_array);
+    ZVAL_COPY(&last_set_vars_zval, vars);
     return;
   }
 
-  HashTable *ht = Z_ARRVAL_P(vars_array);
+  HashTable *ht = Z_ARRVAL_P(vars);
 
   if (bg_worker_is_immutable(ht)) {
-    /* Fast path: immutable arrays are already in shared memory.
-     * No validation needed (immutable arrays contain only safe types).
-     * No deep-copy needed. */
+    /* Fast path: immutable arrays are already in shared memory. */
     void *old = NULL;
-    char *error = go_frankenphp_worker_set_vars(thread_index, ht, &old);
+    char *error = go_frankenphp_set_vars(thread_index, ht, &old);
     if (error) {
       zend_throw_exception(spl_ce_RuntimeException, error, 0);
       free(error);
       RETURN_THROWS();
     }
     bg_worker_free_stored_vars(old);
   } else {
-    /* Slow path: validate, deep-copy to persistent memory */
+    /* Validate nested values */
     zval *val;
     ZEND_HASH_FOREACH_VAL(ht, val) {
       if (!bg_worker_validate_zval(val)) {
-        zend_value_error("Values must be null, scalars, arrays, or enums; "
-                         "objects and resources are not allowed");
+        zend_value_error(
+            "Vars values must be null, scalars, arrays, or enums; "
+            "objects and resources are not allowed");
         RETURN_THROWS();
       }
     }
     ZEND_HASH_FOREACH_END();
 
     zval persistent;
-    bg_worker_persist_zval(&persistent, vars_array);
+    bg_worker_persist_zval(&persistent, vars);
 
     void *old = NULL;
     char *error =
-        go_frankenphp_worker_set_vars(thread_index, Z_ARRVAL(persistent), &old);
+        go_frankenphp_set_vars(thread_index, Z_ARRVAL(persistent), &old);
     if (error) {
       bg_worker_free_persistent_zval(&persistent);
       zend_throw_exception(spl_ce_RuntimeException, error, 0);
@@ -899,7 +898,7 @@ PHP_FUNCTION(frankenphp_worker_set_vars) {
   if (Z_TYPE(last_set_vars_zval) != IS_UNDEF) {
     zval_ptr_dtor(&last_set_vars_zval);
   }
-  ZVAL_COPY(&last_set_vars_zval, vars_array);
+  ZVAL_COPY(&last_set_vars_zval, vars);
 }
 
 /* Copy vars from persistent storage into a PHP zval.
@@ -919,22 +918,22 @@ bool frankenphp_worker_copy_vars(zval *dst, int count, char **names,
 
   array_init(dst);
   for (int i = 0; i < count; i++) {
-    zval worker_vars;
+    zval entry;
     if (ptrs[i]) {
-      bg_worker_read_stored_vars(&worker_vars, ptrs[i]);
+      bg_worker_read_stored_vars(&entry, ptrs[i]);
       if (EG(exception)) {
-        zval_ptr_dtor(&worker_vars);
+        zval_ptr_dtor(&entry);
         return false;
       }
     } else {
-      array_init(&worker_vars);
+      array_init(&entry);
     }
-    add_assoc_zval_ex(dst, names[i], name_lens[i], &worker_vars);
+    add_assoc_zval_ex(dst, names[i], name_lens[i], &entry);
   }
   return true;
 }
 
-PHP_FUNCTION(frankenphp_worker_get_vars) {
+PHP_FUNCTION(frankenphp_get_vars) {
   zval *names = NULL;
   double timeout = 30.0;
 
@@ -972,7 +971,7 @@ PHP_FUNCTION(frankenphp_worker_get_vars) {
       }
     }
 
-    char *error = go_frankenphp_worker_get_vars(
+    char *error = go_frankenphp_get_vars(
         thread_index, &name_ptr, &name_len_val, 1, timeout_ms, return_value,
         cached ? &caller_version : NULL, &out_version);
     if (error) {
@@ -1034,7 +1033,7 @@ PHP_FUNCTION(frankenphp_worker_get_vars) {
   }
   ZEND_HASH_FOREACH_END();
 
-  char *error = go_frankenphp_worker_get_vars(
+  char *error = go_frankenphp_get_vars(
       thread_index, name_ptrs, name_lens_arr, name_count, timeout_ms,
       return_value, NULL, NULL);
   free(name_ptrs);
@@ -1046,12 +1045,12 @@ PHP_FUNCTION(frankenphp_worker_get_vars) {
   }
 }
 
-PHP_FUNCTION(frankenphp_worker_get_signaling_stream) {
+PHP_FUNCTION(frankenphp_get_worker_handle) {
   ZEND_PARSE_PARAMETERS_NONE();
 
   if (!is_background_worker) {
     zend_throw_exception(spl_ce_RuntimeException,
-                         "frankenphp_worker_get_signaling_stream() can only "
+                         "frankenphp_get_worker_handle() can only "
                          "be called from a background worker",
                          0);
     RETURN_THROWS();

frankenphp.stub.php

@@ -17,17 +17,17 @@
 function frankenphp_handle_request(callable $callback): bool {}
 
 /**
- * @param array<null|scalar|\UnitEnum|array<mixed>> $vars Nested arrays must recursively follow the same type constraints
+ * @param array<string, null|scalar|\UnitEnum|array<mixed>> $vars
  */
-function frankenphp_worker_set_vars(array $vars): void {}
+function frankenphp_set_vars(array $vars): void {}
 
 /**
- * @return array<null|scalar|array<mixed>|\UnitEnum> Nested arrays recursively follow the same type constraints
+ * @return array<string, null|scalar|array<mixed>|\UnitEnum>
  */
-function frankenphp_worker_get_vars(string|array $name, float $timeout = 30.0): array {}
+function frankenphp_get_vars(string|array $name, float $timeout = 30.0): array {}
 
 /** @return resource */
-function frankenphp_worker_get_signaling_stream() {}
+function frankenphp_get_worker_handle() {}
 
 function headers_send(int $status = 200): int {}
 

frankenphp_arginfo.h

@@ -5,16 +5,16 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_handle_request, 0, 1,
 	ZEND_ARG_TYPE_INFO(0, callback, IS_CALLABLE, 0)
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_worker_set_vars, 0, 1, IS_VOID, 0)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_set_vars, 0, 1, IS_VOID, 0)
 	ZEND_ARG_TYPE_INFO(0, vars, IS_ARRAY, 0)
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_worker_get_vars, 0, 1, IS_ARRAY, 0)
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_frankenphp_get_vars, 0, 1, IS_ARRAY, 0)
 	ZEND_ARG_TYPE_MASK(0, name, MAY_BE_STRING|MAY_BE_ARRAY, NULL)
 	ZEND_ARG_TYPE_INFO_WITH_DEFAULT_VALUE(0, timeout, IS_DOUBLE, 0, "30.0")
 ZEND_END_ARG_INFO()
 
-ZEND_BEGIN_ARG_INFO_EX(arginfo_frankenphp_worker_get_signaling_stream, 0, 0, 0)
+ZEND_BEGIN_ARG_INFO_EX(arginfo_frankenphp_get_worker_handle, 0, 0, 0)
 ZEND_END_ARG_INFO()
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_headers_send, 0, 0, IS_LONG, 0)
@@ -55,9 +55,9 @@ ZEND_END_ARG_INFO()
 
 
 ZEND_FUNCTION(frankenphp_handle_request);
-ZEND_FUNCTION(frankenphp_worker_set_vars);
-ZEND_FUNCTION(frankenphp_worker_get_vars);
-ZEND_FUNCTION(frankenphp_worker_get_signaling_stream);
+ZEND_FUNCTION(frankenphp_set_vars);
+ZEND_FUNCTION(frankenphp_get_vars);
+ZEND_FUNCTION(frankenphp_get_worker_handle);
 ZEND_FUNCTION(headers_send);
 ZEND_FUNCTION(frankenphp_finish_request);
 ZEND_FUNCTION(frankenphp_request_headers);
@@ -68,9 +68,9 @@ ZEND_FUNCTION(frankenphp_log);
 
 static const zend_function_entry ext_functions[] = {
 	ZEND_FE(frankenphp_handle_request, arginfo_frankenphp_handle_request)
-	ZEND_FE(frankenphp_worker_set_vars, arginfo_frankenphp_worker_set_vars)
-	ZEND_FE(frankenphp_worker_get_vars, arginfo_frankenphp_worker_get_vars)
-	ZEND_FE(frankenphp_worker_get_signaling_stream, arginfo_frankenphp_worker_get_signaling_stream)
+	ZEND_FE(frankenphp_set_vars, arginfo_frankenphp_set_vars)
+	ZEND_FE(frankenphp_get_vars, arginfo_frankenphp_get_vars)
+	ZEND_FE(frankenphp_get_worker_handle, arginfo_frankenphp_get_worker_handle)
 	ZEND_FE(headers_send, arginfo_headers_send)
 	ZEND_FE(frankenphp_finish_request, arginfo_frankenphp_finish_request)
 	ZEND_FALIAS(fastcgi_finish_request, frankenphp_finish_request, arginfo_fastcgi_finish_request)

testdata/background-worker-binary-entrypoint.php

@@ -2,7 +2,7 @@
 
 require __DIR__ . '/background-worker-helper.php';
 
-frankenphp_worker_set_vars([
+frankenphp_set_vars([
     'BINARY_TEST' => "hello\x00world",
     'UTF8_TEST' => "héllo wörld 🚀",
     'EMPTY_VAL' => "",

testdata/background-worker-binary-safe.php

@@ -2,7 +2,7 @@
 
 frankenphp_handle_request(function () {
     try {
-        $vars = frankenphp_worker_get_vars('binary-worker', 5.0);
+        $vars = frankenphp_get_vars('binary-worker', 5.0);
     } catch (\Throwable $e) {
         echo 'ERROR:' . $e->getMessage();
         return;