refactor: rename PHP API

Author: nicolas-grekas

background_worker.go

@@ -58,12 +58,11 @@ func (l *backgroundWorkerLookup) Resolve(name string) *backgroundWorkerRegistry
 }
 
 type backgroundWorkerRegistry struct {
-	entrypoint     string
-	num            int      // threads per background worker (0 = lazy-start with 1 thread)
-	maxWorkers     int      // max lazy-started instances (0 = unlimited)
-	autoStartNames []string // names to start at boot when num >= 1
-	mu             sync.Mutex
-	workers        map[string]*backgroundWorkerState
+	entrypoint string
+	num        int // threads per background worker (0 = lazy-start with 1 thread)
+	maxWorkers int // max lazy-started instances (0 = unlimited)
+	mu         sync.Mutex
+	workers    map[string]*backgroundWorkerState
 }
 
 func newBackgroundWorkerRegistry(entrypoint string) *backgroundWorkerRegistry {
@@ -84,10 +83,6 @@ func (registry *backgroundWorkerRegistry) SetNum(num int) {
 	registry.num = num
 }
 
-func (registry *backgroundWorkerRegistry) AddAutoStartNames(names ...string) {
-	registry.autoStartNames = append(registry.autoStartNames, names...)
-}
-
 func (registry *backgroundWorkerRegistry) SetMaxWorkers(max int) {
 	registry.maxWorkers = max
 }
@@ -125,7 +120,6 @@ func buildBackgroundWorkerLookups(workers []*worker, opts []workerOpt) map[strin
 		if phpName != "" && phpName != w.fileName {
 			// Named background worker
 			if o.num > 0 {
-				registry.AddAutoStartNames(phpName)
 				registry.SetNum(o.num)
 			}
 			lookup.AddNamed(phpName, registry)
@@ -271,15 +265,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 +359,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 {}