Add ModuleScope for per-thread php_module_startup in ZTS mode

In PHP's ZTS (Thread Safe) mode, php_module_startup must be called
per-thread after ts_resource(0) has initialized the thread's local
storage. This commit adds:

1. ModuleScope type that calls php_module_startup per-thread
2. Sapi::module_scope() method to create ModuleScope with proper pointers
3. Per-thread module initialization in spawn_blocking tasks

Key insight: php_module_startup is called once in Sapi::new() for the
main thread, and then again per worker thread via module_scope().
php_module_shutdown should only be called once during SAPI shutdown,
NOT per-thread (per-thread cleanup is handled by ts_free_thread).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: Qard

src/embed.rs

@@ -349,12 +349,13 @@ impl Handler for Embed {
       let _thread_scope = ThreadScope::new();
       eprintln!("DEBUG [spawn_blocking] Step 2: ThreadScope created");
 
-      // Verify SAPI is accessible (no longer calls php_module_startup per-thread).
-      // php_module_startup is only called once in Sapi::new(), not per-thread.
-      sapi
-        .startup()
+      // Initialize PHP module for this thread.
+      // In ZTS mode, php_module_startup must be called per-thread after the thread's
+      // local storage has been initialized. ModuleScope ensures matching shutdown.
+      let _module_scope = sapi
+        .module_scope()
         .map_err(|_| EmbedRequestError::SapiNotStarted)?;
-      eprintln!("DEBUG [spawn_blocking] Step 3: SAPI startup verified");
+      eprintln!("DEBUG [spawn_blocking] Step 3: ModuleScope created (php_module_startup called)");
 
       // Setup RequestContext (always streaming from SAPI perspective)
       // RequestContext::new() will extract the request body's read stream and add it as RequestStream extension

src/sapi.rs

@@ -86,6 +86,8 @@ impl Sapi {
       ext_php_rs_sapi_startup();
       sapi_startup(boxed.as_mut());
 
+      // Call module startup for the main thread that's constructing this Sapi.
+      // Each worker thread also needs its own module startup via module_scope().
       if let Some(startup) = boxed.startup {
         startup(boxed.as_mut());
       }
@@ -114,24 +116,22 @@ impl Sapi {
     })
   }
 
-  /// Verify that the SAPI module has been initialized.
+  /// Creates a new ModuleScope for per-thread module startup.
   ///
-  /// In ZTS mode, thread-local storage is initialized by ThreadScope::new() which
-  /// calls ext_php_rs_sapi_per_thread_init() -> ts_resource(0). The module startup
-  /// (php_module_startup) is only called once in Sapi::new(), not per-thread.
+  /// In ZTS mode, php_module_startup must be called per-thread after the thread's
+  /// local storage has been initialized via ts_resource(0) in ThreadScope::new().
   ///
-  /// This method verifies the SAPI is accessible, but no longer calls php_module_startup
-  /// per-thread as that causes heap corruption when called multiple times.
-  pub fn startup(&self) -> Result<(), EmbedRequestError> {
-    // Just verify we can acquire a read lock - the actual module startup
-    // already happened in Sapi::new(). ThreadScope::new() handles per-thread
-    // TLS initialization via ts_resource(0).
-    let _sapi = self
+  /// This method provides access to the SAPI module and module entry pointers
+  /// needed by ModuleScope::new().
+  pub fn module_scope(&self) -> Result<crate::scopes::ModuleScope, EmbedRequestError> {
+    let mut sapi = self
       .module
-      .read()
+      .write()
       .map_err(|_| EmbedRequestError::SapiNotStarted)?;
 
-    Ok(())
+    unsafe {
+      crate::scopes::ModuleScope::new(sapi.as_mut() as *mut _, get_module())
+    }
   }
 
   pub fn shutdown(&self) -> Result<(), EmbedRequestError> {

src/scopes.rs

@@ -6,10 +6,11 @@ use std::{
 
 use ext_php_rs::{
   alloc::{efree, estrdup},
-  embed::{ext_php_rs_sapi_per_thread_init, ext_php_rs_sapi_per_thread_shutdown},
+  embed::{ext_php_rs_sapi_per_thread_init, ext_php_rs_sapi_per_thread_shutdown, SapiModule},
   ffi::{
-    _zend_file_handle__bindgen_ty_1, php_module_shutdown, php_request_shutdown, php_request_startup,
-    zend_destroy_file_handle, zend_file_handle, zend_stream_init_filename, ZEND_RESULT_CODE_SUCCESS,
+    _zend_file_handle__bindgen_ty_1, php_module_startup, php_request_shutdown, php_request_startup,
+    zend_destroy_file_handle, zend_file_handle, zend_module_entry, zend_stream_init_filename,
+    ZEND_RESULT_CODE_SUCCESS,
   },
 };
 
@@ -38,21 +39,45 @@ impl Drop for ThreadScope {
   }
 }
 
-/// A scope for PHP module shutdown (module startup is called once in Sapi::new()).
-/// This is used to ensure php_module_shutdown is called on drop.
+/// A scope for PHP module startup per-thread.
+/// This ensures that php_module_startup is called on scope creation.
 ///
-/// NOTE: php_module_startup is only called once in Sapi::new() via the startup callback.
-/// Per-thread TLS initialization is handled by ThreadScope via ts_resource(0).
-#[allow(dead_code)]
+/// In ZTS mode, php_module_startup must be called per-thread after the thread's
+/// local storage has been initialized via ts_resource(0).
+///
+/// NOTE: php_module_shutdown should only be called once when the SAPI shuts down,
+/// NOT per-thread. Per-thread cleanup is handled by ThreadScope (ts_free_thread).
 pub(crate) struct ModuleScope;
 
+impl ModuleScope {
+  /// Creates a new ModuleScope, calling php_module_startup.
+  ///
+  /// # Safety
+  /// The sapi_module and module_entry pointers must be valid.
+  pub unsafe fn new(
+    sapi_module: *mut SapiModule,
+    module_entry: *mut zend_module_entry,
+  ) -> Result<Self, EmbedRequestError> {
+    eprintln!("DEBUG [ModuleScope::new] Calling php_module_startup()");
+
+    let result = php_module_startup(sapi_module, module_entry);
+    if result != ZEND_RESULT_CODE_SUCCESS {
+      eprintln!("DEBUG [ModuleScope::new] php_module_startup() FAILED");
+      return Err(EmbedRequestError::SapiNotStarted);
+    }
+
+    eprintln!("DEBUG [ModuleScope::new] php_module_startup() succeeded");
+    Ok(Self)
+  }
+}
+
 impl Drop for ModuleScope {
   fn drop(&mut self) {
-    eprintln!("DEBUG [ModuleScope::drop] Calling php_module_shutdown()");
-    unsafe {
-      php_module_shutdown();
-    }
-    eprintln!("DEBUG [ModuleScope::drop] php_module_shutdown() completed");
+    // NOTE: We intentionally do NOT call php_module_shutdown() here.
+    // php_module_shutdown should only be called once when the entire SAPI shuts down,
+    // not per-thread. Per-thread cleanup is handled by ThreadScope::drop which calls
+    // ext_php_rs_sapi_per_thread_shutdown() -> ts_free_thread().
+    eprintln!("DEBUG [ModuleScope::drop] ModuleScope dropped (no php_module_shutdown called)");
   }
 }