frankenphp/docs/ru/config.md

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

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

В Docker-образах файл Caddyfile находится по пути /etc/frankenphp/Caddyfile. Статический бинарный файл будет искать Caddyfile в директории запуска.

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

PHP-интерпретатор будет искать в следующих местах:

Docker:

• 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 (.rpm или .deb):

• php.ini: /etc/frankenphp/php.ini По умолчанию предоставляется файл php.ini с производственными настройками.
• дополнительные файлы конфигурации: /etc/frankenphp/php.d/*.ini
• расширения php: /usr/lib/frankenphp/modules/

Статический бинарный файл:

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

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

Для настройки FrankenPHP установите глобальную опцию frankenphp. После этого можно использовать HTTP-директивы php_server или php для обработки вашего PHP-приложения.

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

{
	# Включить FrankenPHP
	frankenphp
}

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

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

{
	frankenphp {
		num_threads <num_threads> # Указывает количество потоков PHP. По умолчанию: 2x от числа доступных CPU.
		worker {
			file <path> # Указывает путь к worker-скрипту.
			num <num> # Указывает количество потоков PHP. По умолчанию: 2x от числа доступных CPU.
			env <key> <value> # Устанавливает дополнительную переменную окружения. Можно указать несколько раз для разных переменных.
			watch <path> # Указывает путь для отслеживания изменений файлов.Можно указать несколько раз для разных путей.
		}
	}
}

# ...

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

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

# ...

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

{
	frankenphp {
		worker /path/to/app/public/index.php <num>
		worker /path/to/other/public/index.php <num>
	}
}

app.example.com {
	root /path/to/app/public
	php_server
}

other.example.com {
	root /path/to/other/public
	php_server
}

# ...

Использование директивы php_server — это то, что нужно в большинстве случаев. Однако если требуется полный контроль, вы можете использовать более низкоуровневую директиву 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 на две части. Первая часть будет использована как имя ресурса (CGI-скрипта), вторая часть — как PATH_INFO. По умолчанию: `.php`.
	resolve_root_symlink false # Отключает разрешение символьных ссылок для `root` (включено по умолчанию).
	env <key> <value> # Устанавливает дополнительные переменные окружения. Можно указать несколько раз для разных переменных.
	file_server off # Отключает встроенную директиву file_server.
}

Отслеживание изменений файлов

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

Для разработки можно настроить перезапуск workers при изменении файлов с помощью директивы watch:

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

Если директория для watch не указана, по умолчанию будет использоваться путь ./**/*.{php,yaml,yml,twig,env}, который отслеживает все файлы с расширениями .php, .yaml, .yml, .twig и .env в директории, где был запущен процесс 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, все они будут перезапущены при изменении файлов.
• Избегайте отслеживания файлов, создаваемых во время выполнения (например, логов), так как это может вызвать нежелательные перезапуски.

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

Полный дуплекс (HTTP/1)

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

Эта опция включается вручную и должна быть добавлена в глобальные настройки Caddyfile:

{
  servers {
    enable_full_duplex
  }
}

Caution

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

CADDY_GLOBAL_OPTIONS="servers {
  enable_full_duplex
}"

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

Переменные окружения

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

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

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

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

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

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

Включение режима отладки

При использовании 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