Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dunglas wants to merge 4 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f458ebf
docs: improver worker docs, and add internals docs
dunglas Apr 8, 2026
8391cd8
fix
dunglas Apr 8, 2026
3d4071b
CS
dunglas Apr 9, 2026
4409a2e
grammar fixes
dunglas Apr 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,7 +299,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.
Expand Down Expand Up @@ -348,7 +348,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.
Expand Down
12 changes: 6 additions & 6 deletions docs/cn/extension-workers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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。 |

### 示例

Expand Down
6 changes: 3 additions & 3 deletions docs/cn/hot-reload.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ FrankenPHP 包含一个内置的**热重载**功能，旨在极大改善开发
>
> 此功能仅适用于**开发环境**。
> 请勿在生产环境中启用 `hot_reload`，因为此功能不安全（会暴露敏感的内部细节）并且会降低应用程序的速度。
>

```caddyfile
localhost

Expand Down Expand Up @@ -145,5 +145,5 @@ php_server {
4. **接收**：浏览器通过 JavaScript 库监听，接收 Mercure 事件。
5. **更新**：

- 如果检测到 **Idiomorph**，它会获取更新的内容并修改当前的 HTML 以匹配新状态，即时应用更改而不会丢失状态。
- 否则，将调用 `window.location.reload()` 来刷新页面。
- 如果检测到 **Idiomorph**，它会获取更新的内容并修改当前的 HTML 以匹配新状态，即时应用更改而不会丢失状态。
- 否则，将调用 `window.location.reload()` 来刷新页面。
1 change: 1 addition & 0 deletions docs/cn/worker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,3 +184,4 @@ $handler = static function () use ($workerServer) {
};

// ...
```
4 changes: 2 additions & 2 deletions docs/es/classic.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 [escale 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`.
10 changes: 5 additions & 5 deletions docs/es/compile.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion docs/es/embed.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
10 changes: 5 additions & 5 deletions docs/es/extension-workers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. |
| 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. |
| **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. |

### Ejemplo

Expand Down
30 changes: 15 additions & 15 deletions docs/es/extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
>
Expand Down
12 changes: 6 additions & 6 deletions docs/es/known-issues.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,17 +4,17 @@

Las siguientes extensiones se sabe que no son compatibles con FrankenPHP:

| Nombre | Razón | Alternativas |
| ----------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [imap](https://www.php.net/manual/es/imap.installation.php) | No es thread-safe | [javanile/php-imap2](https://github.com/javanile/php-imap2), [webklex/php-imap](https://github.com/Webklex/php-imap) |
| [newrelic](https://docs.newrelic.com/docs/apm/agents/php-agent/getting-started/introduction-new-relic-php/) | No es thread-safe | - |
| Nombre | Razón | Alternativas |
| ----------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| [imap](https://www.php.net/manual/es/imap.installation.php) | No es thread-safe | [javanile/php-imap2](https://github.com/javanile/php-imap2), [webklex/php-imap](https://github.com/Webklex/php-imap) |
| [newrelic](https://docs.newrelic.com/docs/apm/agents/php-agent/getting-started/introduction-new-relic-php/) | No es thread-safe | - |

## Extensiones PHP con Errores

Las siguientes extensiones tienen errores conocidos y comportamientos inesperados cuando se usan con FrankenPHP:

| Nombre | Problema |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nombre | Problema |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ext-openssl](https://www.php.net/manual/es/book.openssl.php) | Cuando se usa musl libc, la extensión OpenSSL puede fallar bajo cargas pesadas. El problema no ocurre cuando se usa la más popular GNU libc. Este error está [siendo rastreado por PHP](https://github.com/php/php-src/issues/13648). |

## get_browser
Expand Down
Loading
Loading