Add daemon proxy for php-fpm multi-process support

Stoolap uses exclusive file locking, so only one OS process can open a
database at a time. This adds a transparent daemon proxy that auto-forks
when loaded under php-fpm/CGI/Apache, allowing all worker processes to
share database access through shared memory IPC.

Architecture:
- Daemon auto-forks from php-fpm master on first load
- Per-connection 8MB shared memory (request + response buffers)
- Cache-line-split control block eliminates false sharing
- Spin-then-wait: fast spin phase catches sub-μs responses,
  futex (Linux) / __ulock (macOS) for blocking without CPU burn
- Elastic thread pool (8 initial, grows to 64) with 256KB stacks
- Per-PID socket paths for isolation between fpm instances
- Auto-lifecycle: daemon exits when php-fpm master dies

IPC overhead (bare-metal Linux x86_64):
- 0.2μs bare roundtrip (futex)
- 0.9μs SELECT by primary key through daemon
- Sub-2μs for prepared statement execute/query

Zero configuration required - works out of the box.
139 tests pass in both direct and daemon modes.

Author: semihalev

README.md

@@ -359,6 +359,41 @@ try {
 | `array` / `object` | `JSON` | Auto-encoded/decoded |
 | `DateTimeInterface` | `TIMESTAMP` | Converted to nanoseconds |
 
+## PHP-FPM / Web Server Support
+
+Stoolap uses exclusive file locking, so only one OS process can open a database at a time. The PHP extension solves this transparently for multi-process environments (php-fpm, Apache mod_php) with a built-in daemon proxy.
+
+### How It Works
+
+When loaded under php-fpm, CGI, or Apache, the extension automatically forks a background daemon process on first load. PHP workers communicate with the daemon via shared memory + futex/ulock for near-zero IPC overhead:
+
+- **Shared memory**: 8MB per connection, zero-copy request/response buffers
+- **futex (Linux) / __ulock (macOS)**: single-syscall wakeup, ~0.5μs bare roundtrip
+- **Spin-then-wait**: fast spin phase catches sub-microsecond responses, kernel wait for longer queries without CPU burn
+- **Auto-lifecycle**: daemon starts with php-fpm, exits when php-fpm stops
+- **Zero configuration**: works out of the box, no setup required
+
+### IPC Overhead
+
+| Operation | Direct (CLI) | Daemon (FPM) | Overhead |
+|---|---|---|---|
+| SELECT by PK | 0.5 μs | 1.0 μs | ~0.5 μs |
+| UPDATE by PK | 0.8 μs | 1.2 μs | ~0.5 μs |
+| Prepared execute | 0.6 μs | 1.1 μs | ~0.5 μs |
+| Prepared queryOne | 1.1 μs | 1.7 μs | ~0.6 μs |
+
+Analytical queries (GROUP BY, JOIN, window functions) are unaffected since they're dominated by engine time.
+
+### Environment Variables
+
+| Variable | Values | Description |
+|---|---|---|
+| `STOOLAP_DAEMON` | `1` / `on` | Force daemon mode (useful for testing) |
+| `STOOLAP_DAEMON` | `0` / `off` | Force direct mode (disable daemon) |
+| `STOOLAP_DAEMON_DEBUG` | `1` | Enable daemon stderr logging |
+
+When not set, daemon mode is auto-detected from the SAPI name (fpm, cgi, apache).
+
 ## Benchmark
 
 Run the included benchmark (Stoolap vs SQLite):

ext/config.m4

@@ -35,10 +35,8 @@ if test "$PHP_STOOLAP" != "no"; then
 
   PHP_ADD_LIBRARY_WITH_PATH(stoolap, $STOOLAP_LIB_DIR, STOOLAP_SHARED_LIBADD)
   PHP_SUBST(STOOLAP_SHARED_LIBADD)
+  STOOLAP_SHARED_LIBADD="$STOOLAP_SHARED_LIBADD -Wl,-rpath,$STOOLAP_LIB_DIR -lpthread"
 
-  dnl Add rpath so library is found at runtime
-  STOOLAP_SHARED_LIBADD="$STOOLAP_SHARED_LIBADD -Wl,-rpath,$STOOLAP_LIB_DIR"
-
-  PHP_NEW_EXTENSION(stoolap, stoolap.c, $ext_shared)
+  PHP_NEW_EXTENSION(stoolap, stoolap.c stoolap_daemon.c, $ext_shared)
   PHP_ADD_MAKEFILE_FRAGMENT
 fi

ext/php_stoolap.h

@@ -25,41 +25,6 @@ typedef struct StoolapValue {
     } v;
 } StoolapValue;
 
-/* Stoolap C API functions */
-extern const char *stoolap_version(void);
-
-extern int32_t stoolap_open(const char *dsn, StoolapDB **out_db);
-extern int32_t stoolap_open_in_memory(StoolapDB **out_db);
-extern int32_t stoolap_clone(const StoolapDB *db, StoolapDB **out_db);
-extern int32_t stoolap_close(StoolapDB *db);
-extern const char *stoolap_errmsg(const StoolapDB *db);
-
-extern int32_t stoolap_exec(StoolapDB *db, const char *sql, int64_t *rows_affected);
-extern int32_t stoolap_exec_params(StoolapDB *db, const char *sql, const StoolapValue *params, int32_t params_len, int64_t *rows_affected);
-extern int32_t stoolap_query(StoolapDB *db, const char *sql, StoolapRows **out_rows);
-extern int32_t stoolap_query_params(StoolapDB *db, const char *sql, const StoolapValue *params, int32_t params_len, StoolapRows **out_rows);
-
-extern int32_t stoolap_prepare(StoolapDB *db, const char *sql, StoolapStmt **out_stmt);
-extern int32_t stoolap_stmt_exec(StoolapStmt *stmt, const StoolapValue *params, int32_t params_len, int64_t *rows_affected);
-extern int32_t stoolap_stmt_query(StoolapStmt *stmt, const StoolapValue *params, int32_t params_len, StoolapRows **out_rows);
-extern void stoolap_stmt_finalize(StoolapStmt *stmt);
-extern const char *stoolap_stmt_errmsg(const StoolapStmt *stmt);
-
-extern int32_t stoolap_begin(StoolapDB *db, StoolapTx **out_tx);
-extern int32_t stoolap_begin_with_isolation(StoolapDB *db, int32_t isolation, StoolapTx **out_tx);
-extern int32_t stoolap_tx_exec(StoolapTx *tx, const char *sql, int64_t *rows_affected);
-extern int32_t stoolap_tx_exec_params(StoolapTx *tx, const char *sql, const StoolapValue *params, int32_t params_len, int64_t *rows_affected);
-extern int32_t stoolap_tx_query(StoolapTx *tx, const char *sql, StoolapRows **out_rows);
-extern int32_t stoolap_tx_query_params(StoolapTx *tx, const char *sql, const StoolapValue *params, int32_t params_len, StoolapRows **out_rows);
-extern int32_t stoolap_tx_stmt_exec(StoolapTx *tx, const StoolapStmt *stmt, const StoolapValue *params, int32_t params_len, int64_t *rows_affected);
-extern int32_t stoolap_tx_stmt_query(StoolapTx *tx, const StoolapStmt *stmt, const StoolapValue *params, int32_t params_len, StoolapRows **out_rows);
-extern int32_t stoolap_tx_commit(StoolapTx *tx);
-extern int32_t stoolap_tx_rollback(StoolapTx *tx);
-extern const char *stoolap_tx_errmsg(const StoolapTx *tx);
-
-extern int32_t stoolap_rows_fetch_all(StoolapRows *rows, uint8_t **out_buf, int64_t *out_len);
-extern void stoolap_rows_close(StoolapRows *rows);
-extern const char *stoolap_rows_errmsg(const StoolapRows *rows);
-extern void stoolap_buffer_free(uint8_t *buf, int64_t len);
+/* Stoolap FFI — see stoolap_daemon.h for full declarations */
 
 #endif