feat: expose thread API for Go-based PHP extensions

Add APIs that enable Go-based PHP extensions to execute on existing
FrankenPHP threads and access per-request state:

- Thread(index) — retrieves a PHP thread by its index, returning its
  *http.Request which carries the request context
- PHPThread.Pin() — pins a Go object to prevent GC collection
- PHPThread.IsRequestDone() — checks if the request has been closed
- frankenphp_thread_index() — C function returning the current thread
  index so C extension methods can call back into Go

This makes it possible to build PHP extensions where PHP calls into C,
C resolves the current thread index, and Go handles the logic with
full access to the request context.

Author: johanjanssens

frankenphp.c

@@ -1204,6 +1204,10 @@ static int frankenphp_request_startup() {
   return FAILURE;
 }
 
+uintptr_t frankenphp_thread_index(void) {
+  return thread_index;
+}
+
 int frankenphp_execute_script(char *file_name) {
   if (frankenphp_request_startup() == FAILURE) {
 

frankenphp.go

@@ -128,6 +128,38 @@ type PHPConfig struct {
 	ZendMaxExecutionTimers bool
 }
 
+// PHPThread exposes a PHP thread's request context.
+type PHPThread struct {
+	Request *http.Request
+	thread  *phpThread
+}
+
+// IsRequestDone determines whether the request associated with the PHPThread has been closed.
+func (p *PHPThread) IsRequestDone() bool {
+	return p.thread.frankenPHPContext().isDone
+}
+
+// Pin pins a Go object, preventing it from being moved or freed by the garbage
+// collector until the Pinner.Unpin method has been called.
+func (p *PHPThread) Pin(pointer any) {
+	p.thread.Pin(pointer)
+}
+
+// Thread retrieves a PHP thread by its index.
+// Returns nil and false if the system is not running or no thread exists at the given index.
+func Thread(index int) (*PHPThread, bool) {
+	if !isRunning {
+		return nil, false
+	}
+
+	thread := phpThreads[index]
+	if thread != nil {
+		return &PHPThread{thread.frankenPHPContext().request, thread}, true
+	}
+
+	return nil, false
+}
+
 // Version returns infos about the PHP version.
 func Version() PHPVersion {
 	cVersion := C.frankenphp_get_version()

frankenphp.h

@@ -168,6 +168,8 @@ frankenphp_config frankenphp_get_config();
 int frankenphp_new_main_thread(int num_threads);
 bool frankenphp_new_php_thread(uintptr_t thread_index);
 
+uintptr_t frankenphp_thread_index(void);
+
 bool frankenphp_shutdown_dummy_request(void);
 int frankenphp_execute_script(char *file_name);
 void frankenphp_update_local_thread_context(bool is_worker);