feat(build): add static library build system and SAPI integration

- Create CMakeLists.txt for building phpx as a static library with core, std,
  and typephp components
- Add object libraries for mpdecimal and wren-gc third-party dependencies
- Configure proper include directories and compile definitions for PHPX build
- Integrate typephp_sapi.cc into test suite for CLI argument preparation
- Refactor opcode table lifecycle management with separate startup/shutdown
  phases for process and request levels
- Implement runtime hook chaining for compatibility with Zend extensions like
  OPcache
- Add embedded file existence and path kind checking utilities
- Create CLI argument preparation functions that prepend project entry file
  while preserving PHP CLI options
- Add comprehensive tests for SAPI argument handling scenarios

Author: matyhtf

CMakeLists.txt

@@ -494,6 +494,7 @@ if(BUILD_TESTS)
             list(FILTER TEST_FILES EXCLUDE REGEX "/python_bridge\\.cpp$")
         endif()
         add_executable(phpx-tests ${TEST_FILES})
+        target_sources(phpx-tests PRIVATE src/misc/typephp_sapi.cc)
         target_include_directories(phpx-tests PRIVATE tests/include)
 
         if(IS_WINDOWS)

include/typephp_opcode_table.h

@@ -24,13 +24,21 @@ extern "C" {
 const typephp_opcode_entry *typephp_project_opcode_table(size_t *count);
 const typephp_embedded_file_entry *typephp_project_embedded_file_table(size_t *count);
 const char *typephp_project_php_version(void);
+const char *typephp_project_entry_file(void);
 
 #ifdef _WIN32
 /* Return the bytes of the archive linked as a Windows PE resource. */
 const uint8_t *typephp_embedded_archive_data(void);
 #endif
 
 void typephp_opcode_table_install(void);
+void typephp_opcode_table_startup(void);
+void typephp_opcode_table_request_startup(void);
+void typephp_opcode_table_request_shutdown(void);
+void typephp_opcode_table_shutdown(void);
+int typephp_embedded_file_exists(const char *path);
+/* 0: missing, 1: file, 2: directory. */
+int typephp_embedded_path_kind(const char *path);
 void typephp_opcode_table_require(const char *path);
 void typephp_opcode_table_uninstall(void);
 

include/typephp_sapi.h

@@ -0,0 +1,20 @@
+#ifndef TYPEPHP_SAPI_H
+#define TYPEPHP_SAPI_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * Prepare the argv consumed by PHP CLI. The options pointer is PHP CLI's own
+ * opt_struct table, kept opaque here so this ABI does not expose PHP internals.
+ * allocated_argv is non-null only when an application entry was inserted.
+ */
+int typephp_cli_prepare_arguments(int *argc, char ***argv, const void *options, char ***allocated_argv);
+void typephp_cli_release_arguments(char **allocated_argv);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif

sapi-static/CMakeLists.txt

@@ -0,0 +1,62 @@
+cmake_minimum_required(VERSION 3.20)
+project(phpx_sapi_static LANGUAGES C CXX)
+
+set(PHPX_ROOT "" CACHE PATH "PHPX source directory")
+set(PHPX_PHP_PREFIX "" CACHE PATH "Private PHP installation prefix")
+if(NOT EXISTS "${PHPX_ROOT}/include/phpx.h")
+    message(FATAL_ERROR "Invalid PHPX source directory: ${PHPX_ROOT}")
+endif()
+if(NOT EXISTS "${PHPX_PHP_PREFIX}/include/php/main/php.h")
+    message(FATAL_ERROR "Invalid private PHP prefix: ${PHPX_PHP_PREFIX}")
+endif()
+
+file(GLOB PHPX_CORE_SOURCES "${PHPX_ROOT}/src/core/*.cc")
+file(GLOB PHPX_STD_SOURCES "${PHPX_ROOT}/src/std/*.cc")
+file(GLOB PHPX_TYPEPHP_SOURCES "${PHPX_ROOT}/src/typephp/*.cc")
+list(FILTER PHPX_CORE_SOURCES EXCLUDE REGEX "/[^/]+_nano\\.cc$")
+list(FILTER PHPX_TYPEPHP_SOURCES EXCLUDE REGEX "/[^/]+_nano\\.cc$")
+
+file(GLOB MPDEC_C_SOURCES "${PHPX_ROOT}/thirdparty/mpdecimal/libmpdec/*.c")
+list(FILTER MPDEC_C_SOURCES EXCLUDE REGEX "bench")
+add_library(mpdecimal_obj OBJECT
+    ${MPDEC_C_SOURCES}
+    "${PHPX_ROOT}/thirdparty/mpdecimal/libmpdec++/decimal.cc"
+)
+target_include_directories(mpdecimal_obj PUBLIC
+    "${PHPX_ROOT}/thirdparty/mpdecimal/libmpdec"
+    "${PHPX_ROOT}/thirdparty/mpdecimal/libmpdec++"
+)
+target_compile_definitions(mpdecimal_obj PRIVATE CONFIG_64 ANSI HAVE_UINT128_T)
+set_target_properties(mpdecimal_obj PROPERTIES C_STANDARD 99 POSITION_INDEPENDENT_CODE ON)
+
+add_library(wren_gc_obj OBJECT "${PHPX_ROOT}/thirdparty/wren-gc/src/wren_gc.c")
+target_include_directories(wren_gc_obj PUBLIC "${PHPX_ROOT}/thirdparty/wren-gc/include")
+set_target_properties(wren_gc_obj PROPERTIES C_STANDARD 11 POSITION_INDEPENDENT_CODE ON)
+
+add_library(phpx STATIC
+    ${PHPX_CORE_SOURCES}
+    ${PHPX_STD_SOURCES}
+    ${PHPX_TYPEPHP_SOURCES}
+    $<TARGET_OBJECTS:mpdecimal_obj>
+    $<TARGET_OBJECTS:wren_gc_obj>
+)
+set_target_properties(phpx PROPERTIES
+    OUTPUT_NAME phpx
+    ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib"
+    CXX_STANDARD 17
+    CXX_STANDARD_REQUIRED ON
+    POSITION_INDEPENDENT_CODE ON
+)
+target_include_directories(phpx PRIVATE
+    "${PHPX_ROOT}/include"
+    "${PHPX_ROOT}/src/misc"
+    "${PHPX_PHP_PREFIX}/include/php"
+    "${PHPX_PHP_PREFIX}/include/php/main"
+    "${PHPX_PHP_PREFIX}/include/php/Zend"
+    "${PHPX_PHP_PREFIX}/include/php/TSRM"
+    "${PHPX_PHP_PREFIX}/include/php/ext"
+    "${PHPX_PHP_PREFIX}/include/php/ext/date/lib"
+    "${PHPX_ROOT}/thirdparty/mpdecimal/libmpdec"
+    "${PHPX_ROOT}/thirdparty/mpdecimal/libmpdec++"
+    "${PHPX_ROOT}/thirdparty/wren-gc/include"
+)

src/misc/typephp_opcode_table.cc

@@ -46,6 +46,8 @@ zend_result (*old_stream_open)(zend_file_handle *) = nullptr;
 php_stream_wrapper_ops wrapped_file_ops;
 php_stream_wrapper wrapped_file_wrapper;
 bool file_wrapper_installed = false;
+bool runtime_hooks_installed = false;
+bool opcode_table_started = false;
 
 std::string lexical_path(const std::string &path) {
     return std::filesystem::path(path).lexically_normal().string();
@@ -184,7 +186,8 @@ int stat_embedded_file(php_stream_wrapper *, const char *filename, int flags,
 
 }
 
-extern "C" void typephp_opcode_table_install(void) {
+extern "C" void typephp_opcode_table_startup(void) {
+    if (opcode_table_started) return;
     size_t count = 0;
     const typephp_opcode_entry *table = typephp_project_opcode_table(&count);
     size_t raw_count = 0;
@@ -200,12 +203,27 @@ extern "C" void typephp_opcode_table_install(void) {
     for (size_t i = 0; i < raw_count; ++i) {
         raw_entries.emplace(raw_table[i].path, &raw_table[i]);
     }
-    old_compile_file = zend_compile_file;
-    old_resolve_path = zend_resolve_path;
-    old_stream_open = zend_stream_open_function;
-    zend_compile_file = embedded_compile_file;
-    zend_resolve_path = resolve_path;
-    zend_stream_open_function = stream_open;
+    opcode_table_started = true;
+}
+
+extern "C" void typephp_opcode_table_request_startup(void) {
+    if (!opcode_table_started) return;
+
+    // Zend extensions such as OPcache install their compiler hooks after
+    // module MINIT. Chain TypePHP outside those hooks at the first request so
+    // embedded opcodes are resolved before OPcache tries to stat the synthetic
+    // zend_file_handle. Keep the process-wide chain for subsequent requests.
+    if (!runtime_hooks_installed) {
+        old_compile_file = zend_compile_file;
+        old_resolve_path = zend_resolve_path;
+        old_stream_open = zend_stream_open_function;
+        zend_compile_file = embedded_compile_file;
+        zend_resolve_path = resolve_path;
+        zend_stream_open_function = stream_open;
+        runtime_hooks_installed = true;
+    }
+
+    if (file_wrapper_installed) return;
 
     wrapped_file_ops = *php_plain_files_wrapper.wops;
     wrapped_file_ops.stream_opener = open_embedded_file;
@@ -222,6 +240,35 @@ extern "C" void typephp_opcode_table_install(void) {
     zend_string_release(protocol);
 }
 
+extern "C" void typephp_opcode_table_install(void) {
+    typephp_opcode_table_startup();
+    typephp_opcode_table_request_startup();
+}
+
+extern "C" int typephp_embedded_file_exists(const char *path) {
+    if (!path) return 0;
+    const std::string name(path);
+    return lookup(entries, name) != nullptr || lookup(raw_entries, name) != nullptr;
+}
+
+extern "C" int typephp_embedded_path_kind(const char *path) {
+    if (!path) return 0;
+    std::string name(path);
+    if (lookup(entries, name) || lookup(raw_entries, name)) return 1;
+    if (name.rfind("file://", 0) == 0) name.erase(0, 7);
+    name = lexical_path(name);
+    if (!name.empty() && name.back() != std::filesystem::path::preferred_separator) {
+        name.push_back(std::filesystem::path::preferred_separator);
+    }
+    const auto contains_child = [&name](const auto &table) {
+        for (const auto &item : table) {
+            if (item.first.rfind(name, 0) == 0) return true;
+        }
+        return false;
+    };
+    return contains_child(entries) || contains_child(raw_entries) ? 2 : 0;
+}
+
 extern "C" void typephp_opcode_table_require(const char *path) {
     const typephp_opcode_entry *entry = lookup(entries, std::string(path));
     if (!entry) {
@@ -236,17 +283,7 @@ extern "C" void typephp_opcode_table_require(const char *path) {
     zend_destroy_file_handle(&handle);
 }
 
-extern "C" void typephp_opcode_table_uninstall(void) {
-    if (old_compile_file) {
-        zend_compile_file = old_compile_file;
-        zend_resolve_path = old_resolve_path;
-        zend_stream_open_function = old_stream_open;
-        old_compile_file = nullptr;
-        old_resolve_path = nullptr;
-        old_stream_open = nullptr;
-    }
-    entries.clear();
-    raw_entries.clear();
+extern "C" void typephp_opcode_table_request_shutdown(void) {
     if (file_wrapper_installed) {
         zend_string *protocol = zend_string_init("file", sizeof("file") - 1, 0);
         php_unregister_url_stream_wrapper_volatile(protocol);
@@ -255,3 +292,24 @@ extern "C" void typephp_opcode_table_uninstall(void) {
         file_wrapper_installed = false;
     }
 }
+
+extern "C" void typephp_opcode_table_shutdown(void) {
+    if (!opcode_table_started) return;
+    typephp_opcode_table_request_shutdown();
+    if (runtime_hooks_installed) {
+        if (zend_compile_file == embedded_compile_file) zend_compile_file = old_compile_file;
+        if (zend_resolve_path == resolve_path) zend_resolve_path = old_resolve_path;
+        if (zend_stream_open_function == stream_open) zend_stream_open_function = old_stream_open;
+        runtime_hooks_installed = false;
+    }
+    old_compile_file = nullptr;
+    old_resolve_path = nullptr;
+    old_stream_open = nullptr;
+    entries.clear();
+    raw_entries.clear();
+    opcode_table_started = false;
+}
+
+extern "C" void typephp_opcode_table_uninstall(void) {
+    typephp_opcode_table_shutdown();
+}

src/misc/typephp_runtime.cc

@@ -11,7 +11,12 @@ BEGIN_EXTERN_C()
 END_EXTERN_C()
 
 static void module_init(zend_module_entry *module) {
-    if (zend_register_module_ex(module, MODULE_PERSISTENT) == nullptr) {
+    // php_embed_init() has already started the request. Registering another
+    // persistent module at this point appends persistent function/class keys
+    // after Zend's request cleanup boundary. A temporary module is the Zend
+    // supported form for a module loaded during a request, and its destructor
+    // removes those symbols before shutdown_executor() walks the tables.
+    if (zend_register_module_ex(module, MODULE_TEMPORARY) == nullptr) {
         zend_error(E_ERROR, "Failed to register module [%s]", module->name);
         exit(255);
     }
@@ -61,15 +66,14 @@ static void cli_register_file_handles() {
 }
 
 static void module_shutdown(zend_module_entry *module) {
-    /**
-     * There is a bug in PHP's handling of internal strings. All interned strings are released in the request shutdown
-     * function, but then released again in the php_embed_shutdown function, resulting in a use-after-free issue. These
-     * must be manually removed from the module table to prevent double release.
-     */
+    // Removing a temporary module runs its MSHUTDOWN handler and unregisters
+    // its functions, classes, constants and INI entries before Embed shuts the
+    // request down.
     auto name_len = strlen(module->name);
     auto lcname = zend_string_alloc(name_len, module->type == MODULE_PERSISTENT);
     zend_str_tolower_copy(ZSTR_VAL(lcname), module->name, name_len);
     zend_hash_del(&module_registry, lcname);
+    zend_string_release(lcname);
 }
 
 static zend_module_entry *typephp_runtime_module = nullptr;
@@ -142,10 +146,8 @@ extern "C" void typephp_runtime_stop(void) {
     }
     zend_end_try();
 
-    // Keep this manual cleanup and registry removal. Registering an internal
-    // module after request startup exposes a PHP Embed double-release bug for
-    // its persistent strings if the module remains registered through
-    // php_module_shutdown().
+    // The TypePHP module was registered after request startup and therefore is
+    // absent from PHP's precomputed shutdown lists. Run and unload it manually.
     typephp_runtime_module->request_shutdown_func(typephp_runtime_module->type, typephp_runtime_module->module_number);
     module_shutdown(typephp_runtime_module);
     typephp_opcode_table_uninstall();

src/misc/typephp_sapi.cc

@@ -0,0 +1,53 @@
+#include <typephp_opcode_table.h>
+#include <typephp_sapi.h>
+
+extern "C" {
+#include "php.h"
+#include "php_getopt.h"
+}
+
+#include <cstdio>
+#include <cstdlib>
+#include <cstring>
+
+extern "C" int typephp_cli_prepare_arguments(int *argc, char ***argv, const void *options, char ***allocated_argv) {
+    *allocated_argv = nullptr;
+
+    bool php_cli_mode = false;
+    if (*argc > 1) {
+        php_cli_mode = strcmp((*argv)[1], "-") == 0 || strcmp((*argv)[1], "--") == 0;
+        if (!php_cli_mode) {
+            char *option_argument = nullptr;
+            int option_index = 1;
+            int option = php_getopt(
+                *argc, *argv, static_cast<const opt_struct *>(options), &option_argument, &option_index, 0, 2);
+            php_cli_mode = option != EOF;
+        }
+    }
+    if (php_cli_mode) {
+        return SUCCESS;
+    }
+
+    const char *entry = typephp_project_entry_file();
+    if (entry == nullptr || *entry == '\0') {
+        return FAILURE;
+    }
+
+    char **application_argv = static_cast<char **>(calloc(static_cast<size_t>(*argc) + 2, sizeof(char *)));
+    if (application_argv == nullptr) {
+        return FAILURE;
+    }
+    application_argv[0] = (*argv)[0];
+    application_argv[1] = const_cast<char *>(entry);
+    for (int i = 1; i < *argc; ++i) {
+        application_argv[i + 1] = (*argv)[i];
+    }
+    *argv = application_argv;
+    *allocated_argv = application_argv;
+    ++*argc;
+    return SUCCESS;
+}
+
+extern "C" void typephp_cli_release_arguments(char **allocated_argv) {
+    free(allocated_argv);
+}