docs: improve worker docs, and add internals docs (#2334)

Author: dunglas

CONTRIBUTING.md

@@ -1,5 +1,7 @@
 # Contributing
 
+For an overview of FrankenPHP's architecture (thread types, state machine, CGO boundary, request flow), see the [Internals documentation](docs/internals.md).
+
 ## Compiling PHP
 
 ### With Docker (Linux)
@@ -299,7 +301,7 @@ The steps assume the following environment:
 
 4. Debug Go files from CLion
 
-   - Right click on a *.go file in the Project view on the left
+   - Right click on a \*.go file in the Project view on the left
    - Override file type → C/C++
 
    Now you can place breakpoints in C, C++ and Go files.
@@ -348,7 +350,7 @@ Use GoLand for primary Go development, but the debugger cannot debug C code.
 
 To debug C files from GoLand
 
-- Right click on a *.c file in the Project view on the left
+- Right click on a \*.c file in the Project view on the left
 - Override file type → Go
 
 Now you can place breakpoints in C, C++ and Go files.

README.md

@@ -177,6 +177,7 @@ Go to `https://localhost`, and enjoy!
 - [Demo app (Symfony) and benchmarks](https://github.com/dunglas/frankenphp-demo)
 - [Go library documentation](https://pkg.go.dev/github.com/dunglas/frankenphp)
 - [Contributing and debugging](https://frankenphp.dev/docs/contributing/)
+- [Internals (architecture overview)](docs/internals.md)
 
 ## Examples and Skeletons
 

docs/cn/extension-workers.md

@@ -135,12 +135,12 @@ while (frankenphp_handle_request($handler)) {
 
 FrankenPHP 提供了钩子，用于在生命周期的特定点执行 Go 代码。
 
-| 钩子类型 | 选项名称                     | 签名                     | 上下文与用例                                         |
-| :------- | :--------------------------- | :----------------------- | :--------------------------------------------------- |
-| **服务器** | `WithWorkerOnServerStartup`  | `func()`                 | 全局设置。**只运行一次**。示例：连接到 NATS/Redis。  |
-| **服务器** | `WithWorkerOnServerShutdown` | `func()`                 | 全局清理。**只运行一次**。示例：关闭共享连接。       |
-| **线程** | `WithWorkerOnReady`          | `func(threadID int)`     | 每线程设置。在线程启动时调用。接收线程 ID。          |
-| **线程** | `WithWorkerOnShutdown`       | `func(threadID int)`     | 每线程清理。接收线程 ID。                            |
+| 钩子类型   | 选项名称                     | 签名                 | 上下文与用例                                        |
+| :--------- | :--------------------------- | :------------------- | :-------------------------------------------------- |
+| **服务器** | `WithWorkerOnServerStartup`  | `func()`             | 全局设置。**只运行一次**。示例：连接到 NATS/Redis。 |
+| **服务器** | `WithWorkerOnServerShutdown` | `func()`             | 全局清理。**只运行一次**。示例：关闭共享连接。      |
+| **线程**   | `WithWorkerOnReady`          | `func(threadID int)` | 每线程设置。在线程启动时调用。接收线程 ID。         |
+| **线程**   | `WithWorkerOnShutdown`       | `func(threadID int)` | 每线程清理。接收线程 ID。                           |
 
 ### 示例
 

docs/cn/hot-reload.md

@@ -25,7 +25,7 @@ FrankenPHP 包含一个内置的**热重载**功能，旨在极大改善开发
 >
 > 此功能仅适用于**开发环境**。
 > 请勿在生产环境中启用 `hot_reload`，因为此功能不安全（会暴露敏感的内部细节）并且会降低应用程序的速度。
->
+
 ```caddyfile
 localhost
 
@@ -145,5 +145,5 @@ php_server {
 4. **接收**：浏览器通过 JavaScript 库监听，接收 Mercure 事件。
 5. **更新**：
 
-    - 如果检测到 **Idiomorph**，它会获取更新的内容并修改当前的 HTML 以匹配新状态，即时应用更改而不会丢失状态。
-    - 否则，将调用 `window.location.reload()` 来刷新页面。
+   - 如果检测到 **Idiomorph**，它会获取更新的内容并修改当前的 HTML 以匹配新状态，即时应用更改而不会丢失状态。
+   - 否则，将调用 `window.location.reload()` 来刷新页面。

docs/cn/worker.md

@@ -184,3 +184,4 @@ $handler = static function () use ($workerServer) {
 };
 
 // ...
+```

docs/es/classic.md

@@ -3,9 +3,9 @@
 Sin ninguna configuración adicional, FrankenPHP opera en modo clásico. En este modo, FrankenPHP funciona como un servidor PHP tradicional, sirviendo directamente archivos PHP. Esto lo convierte en un reemplazo directo para PHP-FPM o Apache con mod_php.
 
 Al igual que Caddy, FrankenPHP acepta un número ilimitado de conexiones y utiliza un [número fijo de hilos](config.md#caddyfile-config) para atenderlas. La cantidad de conexiones aceptadas y en cola está limitada únicamente por los recursos disponibles del sistema.
-El *pool* de hilos de PHP opera con un número fijo de hilos inicializados al inicio, comparable al modo estático de PHP-FPM. También es posible permitir que los hilos [escale automáticamente en tiempo de ejecución](performance.md#max_threads), similar al modo dinámico de PHP-FPM.
+El _pool_ de hilos de PHP opera con un número fijo de hilos inicializados al inicio, comparable al modo estático de PHP-FPM. También es posible permitir que los hilos [escalen automáticamente en tiempo de ejecución](performance.md#max_threads), similar al modo dinámico de PHP-FPM.
 
 Las conexiones en cola esperarán indefinidamente hasta que un hilo de PHP esté disponible para atenderlas. Para evitar esto, puedes usar la configuración `max_wait_time` en la [configuración global de FrankenPHP](config.md#caddyfile-config) para limitar la duración que una petición puede esperar por un hilo de PHP libre antes de ser rechazada.
 Adicionalmente, puedes establecer un [tiempo límite de escritura razonable en Caddy](https://caddyserver.com/docs/caddyfile/options#timeouts).
 
-Cada instancia de Caddy iniciará solo un *pool* de hilos de FrankenPHP, el cual será compartido entre todos los bloques `php_server`.
+Cada instancia de Caddy iniciará solo un _pool_ de hilos de FrankenPHP, el cual será compartido entre todos los bloques `php_server`.

docs/es/compile.md

@@ -79,11 +79,11 @@ sudo make install
 Algunas características de FrankenPHP dependen de dependencias opcionales del sistema que deben instalarse.
 Alternativamente, estas características pueden deshabilitarse pasando etiquetas de compilación al compilador Go.
 
-| Característica                     | Dependencia                                                                                                   | Etiqueta de compilación para deshabilitarla |
-| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| Compresión Brotli                  | [Brotli](https://github.com/google/brotli)                                                                   | nobrotli                                    |
-| Reiniciar workers al cambiar archivos | [Watcher C](https://github.com/e-dant/watcher/tree/release/watcher-c)                                        | nowatcher                                   |
-| [Mercure](mercure.md)              | [Biblioteca Mercure Go](https://pkg.go.dev/github.com/dunglas/mercure) (instalada automáticamente, licencia AGPL) | nomercure                                   |
+| Característica                        | Dependencia                                                                                                       | Etiqueta de compilación para deshabilitarla |
+| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| Compresión Brotli                     | [Brotli](https://github.com/google/brotli)                                                                        | nobrotli                                    |
+| Reiniciar workers al cambiar archivos | [Watcher C](https://github.com/e-dant/watcher/tree/release/watcher-c)                                             | nowatcher                                   |
+| [Mercure](mercure.md)                 | [Biblioteca Mercure Go](https://pkg.go.dev/github.com/dunglas/mercure) (instalada automáticamente, licencia AGPL) | nomercure                                   |
 
 ## Compilar la aplicación Go
 

docs/es/embed.md

@@ -66,7 +66,7 @@ La forma más fácil de crear un binario para Linux es usar el constructor basad
    RUN EMBED=dist/app/ ./build-static.sh
    ```
 
-    > [!CAUTION]
+   > [!CAUTION]
    >
    > Algunos archivos `.dockerignore` (por ejemplo, el [`.dockerignore` predeterminado de Symfony Docker](https://github.com/dunglas/symfony-docker/blob/main/.dockerignore))
    > ignorarán el directorio `vendor/` y los archivos `.env`. Asegúrese de ajustar o eliminar el archivo `.dockerignore` antes de la construcción.

docs/es/extension-workers.md

@@ -135,12 +135,12 @@ while (frankenphp_handle_request($handler)) {
 
 FrankenPHP proporciona hooks para ejecutar código Go en puntos específicos del ciclo de vida.
 
-| Tipo de Hook | Nombre de Opción             | Firma                | Contexto y Caso de Uso                                                      |
-| :----------- | :--------------------------- | :------------------- | :-------------------------------------------------------------------------- |
-| **Server**   | `WithWorkerOnServerStartup`  | `func()`             | Configuración global. Se ejecuta **Una vez**. Ejemplo: Conectar a NATS/Redis. |
-| **Server**   | `WithWorkerOnServerShutdown` | `func()`             | Limpieza global. Se ejecuta **Una vez**. Ejemplo: Cerrar conexiones compartidas. |
-| **Thread**   | `WithWorkerOnReady`          | `func(threadID int)` | Configuración por hilo. Llamado cuando un hilo inicia. Recibe el ID del hilo. |
-| **Thread**   | `WithWorkerOnShutdown`       | `func(threadID int)` | Limpieza por hilo. Recibe el ID del hilo.                                   |
+| Tipo de Hook | Nombre de Opción             | Firma                | Contexto y Caso de Uso                                                           |
+| :----------- | :--------------------------- | :------------------- | :------------------------------------------------------------------------------- |
+| **Servidor** | `WithWorkerOnServerStartup`  | `func()`             | Configuración global. Se ejecuta **Una vez**. Ejemplo: Conectar a NATS/Redis.    |
+| **Servidor** | `WithWorkerOnServerShutdown` | `func()`             | Limpieza global. Se ejecuta **Una vez**. Ejemplo: Cerrar conexiones compartidas. |
+| **Hilo**     | `WithWorkerOnReady`          | `func(threadID int)` | Configuración por hilo. Llamado cuando un hilo inicia. Recibe el ID del hilo.    |
+| **Hilo**     | `WithWorkerOnShutdown`       | `func(threadID int)` | Limpieza por hilo. Recibe el ID del hilo.                                        |
 
 ### Ejemplo
 

docs/es/extensions.md

@@ -87,21 +87,21 @@ Mientras que el primer punto se explica por sí mismo, el segundo puede ser más
 Aunque algunos tipos de variables tienen la misma representación en memoria entre C/PHP y Go, algunos tipos requieren más lógica para ser usados directamente. Esta es quizá la parte más difícil cuando se trata de escribir extensiones porque requiere entender los internos del motor Zend y cómo se almacenan las variables internamente en PHP.
 Esta tabla resume lo que necesitas saber:
 
-| Tipo PHP            | Tipo Go                        | Conversión directa | Helper de C a Go                     | Helper de Go a C                      | Soporte para Métodos de Clase |
-|---------------------|--------------------------------|---------------------|---------------------------------------|----------------------------------------|-------------------------------|
-| `int`               | `int64`                        | ✅                   | -                                     | -                                      | ✅                             |
-| `?int`              | `*int64`                       | ✅                   | -                                     | -                                      | ✅                             |
-| `float`             | `float64`                      | ✅                   | -                                     | -                                      | ✅                             |
-| `?float`            | `*float64`                     | ✅                   | -                                     | -                                      | ✅                             |
-| `bool`              | `bool`                         | ✅                   | -                                     | -                                      | ✅                             |
-| `?bool`             | `*bool`                        | ✅                   | -                                     | -                                      | ✅                             |
-| `string`/`?string` | `*C.zend_string`              | ❌                   | `frankenphp.GoString()`              | `frankenphp.PHPString()`              | ✅                             |
-| `array`             | `frankenphp.AssociativeArray`  | ❌                   | `frankenphp.GoAssociativeArray()`    | `frankenphp.PHPAssociativeArray()`    | ✅                             |
-| `array`             | `map[string]any`               | ❌                   | `frankenphp.GoMap()`                 | `frankenphp.PHPMap()`                 | ✅                             |
-| `array`             | `[]any`                        | ❌                   | `frankenphp.GoPackedArray()`         | `frankenphp.PHPPackedArray()`         | ✅                             |
-| `mixed`             | `any`                          | ❌                   | `GoValue()`                          | `PHPValue()`                          | ❌                             |
-| `callable`          | `*C.zval`                      | ❌                   | -                                     | frankenphp.CallPHPCallable()          | ❌                             |
-| `object`            | `struct`                       | ❌                   | _Aún no implementado_                | _Aún no implementado_                 | ❌                             |
+| Tipo PHP           | Tipo Go                       | Conversión directa | Helper de C a Go                  | Helper de Go a C                   | Soporte para Métodos de Clase |
+| ------------------ | ----------------------------- | ------------------ | --------------------------------- | ---------------------------------- | ----------------------------- |
+| `int`              | `int64`                       | ✅                 | -                                 | -                                  | ✅                            |
+| `?int`             | `*int64`                      | ✅                 | -                                 | -                                  | ✅                            |
+| `float`            | `float64`                     | ✅                 | -                                 | -                                  | ✅                            |
+| `?float`           | `*float64`                    | ✅                 | -                                 | -                                  | ✅                            |
+| `bool`             | `bool`                        | ✅                 | -                                 | -                                  | ✅                            |
+| `?bool`            | `*bool`                       | ✅                 | -                                 | -                                  | ✅                            |
+| `string`/`?string` | `*C.zend_string`              | ❌                 | `frankenphp.GoString()`           | `frankenphp.PHPString()`           | ✅                            |
+| `array`            | `frankenphp.AssociativeArray` | ❌                 | `frankenphp.GoAssociativeArray()` | `frankenphp.PHPAssociativeArray()` | ✅                            |
+| `array`            | `map[string]any`              | ❌                 | `frankenphp.GoMap()`              | `frankenphp.PHPMap()`              | ✅                            |
+| `array`            | `[]any`                       | ❌                 | `frankenphp.GoPackedArray()`      | `frankenphp.PHPPackedArray()`      | ✅                            |
+| `mixed`            | `any`                         | ❌                 | `GoValue()`                       | `PHPValue()`                       | ❌                            |
+| `callable`         | `*C.zval`                     | ❌                 | -                                 | frankenphp.CallPHPCallable()       | ❌                            |
+| `object`           | `struct`                      | ❌                 | _Aún no implementado_             | _Aún no implementado_              | ❌                            |
 
 > [!NOTE]
 >