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

@@ -1278,6 +1278,10 @@ bool frankenphp_new_php_thread(uintptr_t thread_index) {
   return true;
 }
 
+uintptr_t frankenphp_thread_index(void) {
+  return thread_index;
+}
+
 /* Use global variables to store CLI arguments to prevent useless allocations */
 static char *cli_script;
 static int cli_argc;

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);
 void frankenphp_update_local_thread_context(bool is_worker);