frankenphp

FrankenPHP 技能

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

何时使用此技能

遇到以下情况时，应触发此技能：

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

快速参考

安装与基础服务

通过 curl 安装（Linux/macOS）：

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

# Start server in current directory
frankenphp php-server

通过 Homebrew 安装：

brew install dunglas/frankenphp/frankenphp
frankenphp php-server

快速通过 Docker 部署：

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

基础 Worker 模式

使用独立二进制文件启动 Worker：

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

使用 Worker 模式的 Docker：

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：

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 脚本

基础 Worker 模式：

<?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 集成

安装 Laravel Octane：

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

使用 Docker 的 Laravel：

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：

php artisan octane:frankenphp --watch

Symfony 集成

使用 Runtime 的 Symfony Worker：

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 管理

监视文件更改（自动重新加载）：

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

通过 API 重启 Worker：

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

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

frankenphp {
    worker {
        max_consecutive_failures 10
    }
}

Worker 模式下的超全局变量

访问 Worker 级与请求级变量：

<?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 模式

FrankenPHP 的 Worker 模式会在请求之间将 PHP 应用保留在内存中，从而大幅提升性能。传统 PHP 会为每个请求引导应用，而 Worker 模式只需引导一次，即可由同一进程处理数千个请求。

优势：

• 只需引导一次应用，即可在数毫秒内处理请求
• 持久化数据库连接
• 预加载的类和配置
• 显著降低内存开销

关键模式： 使用 frankenphp_handle_request($handler) 在持久化循环中处理每个请求，并在每次请求后调用 gc_collect_cycles()，以防止内存泄漏。

Caddy 集成

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

• 自动 HTTPS——通过 Let's Encrypt 获取零配置 TLS 证书
• HTTP/2 和 HTTP/3——开箱即用的现代协议支持
• 强大的配置能力——使用 Caddyfile 配置服务

Early Hints（103 状态码）

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

Mercure 实时功能

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

参考文件

此技能在 references/ 中包含全面的文档：

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

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

需要以下内容时，请使用参考文件：

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

使用此 Skill

初学者

1. 从基本安装开始 - 使用 curl 安装脚本或 Docker，快速完成设置
2. 先运行传统 PHP - 使用 frankenphp php-server，不启用 worker 模式，以验证设置
3. 使用简单脚本测试 - 创建一个基本的 index.php，了解服务的运行方式
4. 学习 Caddyfile 基础知识 - 了解如何配置域名和路径
5. 逐步采用 worker 模式 - 熟悉后，切换到 worker 模式以提升性能

Laravel 开发者

1. 使用 Laravel Octane - 官方集成可提供最顺畅的体验
2. 从 Docker 开始 - 使用官方 dunglas/frankenphp 镜像
3. 配置 Mercure - 为 Laravel 应用添加实时功能
4. 优化 worker - 根据流量模式调整 worker 数量
5. 使用文件监视 - 开发期间启用 --watch，以自动重新加载

Symfony 开发者

1. 安装 Symfony runtime - 使用 runtime/frankenphp-symfony 软件包
2. 设置 APP_RUNTIME - 配置环境变量以实现自动集成
3. 使用 worker 模式 - 利用持久进程实现最高性能
4. 使用 Docker 部署 - 使用官方容器进行生产部署

生产环境部署

1. 检查 worker 配置 - 设置合适的 worker 数量和最大请求数
2. 配置故障处理 - 设置 max_consecutive_failures 阈值
3. 启用监控 - 使用 Caddy 管理 API 进行运行状况检查和指标监控
4. 设置日志分析 - 配置结构化 JSON 日志
5. 规划重启策略 - 使用 MAX_REQUESTS 或通过手动调用 API 重启，以防止内存泄漏
6. 进行负载测试 - 在贴近实际的流量模式下验证性能

Docker 用户

1. 使用官方镜像 - 从 dunglas/frankenphp 或 dunglas/frankenphp:static-builder 开始
2. 挂载应用 - 将代码作为卷挂载到 /app
3. 通过 ENV 配置 - 使用 FRANKENPHP_CONFIG 配置 worker
4. 开放端口 - 映射 80、443（TCP）和 443（UDP），以支持 HTTP/3
5. 使用 localhost - 通过 https://localhost 访问（不要使用 127.0.0.1）

常见模式

性能优化

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

开发工作流

• 使用 --watch 标志，在开发期间自动重新加载
• 调试时使用传统模式（更容易追踪问题）
• 使用 Docker，确保开发环境与生产环境保持一致
• 为不同环境分别使用 Caddyfile（dev、staging、prod），并配置不同参数

错误处理

• 在 worker 循环中使用 try-catch 块包装处理程序
• 记录异常，但让 worker 继续运行
• 使用 max_consecutive_failures 重启有问题的 worker
• 通过 Caddy 管理 API 监控 worker 运行状况

资源

官方文档

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

框架集成

• Laravel Octane：通过 laravel/octane 软件包提供的官方集成
• Symfony Runtime：使用 runtime/frankenphp-symfony 软件包
• WordPress、Drupal、Joomla、TYPO3：支持的框架
• API Platform：一流的 FrankenPHP 支持

Docker 镜像

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

备注

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

故障排除

Worker 无法启动

• 检查 Worker 脚本路径是否为绝对路径，或是否相对于文档根目录
• 确认 Worker 脚本没有语法错误（php -l script.php）
• 检查文件权限（脚本必须可读）
• 查看日志中的初始化错误

Worker 中的内存泄漏

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

性能问题

• 增加 Worker 数量（FRANKENPHP_CONFIG="worker ./index.php 42"）
• 检查 Worker 重启频率（过于频繁会降低性能）
• 检查数据库连接池
• 监控每个 Worker 的内存使用情况
• 确认请求处理程序中没有阻塞操作

HTTPS 无法正常工作

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

更新

如需及时了解 FrankenPHP 的最新动态：

1. 关注官方 GitHub 仓库以获取更新
2. 查看变更日志，了解不兼容变更
3. 在预发布环境中测试更新
4. 定期更新 Docker 镜像（docker pull dunglas/frankenphp:latest）
5. 查看框架专属的集成文档，确认版本兼容性