From 67a71a6300bfa366b9db8ec9ea225ad5b635789a Mon Sep 17 00:00:00 2001 From: Ousama Ben Younes Date: Sun, 26 Jul 2026 13:07:17 +0000 Subject: [PATCH 1/2] docs: document HTTP request filtering differences --- docs/migrate.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/migrate.md b/docs/migrate.md index 668da2be54..f721098a5f 100644 --- a/docs/migrate.md +++ b/docs/migrate.md @@ -18,6 +18,27 @@ This guide covers a basic migration for a typical PHP application. | `php_value` / `php_admin_value` | [`php_ini` Caddyfile directive](config.md#php-config) | | `pm = static` / `pm.max_children` | `num_threads` | | `pm = dynamic` | [`max_threads auto`](performance.md#max_threads) | +| Web server request filtering | Caddy routes and matchers | + +## HTTP request filtering + +When migrating from a stock Nginx or Apache package, check any request filtering that was done by the web server before PHP-FPM received the request. +FrankenPHP is built on Caddy, so valid HTTP methods and headers are passed through Caddy's normal routing unless your `Caddyfile` rejects them first. + +For example, some web servers reject `TRACE` requests by default. +If your application should keep that behavior, add an explicit matcher before `php_server`: + +```caddyfile +example.com { + @trace method TRACE + respond @trace 405 + + root /var/www/app/public + php_server +} +``` + +Apply the same approach to any stricter method or header policy your previous front web server enforced. ## Step 1: replace your web server config From 7a8c599803ecfba84c9c8b31ac188dade32fc540 Mon Sep 17 00:00:00 2001 From: Ousama Ben Younes Date: Sun, 26 Jul 2026 13:29:02 +0000 Subject: [PATCH 2/2] docs: mention request header filtering on migration --- docs/migrate.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/migrate.md b/docs/migrate.md index f721098a5f..97fc962a84 100644 --- a/docs/migrate.md +++ b/docs/migrate.md @@ -23,7 +23,7 @@ This guide covers a basic migration for a typical PHP application. ## HTTP request filtering When migrating from a stock Nginx or Apache package, check any request filtering that was done by the web server before PHP-FPM received the request. -FrankenPHP is built on Caddy, so valid HTTP methods and headers are passed through Caddy's normal routing unless your `Caddyfile` rejects them first. +FrankenPHP is built on Caddy, so valid HTTP methods and headers are passed through Caddy's normal routing unless your `Caddyfile` or another proxy rejects them first. For example, some web servers reject `TRACE` requests by default. If your application should keep that behavior, add an explicit matcher before `php_server`: @@ -39,6 +39,7 @@ example.com { ``` Apply the same approach to any stricter method or header policy your previous front web server enforced. +This is also relevant for request header names: some front web servers or proxies reject or drop valid-but-uncommon HTTP field names before PHP-FPM sees them, while FrankenPHP may pass them to the PHP application. ## Step 1: replace your web server config