Настройка php.ini: memory_limit, upload_max_filesize, таймауты
В php.ini задают ограничения памяти, размера загрузок и времени работы PHP. Чтобы изменение сработало, нужно найти конфигурацию нужного обработчика и согласовать её с настройками PHP-FPM и веб-сервера. Разберём это на примерах для PHP 8.3–8.5.
PHP ini: где находится активный php.ini
На одном сервере CLI, PHP-FPM и модуль PHP для Apache могут загружать разные конфигурации. Команда php --ini показывает основной файл и дополнительные INI-файлы для исполняемого файла PHP, который запускает оболочка. Для веб-приложения снимите показания через тот же сайт и пул PHP-FPM, где возникла проблема.
# Показывает конфигурацию PHP для командной строки.
php --ini<?php
declare(strict_types=1);
// Запустите через закрытый диагностический маршрут.
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
'sapi' => PHP_SAPI,
'ini' => php_ini_loaded_file(),
'scanned' => php_ini_scanned_files(),
'memory_limit' => ini_get('memory_limit'),
'upload_max_filesize' => ini_get('upload_max_filesize'),
'post_max_size' => ini_get('post_max_size'),
'max_execution_time' => ini_get('max_execution_time'),
], JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR);Дополнительные INI-файлы читаются после основного, в алфавитном порядке внутри каждого каталога сканирования. В PHP-FPM настройки могут переопределяться в конфигурации пула и в .user.ini. Последний применяется в CGI/FastCGI к директивам подходящего режима и кэшируется, поэтому результат правки может появиться с задержкой. Значение, заданное через php_admin_value в пуле, приложение через ini_set() изменить не может.
После правки основного INI-файла или конфигурации пула перечитайте конфигурацию PHP-FPM и сделайте новый HTTP-запрос. При работе PHP как модуля Apache перечитайте конфигурацию Apache. CLI загружает конфигурацию при новом запуске, поэтому давно работающий консольный воркер нужно перезапустить. Диагностический маршрут после проверки удалите.
PHP memory limit: сколько памяти дать скрипту
memory_limit ограничивает объём памяти, который скрипт может выделить через менеджер памяти PHP. Значение 256M означает 256 МиБ. Пиковый расход зависит от данных и способа обработки. Например, при преобразовании JSON в массив исходная строка и разобранная структура могут одновременно оставаться в памяти.
; Пример лимита для веб-приложения.
memory_limit = 256M<?php
declare(strict_types=1);
// Вызовите после ресурсоёмкой операции.
error_log(sprintf(
'Пик выделенной PHP памяти: %.1f МиБ',
memory_get_peak_usage(true) / (1024 ** 2)
));С аргументом true функция учитывает объём, выделенный менеджером памяти PHP у системы, включая пока не использованную часть. Для оценки ёмкости сервера измерьте также память процессов на уровне ОС под нагрузкой. Сопоставьте её с pm.max_children у PHP-FPM и оставьте запас для других служб. Повышение лимита с 256M до 512M только разрешает скрипту выделить больше памяти, но при одновременных тяжёлых запросах сервер должен выдержать этот расход.
Типичная ошибка — Allowed memory size of ... bytes exhausted. По журналу найдите операцию, на которой достигнут предел, и проверьте объём входных данных. Для больших выборок и импортов часто помогает обработка порциями, для файлов — потоковое чтение. Если задаче действительно нужна дополнительная память, задайте отдельный лимит для её запуска.
# Даёт одному запуску импорта свой лимит памяти.
php -d memory_limit=512M import.phpДля memory_limit значение -1 отключает лимит PHP. Ограничения ОС и контейнера продолжают действовать. В долгоживущем воркере следите за тем, как расход памяти меняется от задания к заданию.
PHP max: лимиты загрузки файлов и размера POST
При отправке формы multipart/form-data работают сразу несколько директив PHP с префиксом max. Размер одного файла, объём всего тела POST и количество файлов задаются отдельно.
| Директива | Что ограничивает | Пример |
|---|---|---|
upload_max_filesize | Размер одного загружаемого файла | 32M |
post_max_size | Размер всего тела POST с полями, файлами и служебными данными формы | 72M |
max_file_uploads | Количество файлов, принимаемых за один запрос | 2 |
max_input_vars | Количество входных переменных отдельно для GET, POST и COOKIE | 1000 |
; До двух файлов по 32 МиБ с запасом на поля и границы частей формы.
file_uploads = On
upload_max_filesize = 32M
post_max_size = 72M
max_file_uploads = 2Если перед PHP-FPM стоит Nginx, проверьте client_max_body_size в том блоке, который обслуживает загрузку. В примере лимиты Nginx и PHP на тело запроса одинаковы. Можно задать меньший предел в Nginx, чтобы отклонять слишком большие запросы до передачи в PHP.
# Добавьте в существующий блок server или location.
client_max_body_size 72m;Обычная загрузка через форму сохраняется во временный файл. Проверьте свободное место и доступность upload_tmp_dir для процесса PHP. Если приложение затем читает файл целиком, распаковывает архив или декодирует изображение, оцените пиковую память отдельно. Размер сжатого файла мало говорит о том, сколько памяти займут распакованные данные.
Почему загрузка даёт 413, пустой $_FILES или пропускает поля
- HTTP 413. Проверьте лимит тела запроса в Nginx или внешнем прокси. Если запрос отклонён на этом уровне, обработчик PHP не запускается.
$_POSTи$_FILESодновременно пусты. Такое бывает при превышенииpost_max_size. Сверьте размер тела в журнале илиContent-Length, если заголовок доступен. Проверьте также метод POST иenctype="multipart/form-data"у HTML-формы, имя поля иenable_post_data_reading.- Запись о файле есть, но
errorотличается отUPLOAD_ERR_OK.UPLOAD_ERR_INI_SIZEозначает превышениеupload_max_filesize,UPLOAD_ERR_PARTIAL— неполную загрузку,UPLOAD_ERR_NO_TMP_DIR— отсутствие временного каталога,UPLOAD_ERR_CANT_WRITE— сбой записи. - В большой форме пропадают последние поля. При превышении
max_input_varsPHP выдаёт предупреждение, а лишние переменные отбрасывает. Если пропадают файлы, отдельно проверьтеmax_file_uploads.
<?php
declare(strict_types=1);
// Обработчик одиночного поля document.
$file = $_FILES['document'] ?? null;
$error = $file['error'] ?? null;
if ($error === UPLOAD_ERR_INI_SIZE) {
http_response_code(413);
exit('Файл превышает допустимый размер');
}
if ($error !== UPLOAD_ERR_OK) {
http_response_code(400);
exit('Файл не получен');
}
// Дальше проверьте формат и перенесите файл через move_uploaded_file().Этот обработчик различает превышение лимита отдельного файла и отсутствие успешной загрузки. Чтобы при превышении лимита на всё тело клиент тоже получал 413, задайте предел на внешнем прокси или предусмотрите отдельную обработку в приложении. Вызов ini_set() внутри обработчика не увеличит доступный размер загрузки, поскольку разбор обычного POST происходит до запуска скрипта.
Таймауты PHP, PHP-FPM и Nginx
Разбор входных данных и выполнение скрипта
max_input_time задаёт время, которое PHP отводит на обработку входных данных до начала выполнения скрипта. Значение -1 берёт предел из max_execution_time. Этот таймаут следует отличать от ожидания данных клиента на веб-сервере. Например, Nginx с включённой буферизацией тела может принять загрузку до того, как передаст запрос PHP-FPM.
max_execution_time ограничивает время выполнения скрипта. На Unix-подобных системах время некоторых блокирующих операций, например ожидания потокового ввода-вывода, может не учитываться. На Windows учитывается реальное прошедшее время. В CLI значение по умолчанию равно 0, то есть лимит отключён. Вызов set_time_limit() запускает отсчёт заново, поэтому вызов внутри цикла способен постоянно отодвигать предел.
Время обработки в пуле и ожидание ответа
request_terminate_timeout в конфигурации пула PHP-FPM ограничивает время обслуживания запроса процессом. По истечении срока FPM может завершить этот процесс. В Nginx fastcgi_read_timeout задаёт допустимую паузу между последовательными чтениями ответа FastCGI. Аналогично client_body_timeout относится к паузам при чтении тела запроса от клиента. Оба значения Nginx задают интервалы между операциями чтения.
; php.ini
max_input_time = 30
max_execution_time = 45
; Конфигурация пула PHP-FPM, отдельный файл.
request_terminate_timeout = 60s# В блоке, передающем запросы в PHP-FPM.
fastcgi_read_timeout 70s;Пример оставляет PHP-FPM возможность завершить зависший запрос до истечения периода ожидания ответа в Nginx. При HTTP 504 сопоставьте журналы Nginx, PHP-FPM и внешнего прокси по тому же запросу. Если обработчик ждёт внешнее API, задайте таймаут подключения и таймаут запроса в HTTP-клиенте. Для долгого импорта, который может пережить HTTP-запрос, используйте фоновое задание и возвращайте клиенту его идентификатор.
Что отличается в PHP 8.3, 8.4 и 8.5
Базовая настройка памяти, POST-загрузок и таймаутов из примеров применяется в PHP 8.3–8.5. Разница важна, когда приложение принимает форму через PUT или PATCH. В PHP 8.3 такой запрос не заполняет $_POST и $_FILES автоматически. Если API уже принимает multipart через эти методы, разбор может выполнять используемый фреймворк. В PHP 8.4 появилась request_parse_body(), доступная и в PHP 8.5. Для форм она возвращает массивы полей и файлов и позволяет передавать отдельные лимиты разбора.
<?php
declare(strict_types=1);
// PHP 8.4–8.5. Для multipart-запроса PUT вызовите до чтения тела.
try {
[$fields, $files] = request_parse_body([
'post_max_size' => '12M',
'upload_max_filesize' => '10M',
'max_file_uploads' => 1,
]);
} catch (RequestParseBodyException) {
http_response_code(400);
exit('Не удалось разобрать форму');
}
// Проверьте error у нужного файла перед дальнейшей обработкой.Функция читает тело запроса однократно. Вызывайте её до чтения php://input и согласуйте лимиты с веб-сервером. Для обычной HTML-формы с POST продолжайте работать с $_POST и $_FILES. Для JSON используйте чтение php://input и json_decode() с JSON_THROW_ON_ERROR.
Чек-лист после изменения php.ini
- Проверьте версию PHP, SAPI, путь к основному
php.iniи дополнительные файлы в том же окружении, где работает приложение. - Согласуйте
upload_max_filesize,post_max_size, количество файлов и лимит тела запроса на прокси. Оставьте запас на поля формы. - Измерьте пиковую память на файле или выборке рабочего размера. Проверьте потребление памяти при нескольких параллельных запросах.
- Сверьте таймауты PHP, пула FPM, Nginx и внешних сервисов. Учитывайте, что у каждого таймаута свой интервал отсчёта.
- Перечитайте конфигурацию затронутых служб и повторно проверьте действующие значения через HTTP. Отправьте допустимый файл, файл больше лимита и запрос, у которого суммарное тело больше лимита. Сверьте ответы и журналы.
Частые вопросы
Почему php --ini показывает один файл, а сайт использует другие значения?
Команда показывает конфигурацию CLI. Сайт может обслуживаться другой версией PHP или отдельным пулом PHP-FPM. Проверьте php_ini_loaded_file(), php_ini_scanned_files() и ini_get() через закрытый HTTP-маршрут сайта.
Какой post_max_size нужен для двух файлов по 32 МиБ?
Задайте upload_max_filesize = 32M, max_file_uploads = 2 и, например, post_max_size = 72M. Запас нужен для полей и служебных данных multipart. Согласуйте с этим значением максимальный размер тела запроса на прокси.
Почему увеличение max_execution_time не устранило ошибку 504?
Ответ мог оборвать Nginx или внешний прокси. Проверьте fastcgi_read_timeout, таймауты внешнего прокси и request_terminate_timeout в пуле PHP-FPM, сопоставив записи в журналах по одному запросу.