frankenphp

用途

FrankenPHP 是一个基于 Caddy 网络服务器构建的现代 PHP 应用服务器。本技能为 FrankenPHP 开发提供全面协助，涵盖服务器搭建与配置、性能优化、框架集成与部署等场景。

主要能力

Worker 模式：保持 PHP 应用在请求之间常驻内存，应用只启动一次即可处理成千上万的请求，从而提升性能，并提供持久数据库连接、预加载类与配置、显著降低内存开销。
Caddy 集成：自动 HTTPS（通过 Let's Encrypt 零配置 TLS 证书）、HTTP/2 与 HTTP/3、通过 Caddyfile 进行强大配置、Early Hints（103 状态）。
Mercure 实时能力：内置 Mercure 协议支持，可基于 Server-Sent Events（SSE）实现服务器到浏览器的实时推送。

使用方式

安装（Linux/macOS）：

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

# 在当前目录启动服务器
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 模式：

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

Docker 中启用 worker 模式：

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 脚本模式：

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

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

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 模式下的超全局变量：

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

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

适用场景

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

限制与注意事项

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

参考资源

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

Docker 镜像：生产环境使用 dunglas/frankenphp；静态构建器为 dunglas/frankenphp:static-builder；latest 标签始终包含 PHP 8.4+ 及流行扩展。