refactor: rename PHP API and widen state types

Renames:
- frankenphp_worker_set_vars - frankenphp_set_worker_state
- frankenphp_worker_get_vars - frankenphp_get_worker_state
- frankenphp_worker_get_signaling_stream - frankenphp_get_worker_handle
- Internal: varsPtr - statePtr, varsVersion - stateVersion, etc.

Type widening:
- set_worker_state accepts mixed (null, scalars, arrays, enums)
- get_worker_state returns mixed
- Non-array values are internally wrapped in a single-element array
  for uniform persistent storage, and unwrapped on read.

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_worker_state 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_worker_state
+func go_frankenphp_get_worker_state(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 {
@@ -330,7 +330,7 @@ func go_frankenphp_worker_get_vars(threadIndex C.uintptr_t, names **C.char, name
 		outVSlice := unsafe.Slice(outVersions, n)
 		allMatch := true
 		for i, sk := range sks {
-			v := sk.varsVersion.Load()
+			v := sk.stateVersion.Load()
 			outVSlice[i] = C.uint64_t(v)
 			if uint64(callerVSlice[i]) != v {
 				allMatch = false
@@ -341,20 +341,24 @@ func go_frankenphp_worker_get_vars(threadIndex C.uintptr_t, names **C.char, name
 		}
 	}
 
-	// Take all read locks, collect pointers, copy via C helper, then release
+	// Take all read locks, collect pointers and scalar flags, copy via C helper, then release
 	ptrs := make([]unsafe.Pointer, n)
+	scalarFlags := make([]C.int, n)
 	for i, sk := range sks {
 		sk.mu.RLock()
-		ptrs[i] = sk.varsPtr
+		ptrs[i] = sk.statePtr
+		if sk.stateIsScalar {
+			scalarFlags[i] = 1
+		}
 	}
 
-	C.frankenphp_worker_copy_vars(returnValue, C.int(n), names, nameLens, (*unsafe.Pointer)(unsafe.Pointer(&ptrs[0])))
+	C.frankenphp_worker_copy_state(returnValue, C.int(n), names, nameLens, (*unsafe.Pointer)(unsafe.Pointer(&ptrs[0])), &scalarFlags[0])
 
 	// Write versions while locks are still held
 	if outVersions != nil {
 		outVSlice := unsafe.Slice(outVersions, n)
 		for i, sk := range sks {
-			outVSlice[i] = C.uint64_t(sk.varsVersion.Load())
+			outVSlice[i] = C.uint64_t(sk.stateVersion.Load())
 		}
 	}
 
@@ -365,21 +369,22 @@ 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_worker_state
+func go_frankenphp_set_worker_state(threadIndex C.uintptr_t, statePtr unsafe.Pointer, isScalar C.int, 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_worker_state() can only be called from a background worker")
 	}
 
 	sk := bgHandler.worker.backgroundWorker
 
 	sk.mu.Lock()
-	*oldPtr = sk.varsPtr
-	sk.varsPtr = varsPtr
-	sk.varsVersion.Add(1)
+	*oldPtr = sk.statePtr
+	sk.statePtr = statePtr
+	sk.stateIsScalar = isScalar != 0
+	sk.stateVersion.Add(1)
 	sk.mu.Unlock()
 
 	sk.readyOnce.Do(func() {

bg_worker_vars.h

@@ -25,7 +25,7 @@ static bool bg_worker_is_immutable(HashTable *ht) {
 }
 
 /* Free a stored vars pointer only if it's a persistent copy (not immutable). */
-static void bg_worker_free_stored_vars(void *ptr) {
+static void bg_worker_free_stored_state(void *ptr) {
   if (ptr != NULL) {
     HashTable *ht = (HashTable *)ptr;
     if (!bg_worker_is_immutable(ht)) {
@@ -38,7 +38,7 @@ static void bg_worker_free_stored_vars(void *ptr) {
 
 /* Copy or reference a stored vars pointer to request memory.
  * Immutable arrays are returned as zero-copy references. */
-static void bg_worker_read_stored_vars(zval *dst, void *ptr) {
+static void bg_worker_read_stored_state(zval *dst, void *ptr) {
   HashTable *ht = (HashTable *)ptr;
   if (bg_worker_is_immutable(ht)) {
     ZVAL_ARR(dst, ht); /* zero-copy: immutable = safe to share */

docs/background-workers.md

@@ -6,9 +6,9 @@ They observe their environment and publish configuration that HTTP [workers](wor
 ## 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
-4. The first `get_vars()` call blocks until the background worker has published - no startup race condition
+2. It calls `frankenphp_set_worker_state()` to publish a snapshot of key-value pairs
+3. HTTP workers call `frankenphp_get_worker_state()` to read the latest snapshot
+4. The first `get_worker_state()` call blocks until the background worker has published - no startup race condition
 
 ## Configuration
 
@@ -27,51 +27,52 @@ example.com {
             name feature-flags
         }
 
-        # Catch-all - handles any unlisted name via get_vars()
+        # Catch-all - handles any unlisted name via get_worker_state()
         worker /app/bin/console {
             background
         }
     }
 }
 ```
 
-- **Named** (with `name`): lazy-started on first `get_vars()` call, or auto-started at boot if `num 1` is set.
+- **Named** (with `name`): lazy-started on first `get_worker_state()` call, or auto-started at boot if `num 1` is set.
 - **Catch-all** (no `name`): also lazy-started. Use `max_threads` to cap how many can be created (defaults to 16). Not declaring a catch-all forbids unlisted names.
 - Each `php_server` block has its own isolated scope - two blocks can use the same worker names without conflict.
 - `max_consecutive_failures`, `env`, and `watch` work the same as HTTP workers.
 
 ## PHP API
 
-### `frankenphp_worker_get_vars(string|array $name, float $timeout = 30.0): array`
+### `frankenphp_get_worker_state(string|array $name, float $timeout = 30.0): mixed`
 
-Starts a background worker (at-most-once) and returns its published variables.
+Starts a background worker (at-most-once) and returns its published state.
 
 ```php
-$redis = frankenphp_worker_get_vars('redis-watcher');
+$redis = frankenphp_get_worker_state('redis-watcher');
 // ['MASTER_HOST' => '10.0.0.1', 'MASTER_PORT' => 6379]
 
-$all = frankenphp_worker_get_vars(['redis-watcher', 'feature-flags']);
+$all = frankenphp_get_worker_state(['redis-watcher', 'feature-flags']);
 // ['redis-watcher' => [...], 'feature-flags' => [...]]
 ```
 
-- First call blocks until the background worker calls `set_vars()` or the timeout expires
+- First call blocks until the background worker calls `set_worker_state()` or the timeout expires
 - Subsequent calls return the latest snapshot immediately
 - Within a single HTTP request, repeated calls with the same name return the same cached array - `===` comparisons are O(1)
 - 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_worker_state(mixed $state): void`
 
-Publishes a snapshot of key-value pairs from inside a background worker.
-Each call **replaces** the entire snapshot atomically.
+Publishes state from inside a background worker.
+Each call **replaces** the entire state 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**.
+State can be `null`, a scalar (`bool`, `int`, `float`, `string`), an `array` (nested), or an **enum**.
+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_worker_state([
             '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_worker_state([
                 'MASTER_HOST' => $newIp,
                 'MASTER_PORT' => (int) $newPort,
             ]);
         }
     });
 
     $master = $sentinel->rawCommand('SENTINEL', 'get-master-addr-by-name', 'mymaster');
-    frankenphp_worker_set_vars([
+    frankenphp_set_worker_state([
         '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_worker_state('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_worker_state')) {
+    $config = frankenphp_get_worker_state('config-watcher');
 } else {
     $config = ['MASTER_HOST' => getenv('REDIS_HOST') ?: '127.0.0.1'];
 }
@@ -201,5 +202,5 @@ if (function_exists('frankenphp_worker_get_vars')) {
 - `$_SERVER['FRANKENPHP_WORKER_NAME']` is set for all workers (HTTP and background)
 - `$_SERVER['FRANKENPHP_WORKER_BACKGROUND']` is `true` for background workers, `false` for HTTP workers
 - `$_SERVER['argv']` = `[entrypoint, name]` in background workers (for `bin/console` compatibility)
-- Crash recovery with automatic restart and exponential backoff. During the restart window, `get_vars` returns the last published data (stale but available). A warning is logged on crash (`background worker exited, restarting`).
+- Crash recovery with automatic restart and exponential backoff. During the restart window, `get_worker_state` returns the last published data (stale but available). A warning is logged on crash (`background worker exited, restarting`).
 - On shutdown/restart: the signaling stream is closed (EOF). Workers have 5 seconds to exit. Stuck workers are force-killed on Linux and Windows.