frankenphp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FrankenPHP Skill

FrankenPHP 技能指南

Comprehensive assistance with FrankenPHP development - a modern PHP application server built on top of the Caddy web server. FrankenPHP enables persistent PHP processes with worker mode, automatic HTTPS, HTTP/2, HTTP/3, and real-time capabilities via Mercure integration.

为FrankenPHP开发提供全面支持——这是一款基于Caddy Web服务器构建的现代化PHP应用服务器。FrankenPHP通过Worker模式实现持久化PHP进程，支持自动HTTPS、HTTP/2、HTTP/3，并可通过Mercure集成实现实时功能。

When to Use This Skill

何时使用本技能

This skill should be triggered when:

Setting up or configuring FrankenPHP server
Implementing FrankenPHP worker mode for performance optimization
Integrating FrankenPHP with Laravel, Symfony, or other PHP frameworks
Deploying PHP applications with Docker using FrankenPHP
Converting traditional PHP apps to use persistent workers
Configuring automatic HTTPS, HTTP/2, or HTTP/3
Implementing real-time features with Mercure
Creating standalone, self-executable PHP applications
Optimizing PHP application performance with persistent processes
Troubleshooting FrankenPHP worker mode or configuration issues

在以下场景下可触发本技能：

搭建或配置FrankenPHP服务器
实现FrankenPHP Worker模式以优化性能
将FrankenPHP与Laravel、Symfony或其他PHP框架集成
使用FrankenPHP通过Docker部署PHP应用
将传统PHP应用转换为使用持久化Worker
配置自动HTTPS、HTTP/2或HTTP/3
通过Mercure实现实时功能
创建独立的可自执行PHP应用
利用持久化进程优化PHP应用性能
排查FrankenPHP Worker模式或配置问题

Quick Reference

快速参考

Installation & Basic Server

安装与基础服务器

Install via curl (Linux/macOS):

bash

curl https://frankenphp.dev/install.sh | sh
mv frankenphp /usr/local/bin/

通过curl安装（Linux/macOS）：

bash

curl https://frankenphp.dev/install.sh | sh
mv frankenphp /usr/local/bin/

Start server in current directory

在当前目录启动服务器

frankenphp php-server


**Install via Homebrew:**
```bash
brew install dunglas/frankenphp/frankenphp
frankenphp php-server

Quick Docker deployment:

bash

docker run -v $PWD:/app/public \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

frankenphp php-server


**通过Homebrew安装：**
```bash
brew install dunglas/frankenphp/frankenphp
frankenphp php-server

Docker快速部署：

bash

docker run -v $PWD:/app/public \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

Basic Worker Mode

基础Worker模式

Start worker with standalone binary:

bash

frankenphp php-server --worker /path/to/your/worker/script.php

Docker with worker mode:

bash

docker run \
    -e FRANKENPHP_CONFIG="worker /app/public/index.php" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

Worker with 42 processes:

bash

docker run \
    -e FRANKENPHP_CONFIG="worker ./public/index.php 42" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

通过独立二进制文件启动Worker：

bash

frankenphp php-server --worker /path/to/your/worker/script.php

Docker环境下的Worker模式：

bash

docker run \
    -e FRANKENPHP_CONFIG="worker /app/public/index.php" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

启动42个Worker进程：

bash

docker run \
    -e FRANKENPHP_CONFIG="worker ./public/index.php 42" \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

Custom Worker Script

自定义Worker脚本

Basic worker pattern:

php

<?php
// public/index.php

ignore_user_abort(true);

require __DIR__.'/vendor/autoload.php';

$myApp = new \App\Kernel();
$myApp->boot();

$handler = static function () use ($myApp) {
    try {
        echo $myApp->handle($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER);
    } catch (\Throwable $exception) {
        (new \MyCustomExceptionHandler)->handleException($exception);
    }
};

$maxRequests = (int)($_SERVER['MAX_REQUESTS'] ?? 0);
for ($nbRequests = 0; !$maxRequests || $nbRequests < $maxRequests; ++$nbRequests) {
    $keepRunning = \frankenphp_handle_request($handler);
    $myApp->terminate();
    gc_collect_cycles();
    if (!$keepRunning) break;
}

$myApp->shutdown();

基础Worker模式示例：

php

<?php
// public/index.php

ignore_user_abort(true);

require __DIR__.'/vendor/autoload.php';

$myApp = new \App\Kernel();
$myApp->boot();

$handler = static function () use ($myApp) {
    try {
        echo $myApp->handle($_GET, $_POST, $_COOKIE, $_FILES, $_SERVER);
    } catch (\Throwable $exception) {
        (new \MyCustomExceptionHandler)->handleException($exception);
    }
};

$maxRequests = (int)($_SERVER['MAX_REQUESTS'] ?? 0);
for ($nbRequests = 0; !$maxRequests || $nbRequests < $maxRequests; ++$nbRequests) {
    $keepRunning = \frankenphp_handle_request($handler);
    $myApp->terminate();
    gc_collect_cycles();
    if (!$keepRunning) break;
}

$myApp->shutdown();

Laravel Integration

Laravel集成

Laravel Octane installation:

bash

composer require laravel/octane
php artisan octane:install --server=frankenphp
php artisan octane:frankenphp

Laravel with Docker:

bash

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v $PWD:/app \
    dunglas/frankenphp

Laravel Caddyfile:

{
	frankenphp
}

localhost {
	root public/
	encode zstd br gzip
	php_server {
		try_files {path} index.php
	}
}

Octane with file watching:

bash

php artisan octane:frankenphp --watch

Laravel Octane安装：

bash

composer require laravel/octane
php artisan octane:install --server=frankenphp
php artisan octane:frankenphp

Docker环境下的Laravel：

bash

docker run -p 80:80 -p 443:443 -p 443:443/udp \
    -v $PWD:/app \
    dunglas/frankenphp

Laravel Caddyfile配置：

{
	frankenphp
}

localhost {
	root public/
	encode zstd br gzip
	php_server {
		try_files {path} index.php
	}
}

开启文件监听的Octane：

bash

php artisan octane:frankenphp --watch

Symfony Integration

Symfony集成

Symfony worker with runtime:

bash

composer require runtime/frankenphp-symfony

docker run \
    -e FRANKENPHP_CONFIG="worker ./public/index.php" \
    -e APP_RUNTIME=Runtime\\FrankenPhpSymfony\\Runtime \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

使用Runtime的Symfony Worker：

bash

composer require runtime/frankenphp-symfony

docker run \
    -e FRANKENPHP_CONFIG="worker ./public/index.php" \
    -e APP_RUNTIME=Runtime\\FrankenPhpSymfony\\Runtime \
    -v $PWD:/app \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

Worker Management

Worker管理

Watch files for changes (auto-reload):

bash

frankenphp php-server --worker /path/to/worker.php \
    --watch="/path/to/your/app/**/*.php"

Restart workers via API:

bash

curl -X POST http://localhost:2019/frankenphp/workers/restart

Configure max consecutive failures (Caddyfile):

frankenphp {
    worker {
        max_consecutive_failures 10
    }
}

监听文件变更（自动重载）：

bash

frankenphp php-server --worker /path/to/worker.php \
    --watch="/path/to/your/app/**/*.php"

通过API重启Worker：

bash

curl -X POST http://localhost:2019/frankenphp/workers/restart

配置最大连续失败次数（Caddyfile）：

frankenphp {
    worker {
        max_consecutive_failures 10
    }
}

Superglobals in Worker Mode

Worker模式中的超全局变量

Accessing worker-bound vs request-bound values:

php

<?php
// Capture worker-level values before request loop
$workerServer = $_SERVER;

$handler = static function () use ($workerServer) {
    var_dump($_SERVER);      // Current request superglobals
    var_dump($workerServer); // Original worker values
};

区分Worker绑定与请求绑定的值：

php

<?php
// 在请求循环前捕获Worker级别的值
$workerServer = $_SERVER;

$handler = static function () use ($workerServer) {
    var_dump($_SERVER);      // 当前请求的超全局变量
    var_dump($workerServer); // 原始的Worker级变量
};

Key Concepts

核心概念

Worker Mode

Worker模式

FrankenPHP's worker mode keeps your PHP application loaded in memory between requests, dramatically improving performance. Instead of bootstrapping your application for each request (traditional PHP), the application boots once and handles thousands of requests with the same process.

Benefits:

Boot your application once, handle requests in milliseconds
Persistent database connections
Preloaded classes and configuration
Significantly reduced memory overhead

Key Pattern: Use

frankenphp_handle_request($handler)

to process each request within a persistent loop, calling

gc_collect_cycles()

after each request to prevent memory leaks.

FrankenPHP的Worker模式可让PHP应用在请求之间保持内存加载状态，大幅提升性能。与传统PHP为每个请求重新启动应用不同，该模式下应用只需启动一次，即可用同一进程处理数千个请求。

优势：

应用只需启动一次，请求处理耗时缩短至毫秒级
持久化数据库连接
预加载类与配置
显著降低内存开销

核心模式： 使用

frankenphp_handle_request($handler)

在持久化循环中处理每个请求，在每个请求后调用

gc_collect_cycles()

以防止内存泄漏。

Caddy Integration

Caddy集成

FrankenPHP is built on top of Caddy, meaning you get:

Automatic HTTPS - Zero-config TLS certificates via Let's Encrypt
HTTP/2 & HTTP/3 - Modern protocol support out of the box
Powerful configuration - Use Caddyfile for server configuration

FrankenPHP基于Caddy构建，因此你可获得：

自动HTTPS - 通过Let's Encrypt实现零配置TLS证书
HTTP/2与HTTP/3 - 原生支持现代协议
强大的配置能力 - 使用Caddyfile进行服务器配置

Early Hints (103 Status)

Early Hints（103状态码）

FrankenPHP supports HTTP 103 Early Hints, allowing browsers to start loading critical resources (CSS, JS, fonts) while the server is still generating the full response.

FrankenPHP支持HTTP 103 Early Hints，允许浏览器在服务器生成完整响应的同时，开始加载关键资源（CSS、JS、字体等）。

Mercure Real-Time

Mercure实时功能

Built-in support for Mercure protocol enables real-time push notifications from server to browser using Server-Sent Events (SSE). Perfect for live updates, notifications, and collaborative features.

内置对Mercure协议的支持，可通过Server-Sent Events（SSE）实现从服务器到浏览器的实时推送通知，非常适合实时更新、通知和协作功能。

Reference Files

参考文件

This skill includes comprehensive documentation in

references/

other.md - Core FrankenPHP documentation including installation, configuration, worker mode, framework integration, deployment, and production setup

The reference file contains detailed information from the official FrankenPHP documentation at https://frankenphp.dev/docs/

Use the reference file when you need:

Detailed installation instructions for different platforms
Advanced Caddyfile configuration examples
Framework-specific integration patterns (Laravel, Symfony, WordPress, etc.)
Production deployment strategies
Performance optimization techniques
Static binary compilation guides
Docker configuration options

本技能在

references/

目录下包含完整文档：

other.md - FrankenPHP核心文档，包括安装、配置、Worker模式、框架集成、部署和生产环境设置

参考文件包含来自FrankenPHP官方文档（https://frankenphp.dev/docs/）的详细信息

在以下场景下可使用参考文件：

不同平台的详细安装说明
高级Caddyfile配置示例
特定框架的集成模式（Laravel、Symfony、WordPress等）
生产环境部署策略
性能优化技巧
静态二进制编译指南
Docker配置选项

Working with This Skill

如何使用本技能

For Beginners

面向初学者

Start with basic installation - Use the curl install script or Docker for quickest setup
Run traditional PHP first - Use
```
frankenphp php-server
```
without worker mode to verify setup
Test with simple scripts - Create a basic
```
index.php
```
to understand the server behavior
Learn Caddyfile basics - Understand how to configure domains and paths
Gradually adopt worker mode - Once comfortable, convert to worker mode for performance

从基础安装开始 - 使用curl安装脚本或Docker快速完成搭建
先运行传统PHP - 使用
```
frankenphp php-server
```
（不启用Worker模式）验证搭建是否成功
使用简单脚本测试 - 创建基础的
```
index.php
```
以了解服务器行为
学习Caddyfile基础 - 了解如何配置域名和路径
逐步采用Worker模式 - 熟悉后，转换为Worker模式以提升性能

For Laravel Developers

面向Laravel开发者

Use Laravel Octane - The official integration provides the smoothest experience
Start with Docker - Use the official
```
dunglas/frankenphp
```
image
Configure Mercure - Add real-time capabilities to your Laravel app
Optimize workers - Tune worker count based on your traffic patterns
Use file watching - Enable
```
--watch
```
during development for auto-reload

使用Laravel Octane - 官方集成提供最流畅的体验
从Docker开始 - 使用官方
```
dunglas/frankenphp
```
镜像
配置Mercure - 为Laravel应用添加实时功能
优化Worker数量 - 根据流量模式调整Worker数量
启用文件监听 - 开发期间启用
```
--watch
```
实现自动重载

For Symfony Developers

面向Symfony开发者

Install Symfony runtime - Use
```
runtime/frankenphp-symfony
```
package
Set APP_RUNTIME - Configure environment variable for automatic integration
Use worker mode - Leverage persistent processes for maximum performance
Deploy with Docker - Use official containers for production

安装Symfony Runtime - 使用
```
runtime/frankenphp-symfony
```
包
设置APP_RUNTIME - 配置环境变量以实现自动集成
使用Worker模式 - 利用持久化进程实现最佳性能
通过Docker部署 - 使用官方容器部署到生产环境

For Production Deployment

面向生产环境部署

Review worker configuration - Set appropriate worker count and max requests
Configure failure handling - Set
```
max_consecutive_failures
```
threshold
Enable monitoring - Use Caddy admin API for health checks and metrics
Set up log analytics - Configure structured JSON logs
Plan restart strategy - Use
```
MAX_REQUESTS
```
or manual API restarts to prevent memory leaks
Test with load - Validate performance under realistic traffic patterns

检查Worker配置 - 设置合适的Worker数量和最大请求数
配置故障处理 - 设置
```
max_consecutive_failures
```
阈值
启用监控 - 使用Caddy Admin API进行健康检查和指标监控
设置日志分析 - 配置结构化JSON日志
规划重启策略 - 使用
```
MAX_REQUESTS
```
或手动API重启以防止内存泄漏
进行负载测试 - 在真实流量模式下验证性能

For Docker Users

面向Docker用户

Use official images - Start with

dunglas/frankenphp

dunglas/frankenphp:static-builder

Mount your app - Volume mount your code to
```
/app
```
Configure via ENV - Use
```
FRANKENPHP_CONFIG
```
for worker setup
Expose ports - Map 80, 443 (TCP), and 443 (UDP) for HTTP/3
Use localhost - Access via
```
https://localhost
```
(not 127.0.0.1)

使用官方镜像 - 从

dunglas/frankenphp

或

dunglas/frankenphp:static-builder

开始

挂载应用代码 - 将代码卷挂载到
```
/app
```
目录
通过环境变量配置 - 使用
```
FRANKENPHP_CONFIG
```
设置Worker
暴露端口 - 映射80、443（TCP）和443（UDP）以支持HTTP/3
使用localhost - 通过
```
https://localhost
```
访问（而非127.0.0.1）

Common Patterns

常见模式

Performance Optimization

性能优化

Use worker mode for all production applications
Set MAX_REQUESTS to restart workers periodically (prevents memory leaks)
Call gc_collect_cycles() after each request in custom workers
Tune worker count based on CPU cores and memory available
Enable HTTP/2 push for critical assets

在生产环境中使用Worker模式
设置MAX_REQUESTS以定期重启Worker（防止内存泄漏）
在自定义Worker中每个请求后调用
gc_collect_cycles()
根据CPU核心数和可用内存调整Worker数量
为关键资源启用HTTP/2推送

Development Workflow

开发工作流

Use --watch flag for automatic reload during development
Traditional mode for debugging (easier to trace issues)
Docker for consistency across development and production environments
Caddyfile per environment (dev, staging, prod) with different configs

使用--watch标志在开发期间实现自动重载
使用传统模式进行调试（更容易追踪问题）
使用Docker确保开发与生产环境一致
为不同环境（开发、 staging、生产）配置独立的Caddyfile

Error Handling

错误处理

Wrap handlers in try-catch blocks within worker loop
Log exceptions but keep worker running
Use max_consecutive_failures to restart problematic workers
Monitor worker health via Caddy admin API

在Worker循环中用try-catch块包裹处理器
记录异常但保持Worker运行
使用max_consecutive_failures重启有问题的Worker
通过Caddy Admin API监控Worker健康状态

Resources

资源

Official Documentation

官方文档

Main docs: https://frankenphp.dev/docs/
Worker mode guide: https://frankenphp.dev/docs/worker/
Laravel integration: https://frankenphp.dev/docs/laravel/
Symfony integration: https://frankenphp.dev/docs/symfony/

主文档： https://frankenphp.dev/docs/
Worker模式指南： https://frankenphp.dev/docs/worker/
Laravel集成： https://frankenphp.dev/docs/laravel/
Symfony集成： https://frankenphp.dev/docs/symfony/

Framework Integration

框架集成

Laravel Octane: Official integration via
```
laravel/octane
```
package
Symfony Runtime: Use
```
runtime/frankenphp-symfony
```
package
WordPress, Drupal, Joomla, TYPO3: Supported frameworks
API Platform: First-class FrankenPHP support

Laravel Octane：通过
```
laravel/octane
```
包实现官方集成
Symfony Runtime：使用
```
runtime/frankenphp-symfony
```
包
WordPress、Drupal、Joomla、TYPO3：均为支持的框架
API Platform：原生支持FrankenPHP

Docker Images

Docker镜像

Production:
```
dunglas/frankenphp
```
Static builder:
```
dunglas/frankenphp:static-builder
```
Latest tag: Always includes PHP 8.4+ and popular extensions

生产环境：
```
dunglas/frankenphp
```
静态构建器：
```
dunglas/frankenphp:static-builder
```
Latest标签： 始终包含PHP 8.4+及常用扩展

Notes

注意事项

FrankenPHP includes PHP 8.4 and most popular extensions in static binaries
Can be embedded as a Go library via
```
net/http
```
for custom applications
Worker mode requires careful superglobals management (use closures to capture state)
HTTPS is automatic via Let's Encrypt (no certificate configuration needed)
HTTP/3 support requires UDP port 443 to be accessible
File watching uses system-specific file monitoring (efficient, no polling)

FrankenPHP的静态二进制文件包含PHP 8.4及大多数常用扩展
可通过
```
net/http
```
作为Go库嵌入到自定义应用中
Worker模式需要谨慎管理超全局变量（使用闭包捕获状态）
通过Let's Encrypt自动实现HTTPS（无需证书配置）
HTTP/3支持要求UDP端口443可访问
文件监听使用系统特定的文件监控机制（高效，无轮询）

Troubleshooting

故障排查

Worker Not Starting

Worker无法启动

Check worker script path is absolute or relative to document root
Verify worker script has no syntax errors (
```
php -l script.php
```
)
Check file permissions (script must be readable)
Review logs for initialization errors

检查Worker脚本路径是否为绝对路径或相对于文档根目录
验证Worker脚本无语法错误（
```
php -l script.php
```
）
检查文件权限（脚本必须可读）
查看初始化错误日志

Memory Leaks in Workers

Worker内存泄漏

Call
```
gc_collect_cycles()
```
after each request
Set
```
MAX_REQUESTS
```
to restart workers periodically
Avoid global state accumulation
Check for unclosed resources (files, connections)

在每个请求后调用
```
gc_collect_cycles()
```
设置
```
MAX_REQUESTS
```
以定期重启Worker
避免全局状态累积
检查是否有未关闭的资源（文件、连接）

Performance Issues

性能问题

Increase worker count (

FRANKENPHP_CONFIG="worker ./index.php 42"

)

Check worker restart frequency (too frequent = performance loss)
Review database connection pooling
Monitor memory usage per worker
Verify no blocking operations in request handler

增加Worker数量（

FRANKENPHP_CONFIG="worker ./index.php 42"

）

检查Worker重启频率（过于频繁会导致性能损失）
检查数据库连接池配置
监控每个Worker的内存使用情况
验证请求处理器中无阻塞操作

HTTPS Not Working

HTTPS无法工作

Ensure ports 80 and 443 are accessible
Check firewall rules
Verify domain DNS points to server
Use
```
localhost
```
(not 127.0.0.1) for local development
Accept self-signed certificate in browser for local testing

确保端口80和443可访问
检查防火墙规则
验证域名DNS指向服务器
本地开发使用
```
localhost
```
（而非127.0.0.1）
本地测试时在浏览器中接受自签名证书

Updating

更新

To stay current with FrankenPHP:

Follow the official GitHub repository for updates
Review changelog for breaking changes
Test updates in staging environment
Update Docker images regularly (
```
docker pull dunglas/frankenphp:latest
```
)
Check framework-specific integration docs for version compatibility

保持FrankenPHP为最新版本：

关注官方GitHub仓库获取更新
查看变更日志了解破坏性变更
在 staging环境测试更新
定期更新Docker镜像（
```
docker pull dunglas/frankenphp:latest
```
）
检查特定框架的集成文档以确认版本兼容性