feat: hide background-worker functions in CLI mode

In CLI mode (frankenphp php-cli), there is no worker pool and no SAPI
request cycle; the background-worker API is meaningless. Rather than
throwing at call time, the four functions are now unregistered from
the function table in MINIT when the SAPI is "cli":

  frankenphp_require_background_worker
  frankenphp_set_vars
  frankenphp_get_vars
  frankenphp_get_worker_handle

This lets library code detect the mode cleanly via function_exists()
and fall back to alternative config sources without try/catch.

HTTP-mode set_vars cannot be hidden the same way because the context
(HTTP worker vs background worker) is per-thread, not per-process;
threads share the PHP module and function table. Runtime throw stays
the approach there, matching PHP's convention for pcntl_*/posix_*.

Author: nicolas-grekas

cli_test.go

@@ -32,6 +32,24 @@ func TestExecuteScriptCLI(t *testing.T) {
 	assert.Contains(t, stdoutStderrStr, "From the CLI")
 }
 
+func TestBackgroundWorkerFunctionsHiddenInCLI(t *testing.T) {
+	if _, err := os.Stat("internal/testcli/testcli"); err != nil {
+		t.Skip("internal/testcli/testcli has not been compiled, run `cd internal/testcli/ && go build`")
+	}
+
+	cmd := exec.Command("internal/testcli/testcli", "testdata/bg-worker-cli-hidden.php")
+	stdoutStderr, err := cmd.CombinedOutput()
+	assert.NoError(t, err)
+
+	out := string(stdoutStderr)
+	assert.Contains(t, out, "frankenphp_require_background_worker:hidden")
+	assert.Contains(t, out, "frankenphp_set_vars:hidden")
+	assert.Contains(t, out, "frankenphp_get_vars:hidden")
+	assert.Contains(t, out, "frankenphp_get_worker_handle:hidden")
+	// unrelated functions must remain available
+	assert.Contains(t, out, "frankenphp_log:exists")
+}
+
 func TestExecuteCLICode(t *testing.T) {
 	if _, err := os.Stat("internal/testcli/testcli"); err != nil {
 		t.Skip("internal/testcli/testcli has not been compiled, run `cd internal/testcli/ && go build`")

docs/background-workers.md

@@ -222,6 +222,8 @@ $config = frankenphp_get_vars('config-watcher');
 
 ### Graceful Degradation
 
+The `frankenphp_require_background_worker`, `frankenphp_set_vars`, `frankenphp_get_vars`, and `frankenphp_get_worker_handle` functions are only exposed when FrankenPHP runs in SAPI mode (HTTP server). In CLI mode (`frankenphp php-cli ...`), they are hidden, so `function_exists()` returns `false`. Library code can rely on this to degrade gracefully:
+
 ```php
 if (function_exists('frankenphp_get_vars')) {
     frankenphp_require_background_worker('config-watcher');

frankenphp.c

@@ -1236,6 +1236,18 @@ PHP_MINIT_FUNCTION(frankenphp) {
   pthread_atfork(NULL, NULL, frankenphp_fork_child);
 #endif
 
+  /* Background workers do not exist in CLI mode (no worker pool, no SAPI
+   * request cycle). Hide the related functions so function_exists() reports
+   * false and library code can detect this cleanly. */
+  if (sapi_module.name && strcmp(sapi_module.name, "cli") == 0) {
+    static const char *bg_functions[] = {
+        "frankenphp_require_background_worker", "frankenphp_set_vars",
+        "frankenphp_get_vars", "frankenphp_get_worker_handle", NULL};
+    for (const char **f = bg_functions; *f != NULL; f++) {
+      zend_hash_str_del(CG(function_table), *f, strlen(*f));
+    }
+  }
+
   zend_function *func;
 
   // Override putenv

testdata/bg-worker-cli-hidden.php

@@ -0,0 +1,20 @@
+<?php
+
+// In CLI mode, background-worker functions are not exposed at all
+// (function_exists() returns false).
+
+$functions = [
+    'frankenphp_require_background_worker',
+    'frankenphp_set_vars',
+    'frankenphp_get_vars',
+    'frankenphp_get_worker_handle',
+];
+
+foreach ($functions as $fn) {
+    echo $fn . ':' . (function_exists($fn) ? 'exists' : 'hidden') . "\n";
+}
+
+// Other frankenphp functions should still exist
+echo 'frankenphp_log:' . (function_exists('frankenphp_log') ? 'exists' : 'hidden') . "\n";
+
+exit(0);