frankenphp

FrankenPHP スキル

FrankenPHP の開発を包括的に支援します。FrankenPHP は、Caddy Web サーバーを基盤とする最新の PHP アプリケーションサーバーです。ワーカーモード、HTTPS の自動設定、HTTP/2、HTTP/3、Mercure 連携によるリアルタイム機能を備え、PHP プロセスを常時起動した状態で実行できます。

このスキルを使用する場面

次の場合に、このスキルを使用してください。

• FrankenPHP サーバーをセットアップまたは設定するとき
• パフォーマンス最適化のために FrankenPHP のワーカーモードを実装するとき
• FrankenPHP を Laravel、Symfony、その他の PHP フレームワークと連携するとき
• FrankenPHP を使用して Docker で PHP アプリケーションをデプロイするとき
• 従来の PHP アプリを常駐ワーカーで動作するように変換するとき
• HTTPS の自動設定、HTTP/2、HTTP/3 を設定するとき
• Mercure でリアルタイム機能を実装するとき
• 単独で実行できる PHP アプリケーションを作成するとき
• 常駐プロセスで PHP アプリケーションのパフォーマンスを最適化するとき
• FrankenPHP のワーカーモードや設定に関する問題をトラブルシューティングするとき

クイックリファレンス

インストールと基本的なサーバー

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

基本的なワーカーモード

スタンドアロンバイナリでワーカーを起動：

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

ワーカーモードでの 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 個のプロセスでワーカーを起動：

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

カスタムワーカースクリプト

基本的なワーカーパターン：

<?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 ワーカー：

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

ワーカーの管理

ファイルの変更を監視（自動リロード）：

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

API 経由でワーカーを再起動：

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

連続失敗の最大回数を設定（Caddyfile）：

frankenphp {
    worker {
        max_consecutive_failures 10
    }
}

ワーカーモードでのスーパーグローバル

ワーカーに紐づく値とリクエストに紐づく値へのアクセス：

<?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
};

主な概念

ワーカーモード

FrankenPHP のワーカーモードでは、リクエスト間で PHP アプリケーションをメモリ上に読み込んだ状態に保つため、パフォーマンスが大幅に向上します。リクエストごとにアプリケーションを初期化する従来の PHP とは異なり、アプリケーションは一度だけ起動し、同じプロセスで数千件のリクエストを処理します。

メリット：

• アプリケーションを一度だけ起動し、ミリ秒単位でリクエストを処理できます
• データベース接続を維持できます
• クラスと設定を事前に読み込めます
• メモリのオーバーヘッドを大幅に削減できます

主なパターン： 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 の主要なドキュメント

このリファレンスファイルには、https://frankenphp.dev/docs/ にある FrankenPHP 公式ドキュメントの詳細情報が記載されています。

次の情報が必要な場合は、リファレンスファイルを使用してください。

• プラットフォームごとの詳細なインストール手順
• Caddyfile の高度な設定例
• フレームワークごとの連携パターン（Laravel、Symfony、WordPress など）
• 本番環境へのデプロイ戦略
• パフォーマンス最適化の手法
• 静的バイナリのコンパイルガイド
• Docker の設定オプション

このスキルの活用方法

初心者の方へ

1. 基本的なインストールから始める - 最も手早くセットアップするには、curl インストールスクリプトまたは Docker を使用します
2. まず従来の PHP を実行する - ワーカーモードを使わずに frankenphp php-server を実行し、セットアップを確認します
3. 簡単なスクリプトでテストする - 基本的な index.php を作成して、サーバーの動作を理解します
4. Caddyfile の基本を学ぶ - ドメインとパスの設定方法を理解します
5. ワーカーモードを段階的に導入する - 慣れてきたら、パフォーマンス向上のためにワーカーモードへ移行します

Laravel 開発者の方へ

1. Laravel Octane を使用する - 公式統合により、最もスムーズに利用できます
2. Docker から始める - 公式の dunglas/frankenphp イメージを使用します
3. Mercure を設定する - Laravel アプリにリアルタイム機能を追加します
4. ワーカーを最適化する - トラフィックのパターンに応じてワーカー数を調整します
5. ファイル監視を使用する - 開発中に --watch を有効にして、自動再読み込みを行います

Symfony 開発者の方へ

1. Symfony ランタイムをインストールする - runtime/frankenphp-symfony パッケージを使用します
2. APP_RUNTIME を設定する - 自動統合のための環境変数を設定します
3. ワーカーモードを使用する - 永続プロセスを活用して、最大限のパフォーマンスを実現します
4. Docker でデプロイする - 本番環境では公式コンテナを使用します

本番環境へのデプロイ

1. ワーカー設定を確認する - 適切なワーカー数と最大リクエスト数を設定します
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 を使用します
4. ポートを公開する - HTTP/3 用に 80、443（TCP）、443（UDP）をマッピングします
5. localhost を使用する - https://localhost からアクセスします（127.0.0.1 ではありません）

よくあるパターン

パフォーマンスの最適化

• 本番環境のすべてのアプリケーションでワーカーモードを使用します
• ワーカーを定期的に再起動するように MAX_REQUESTS を設定します（メモリーリークを防止します）
• カスタムワーカーでは、各リクエストの後に gc_collect_cycles() を呼び出します
• 利用可能な CPU コア数とメモリーに応じてワーカー数を調整します
• 重要なアセットでは HTTP/2 プッシュを有効にします

開発ワークフロー

• 開発中の自動再読み込みには --watch フラグを使用します
• デバッグには従来のモードを使用します（問題を追跡しやすくなります）
• 開発環境と本番環境の一貫性を保つために Docker を使用します
• 環境ごと（dev、staging、prod）に異なる設定の Caddyfile を用意します

エラー処理

• ワーカーループ内でハンドラーを try-catch ブロックで囲みます
• 例外をログに記録しつつ、ワーカーの実行を継続します
• 問題のあるワーカーを再起動するために max_consecutive_failures を使用します
• Caddy 管理 API でワーカーの状態を監視します

リソース

公式ドキュメント

• メインドキュメント： https://frankenphp.dev/docs/
• ワーカーモードガイド： 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 ライブラリとして組み込み、カスタムアプリケーションに利用できます
• ワーカーモードでは、スーパーグローバルの管理に注意が必要です（クロージャーを使って状態をキャプチャしてください）
• HTTPS は Let's Encrypt によって自動的に設定されます（証明書の設定は不要です）
• HTTP/3 をサポートするには、UDP ポート 443 にアクセスできる必要があります
• ファイル監視には、システム固有のファイル監視機能を使用します（ポーリングは行わず、効率的です）

トラブルシューティング

ワーカーが起動しない

• ワーカースクリプトのパスが、絶対パスまたはドキュメントルートからの相対パスであることを確認します
• ワーカースクリプトに構文エラーがないことを確認します（php -l script.php）
• ファイルの権限を確認します（スクリプトが読み取り可能である必要があります）
• 初期化エラーがないかログを確認します

ワーカーのメモリリーク

• 各リクエストの後に gc_collect_cycles() を呼び出します
• ワーカーを定期的に再起動するため、MAX_REQUESTS を設定します
• グローバル状態が蓄積しないようにします
• 閉じられていないリソース（ファイル、接続）がないか確認します

パフォーマンスの問題

• ワーカー数を増やします（FRANKENPHP_CONFIG="worker ./index.php 42"）
• ワーカーの再起動頻度を確認します（頻繁すぎるとパフォーマンスが低下します）
• データベース接続プーリングを確認します
• ワーカーごとのメモリ使用量を監視します
• リクエストハンドラーにブロッキング処理がないことを確認します

HTTPS が機能しない

• ポート 80 と 443 にアクセスできることを確認します
• ファイアウォールのルールを確認します
• ドメインの DNS がサーバーを指していることを確認します
• ローカル開発では 127.0.0.1 ではなく localhost を使用します
• ローカルでのテストでは、ブラウザーで自己署名証明書を承認します

更新

FrankenPHP を最新の状態に保つには、次の手順を行います。

1. 公式 GitHub リポジトリをフォローして、更新情報を確認します
2. 破壊的変更がないか変更履歴を確認します
3. ステージング環境で更新をテストします
4. Docker イメージを定期的に更新します（docker pull dunglas/frankenphp:latest）
5. バージョンの互換性について、フレームワーク固有の統合ドキュメントを確認します