Конфигурация

FrankenPHP, Caddy, а также модули Mercure и Vulcain могут быть настроены с использованием форматов, поддерживаемых Caddy.

Наиболее распространенным форматом является Caddyfile, который представляет собой простой, удобочитаемый текстовый формат. По умолчанию FrankenPHP будет искать Caddyfile в текущей директории. Вы можете указать пользовательский путь с помощью опции -c или --config.

Ниже показан минимальный Caddyfile для обслуживания PHP-приложения:

# Хостнейм, на который будет отвечать сервер
localhost

# Опционально, директория для обслуживания файлов, иначе по умолчанию используется текущая директория
#root public/
php_server

Более продвинутый Caddyfile, включающий дополнительные функции и предоставляющий удобные переменные окружения, можно найти в репозитории FrankenPHP, а также в Docker-образах.

PHP можно настроить с помощью файла php.ini.

В зависимости от метода установки, FrankenPHP и PHP-интерпретатор будут искать конфигурационные файлы в местах, описанных ниже.

FrankenPHP:

• /etc/frankenphp/Caddyfile: основной файл конфигурации
• /etc/frankenphp/Caddyfile.d/*.caddyfile: дополнительные файлы конфигурации, которые загружаются автоматически

PHP:

• php.ini: /usr/local/etc/php/php.ini (по умолчанию php.ini не предоставляется)
• дополнительные файлы конфигурации: /usr/local/etc/php/conf.d/*.ini
• расширения PHP: /usr/local/lib/php/extensions/no-debug-zts-<YYYYMMDD>/
• Вы должны скопировать официальный шаблон, предоставляемый проектом PHP:

FROM dunglas/frankenphp

# Production:
RUN cp $PHP_INI_DIR/php.ini-production $PHP_INI_DIR/php.ini

# Или development:
RUN cp $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini

FrankenPHP:

• /etc/frankenphp/Caddyfile: основной файл конфигурации
• /etc/frankenphp/Caddyfile.d/*.caddyfile: дополнительные файлы конфигурации, которые загружаются автоматически

PHP:

• php.ini: /etc/php-zts/php.ini (по умолчанию предоставляется файл php.ini с производственными настройками)
• дополнительные файлы конфигурации: /etc/php-zts/conf.d/*.ini

FrankenPHP:

• В текущей рабочей директории: Caddyfile

PHP:

• php.ini: Директория, в которой выполняется frankenphp run или frankenphp php-server, затем /etc/frankenphp/php.ini
• дополнительные файлы конфигурации: /etc/frankenphp/php.d/*.ini
• расширения PHP: не могут быть загружены, их следует встраивать в сам бинарный файл
• скопируйте один из шаблонов php.ini-production или php.ini-development, предоставленных в исходниках PHP.

HTTP-директивы php_server или php могут быть использованы в блоках сайта для обслуживания вашего PHP-приложения.

Минимальный пример:

localhost {
	# Включить сжатие (опционально)
	encode zstd br gzip
	# Выполнять PHP-файлы в текущей директории и обслуживать ресурсы
	php_server
}

Вы также можете явно настроить FrankenPHP, используя глобальную опцию frankenphp:

{
	frankenphp {
		num_threads <num_threads> # Устанавливает количество запускаемых потоков PHP. По умолчанию: 2x от числа доступных CPU.
		max_threads <num_threads> # Ограничивает количество дополнительных потоков PHP, которые могут быть запущены во время выполнения. По умолчанию: num_threads. Может быть установлено в 'auto'.
		max_wait_time <duration> # Устанавливает максимальное время, в течение которого запрос может ожидать свободный поток PHP до истечения таймаута. По умолчанию: отключено.
		max_idle_time <duration> # Устанавливает максимальное время бездействия автоматически масштабируемого потока до его деактивации. По умолчанию: 5s.
		php_ini <key> <value> # Устанавливает директиву php.ini. Может использоваться несколько раз для установки нескольких директив.
		worker {
			file <path> # Устанавливает путь к worker-скрипту.
			num <num> # Устанавливает количество запускаемых потоков PHP, по умолчанию 2x от числа доступных CPU.
			env <key> <value> # Устанавливает дополнительную переменную окружения с заданным значением. Может быть указано несколько раз для нескольких переменных окружения.
			watch <path> # Устанавливает путь для отслеживания изменений файлов. Может быть указано несколько раз для нескольких путей.
			name <name> # Устанавливает имя worker, используемое в логах и метриках. По умолчанию: абсолютный путь к файлу worker.
			max_consecutive_failures <num> # Устанавливает максимальное количество последовательных сбоев, после которых worker считается неработоспособным; -1 означает, что worker всегда будет перезапускаться. По умолчанию: 6.
		}
	}
}

# ...

В качестве альтернативы можно использовать однострочную краткую форму для опции worker:

{
	frankenphp {
		worker <file> <num>
	}
}

# ...

Вы также можете определить несколько workers, если обслуживаете несколько приложений на одном сервере:

app.example.com {
    root /path/to/app/public
	php_server {
		root /path/to/app/public # позволяет лучше кэшировать
		worker index.php <num>
	}
}

other.example.com {
    root /path/to/other/public
	php_server {
		root /path/to/other/public
		worker index.php <num>
	}
}

# ...

Использование директивы php_server — это то, что нужно в большинстве случаев, но если требуется полный контроль, вы можете использовать более низкоуровневую директиву php. Директива php передает все входные данные PHP, не проверяя предварительно, является ли это PHP-файлом или нет. Подробнее об этом читайте на странице производительности.

Использование директивы php_server эквивалентно следующей конфигурации:

route {
	# Добавить слэш в конец запросов к директориям
	@canonicalPath {
		file {path}/index.php
		not path */
	}
	redir @canonicalPath {path}/ 308
	# Если запрошенный файл не существует, попытаться использовать файлы index
	@indexFiles file {
		try_files {path} {path}/index.php index.php
		split_path .php
	}
	rewrite @indexFiles {http.matchers.file.relative}
	# FrankenPHP!
	@phpFiles path *.php
	php @phpFiles
	file_server
}

Директивы php_server и php имеют следующие опции:

php_server [<matcher>] {
	root <directory> # Устанавливает корневую папку для сайта. По умолчанию: директива `root`.
	split_path <delim...> # Устанавливает подстроки для разделения URI на две части. Первая совпадающая подстрока будет использована для разделения "path info" от пути. Первая часть будет дополнена совпадающей подстрокой и будет считаться фактическим именем ресурса (CGI-скрипта). Вторая часть будет установлена как PATH_INFO для использования скриптом. По умолчанию: `.php`.
	resolve_root_symlink false # Отключает разрешение директории `root` до ее фактического значения путем оценки символической ссылки, если таковая существует (включено по умолчанию).
	env <key> <value> # Устанавливает дополнительную переменную окружения с заданным значением. Может быть указано несколько раз для нескольких переменных окружения.
	file_server off # Отключает встроенную директиву file_server.
	worker { # Создает worker, специфичный для этого сервера. Может быть указано несколько раз для нескольких workers.
		file <path> # Устанавливает путь к worker-скрипту, может быть относительным к корню php_server
		num <num> # Устанавливает количество запускаемых потоков PHP, по умолчанию 2x от числа доступных CPU.
		name <name> # Устанавливает имя для worker, используемое в логах и метриках. По умолчанию: абсолютный путь к файлу worker. Всегда начинается с m# при определении в блоке php_server.
		watch <path> # Устанавливает путь для отслеживания изменений файлов. Может быть указано несколько раз для нескольких путей.
		env <key> <value> # Устанавливает дополнительную переменную окружения с заданным значением. Может быть указано несколько раз для нескольких переменных окружения. Переменные окружения для этого worker также наследуются от родительского php_server, но могут быть переопределены здесь.
		match <path> # сопоставляет worker с шаблоном пути. Переопределяет try_files и может использоваться только в директиве php_server.
	}
	worker <other_file> <num> # Также можно использовать краткую форму, как и в глобальном блоке frankenphp.
}

Поскольку workers запускают ваше приложение только один раз и держат его в памяти, любые изменения в ваших PHP-файлах не будут отражены немедленно.

Вместо этого workers могут быть перезапущены при изменении файлов с помощью директивы watch. Это полезно для сред разработки.

{
	frankenphp {
		worker {
			file  /path/to/app/public/worker.php
			watch
		}
	}
}

Эта функция часто используется в сочетании с горячей перезагрузкой.

Если директория для watch не указана, по умолчанию будет использоваться ./**/*.{env,php,twig,yaml,yml}, который отслеживает все файлы с расширениями .env, .php, .twig, .yaml и .yml в директории и поддиректориях, где был запущен процесс FrankenPHP. Вы также можете указать одну или несколько директорий с использованием шаблона имён файлов оболочки:

{
	frankenphp {
		worker {
			file  /path/to/app/public/worker.php
			watch /path/to/app # отслеживает все файлы во всех поддиректориях /path/to/app
			watch /path/to/app/*.php # отслеживает файлы с расширением .php в /path/to/app
			watch /path/to/app/**/*.php # отслеживает PHP-файлы в /path/to/app и поддиректориях
			watch /path/to/app/**/*.{php,twig} # отслеживает PHP и Twig-файлы в /path/to/app и поддиректориях
		}
	}
}

• Шаблон ** указывает на рекурсивное отслеживание.
• Директории также могут быть относительными (к месту запуска процесса FrankenPHP).
• Если у вас определено несколько workers, все они будут перезапущены при изменении файлов.
• Будьте осторожны с отслеживанием файлов, создаваемых во время выполнения (например, логов), так как это может вызвать нежелательные перезапуски workers.

Механизм отслеживания файлов основан на e-dant/watcher.

В традиционных PHP-приложениях скрипты всегда размещаются в публичной директории. Это также верно для worker-скриптов, которые обрабатываются как любые другие PHP-скрипты. Если вы хотите разместить worker-скрипт вне публичной директории, вы можете сделать это с помощью директивы match.

Директива match является оптимизированной альтернативой try_files, доступной только внутри php_server и php. Следующий пример всегда будет обслуживать файл в публичной директории, если он присутствует, и в противном случае будет перенаправлять запрос worker, соответствующему шаблону пути.

{
	frankenphp {
		php_server {
			worker {
				file /path/to/worker.php # файл может находиться вне публичного пути
				match /api/* # все запросы, начинающиеся с /api/, будут обрабатываться этим worker
			}
		}
	}
}

Следующие переменные окружения могут быть использованы для внедрения директив Caddy в Caddyfile без его изменения:

• SERVER_NAME: изменение адресов для прослушивания; предоставленные хостнеймы также будут использованы для генерации TLS-сертификата
• SERVER_ROOT: изменение корневой директории сайта, по умолчанию public/
• CADDY_GLOBAL_OPTIONS: внедрение глобальных опций
• FRANKENPHP_CONFIG: внедрение конфигурации под директиву frankenphp

Как и для FPM и CLI SAPIs, переменные окружения по умолчанию доступны в суперглобальной переменной $_SERVER.

Значение S в директиве PHP variables_order всегда эквивалентно ES, независимо от того, где расположена E в этой директиве.

Для загрузки дополнительных конфигурационных файлов PHP можно использовать переменную окружения PHP_INI_SCAN_DIR. Если она установлена, PHP загрузит все файлы с расширением .ini, находящиеся в указанных директориях.

Вы также можете изменить конфигурацию PHP с помощью директивы php_ini в Caddyfile:

{
    frankenphp {
        php_ini memory_limit 256M

        # или

        php_ini {
            memory_limit 256M
            max_execution_time 15
        }
    }
}

По умолчанию FrankenPHP автоматически включает HTTPS для всех хостнеймов, включая localhost. Если вы хотите отключить HTTPS (например, в среде разработки), вы можете установить переменную окружения SERVER_NAME в http:// или :80:

В качестве альтернативы вы можете использовать все другие методы, описанные в документации Caddy.

Если вы хотите использовать HTTPS с IP-адресом 127.0.0.1 вместо хостнейма localhost, пожалуйста, ознакомьтесь с разделом известные проблемы.

При использовании HTTP/1.x может быть желательно включить режим полного дуплекса, чтобы разрешить запись ответа до завершения чтения всего тела запроса. (например: Mercure, WebSocket, Server-Sent Events и т.д.)

Это конфигурация, которую необходимо добавить в глобальные опции в Caddyfile:

{
  servers {
    enable_full_duplex
  }
}

Caution

Включение этой опции может привести к зависанию устаревших HTTP/1.x клиентов, которые не поддерживают полный дуплекс. Это также можно настроить с помощью переменной окружения CADDY_GLOBAL_OPTIONS:

CADDY_GLOBAL_OPTIONS="servers {
  enable_full_duplex
}"

Дополнительную информацию об этой настройке можно найти в документации Caddy.

При использовании Docker-образа установите переменную окружения CADDY_GLOBAL_OPTIONS в debug, чтобы включить режим отладки:

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

FrankenPHP предоставляет встроенную поддержку автодополнения команд для Bash, Zsh, Fish и PowerShell. Это позволяет автоматически завершать все команды (включая пользовательские команды, такие как php-server, php-cli и extension-init) и их флаги.

Для загрузки автодополнения в текущую сессию оболочки:

source <(frankenphp completion bash)

Для загрузки автодополнения для каждой новой сессии выполните:

Linux:

frankenphp completion bash > /usr/share/bash-completion/completions/frankenphp

macOS:

frankenphp completion bash > $(brew --prefix)/share/bash-completion/completions/frankenphp

Если автодополнение команд еще не включено в вашей среде, вам нужно будет его активировать. Вы можете выполнить следующее один раз:

echo "autoload -U compinit; compinit" >> ~/.zshrc

Чтобы загрузить автодополнение для каждой сессии, выполните один раз:

frankenphp completion zsh > "${fpath[1]}/_frankenphp"

Вам потребуется запустить новую оболочку, чтобы эти настройки вступили в силу.

Для загрузки автодополнения в текущую сессию оболочки:

frankenphp completion fish | source

Для загрузки автодополнения для каждой новой сессии выполните один раз:

frankenphp completion fish > ~/.config/fish/completions/frankenphp.fish

Для загрузки автодополнения в текущую сессию оболочки:

frankenphp completion powershell | Out-String | Invoke-Expression

Для загрузки автодополнения для каждой новой сессии выполните один раз:

frankenphp completion powershell | Out-File -FilePath (Join-Path (Split-Path $PROFILE) "frankenphp.ps1")
Add-Content -Path $PROFILE -Value '. (Join-Path (Split-Path $PROFILE) "frankenphp.ps1")'

Вам потребуется запустить новую оболочку, чтобы эти настройки вступили в силу.

Вам потребуется запустить новую оболочку, чтобы эти настройки вступили в силу.