PHPTime

Настройка 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, где возникла проблема.

Shell
# Показывает конфигурацию PHP для командной строки.
php --ini
PHP
<?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 в массив исходная строка и разобранная структура могут одновременно оставаться в памяти.

ini
; Пример лимита для веб-приложения.
memory_limit = 256M
PHP
<?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. По журналу найдите операцию, на которой достигнут предел, и проверьте объём входных данных. Для больших выборок и импортов часто помогает обработка порциями, для файлов — потоковое чтение. Если задаче действительно нужна дополнительная память, задайте отдельный лимит для её запуска.

Shell
# Даёт одному запуску импорта свой лимит памяти.
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 и COOKIE1000
ini
; До двух файлов по 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.

nginx
# Добавьте в существующий блок 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_vars PHP выдаёт предупреждение, а лишние переменные отбрасывает. Если пропадают файлы, отдельно проверьте max_file_uploads.
PHP
<?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 задают интервалы между операциями чтения.

ini
; php.ini
max_input_time = 30
max_execution_time = 45

; Конфигурация пула PHP-FPM, отдельный файл.
request_terminate_timeout = 60s
nginx
# В блоке, передающем запросы в 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
<?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

  1. Проверьте версию PHP, SAPI, путь к основному php.ini и дополнительные файлы в том же окружении, где работает приложение.
  2. Согласуйте upload_max_filesize, post_max_size, количество файлов и лимит тела запроса на прокси. Оставьте запас на поля формы.
  3. Измерьте пиковую память на файле или выборке рабочего размера. Проверьте потребление памяти при нескольких параллельных запросах.
  4. Сверьте таймауты PHP, пула FPM, Nginx и внешних сервисов. Учитывайте, что у каждого таймаута свой интервал отсчёта.
  5. Перечитайте конфигурацию затронутых служб и повторно проверьте действующие значения через 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, сопоставив записи в журналах по одному запросу.

Справка по теме

Ещё в разделе «Справочник PHP»

Обработка форм в PHP: $_GET, $_POST, валидация и защита

Как обработать HTML-форму в PHP 8.3–8.5: выбрать GET или POST, прочитать php://input, проверить поля, экранировать HTML и защитить запрос от CSRF.

10 мин

Операторы PHP: сравнение, ??, ?->, тернарный оператор и match

Операторы и условия PHP 8.3–8.5 на коротких примерах. Как работают сравнение, не равно, ??, ?->, тернарный оператор, if else, switch case и match.

9 мин

Отладка PHP: var_dump, Xdebug и PhpStorm

Практическая отладка PHP 8.3–8.5: проверка данных через var_dump, настройка Xdebug в PhpStorm и VS Code, точки останова и разбор ошибок подключения.

9 мин

Отправка почты из PHP: mail(), PHPMailer и Symfony Mailer

Как отправить письмо из PHP 8.3–8.5 через mail(), PHPMailer и Symfony Mailer. Рабочие примеры, настройка SMTP, UTF-8 и разбор ошибок доставки.

9 мин