PHPTime

Загрузка файлов на сервер в PHP: $_FILES и безопасность

При загрузке через HTML-форму PHP сохраняет содержимое файла во временный каталог и передаёт сведения о нём в $_FILES. Обработчик проверяет результат загрузки, выбирает допустимый формат и сохраняет файл под своим именем. Скачивание и работу с ZIP лучше вынести в отдельные обработчики со своими проверками.

Как файл попадает в $_FILES

Для обычной HTML-формы нужны метод POST, кодировка multipart/form-data и поле type="file" с именем. Если форма и обработчик находятся на одной странице, атрибут action можно опустить. Ключ в $_FILES совпадает с именем поля.

HTML
<form method="post" enctype="multipart/form-data">
  <label>Изображение JPEG или PNG
    <input type="file" name="photo" accept="image/jpeg,image/png" required>
  </label>
  <button type="submit">Загрузить</button>
</form>

Атрибуты accept и required помогают пользователю заполнить форму. Сервер проверяет запрос самостоятельно. Если форма использует авторизацию по cookie, добавьте CSRF-токен и проверяйте его перед сохранением файла.

  • error — код результата. Обработку файла начинают только при UPLOAD_ERR_OK.
  • tmp_name — путь к временному файлу на сервере. Если файл не переместить, PHP удалит его по завершении запроса.
  • size — размер в байтах, который PHP указывает для загруженного файла.
  • name и type — имя и MIME-тип, переданные клиентом. Имя можно сохранить для отображения, а тип следует определять по содержимому.
  • full_path, если он передан, — путь на стороне клиента. По нему нельзя строить путь на сервере.

Для name="photo[]" значения error, tmp_name и остальных полей становятся массивами. Обходите их по общему индексу и проверяйте каждый файл. Обработчик одиночного поля должен отклонять такую структуру.

Лимиты PHP и типичные ошибки загрузки

upload_max_filesize ограничивает один файл, а post_max_size — всё тело запроса, включая остальные поля и служебные границы multipart. Оставьте запас между этими значениями. При нескольких файлах учитывайте их суммарный размер и лимит max_file_uploads.

ini
file_uploads = On
upload_max_filesize = 5M
post_max_size = 8M
max_file_uploads = 1
СимптомЧто проверить
UPLOAD_ERR_INI_SIZEФайл превысил upload_max_filesize.
UPLOAD_ERR_FORM_SIZEПревышен предел из поля формы MAX_FILE_SIZE. Этот предел задаёт клиент, поэтому нужен и серверный лимит.
UPLOAD_ERR_PARTIAL или UPLOAD_ERR_NO_FILEФайл пришёл частично или пользователь его не выбрал. Запросите повторную загрузку.
UPLOAD_ERR_NO_TMP_DIR, UPLOAD_ERR_CANT_WRITE, UPLOAD_ERR_EXTENSIONПроверьте временный каталог, права записи, свободное место и журнал PHP. Последний код означает, что загрузку остановило расширение PHP.
Пустые $_FILES и $_POSTПроверьте метод и кодировку формы, а также post_max_size. При превышении общего лимита PHP может оставить оба массива пустыми, без кода ошибки для отдельного файла.
Ответ 413 до запуска скриптаПроверьте ограничение тела запроса на веб-сервере или прокси, через который идёт загрузка.

Правьте конфигурацию того окружения, которое обслуживает HTTP-запросы. PHP CLI и PHP-FPM могут читать разные файлы настроек. К моменту запуска обработчика PHP уже разобрал обычный multipart-запрос, поэтому правка лимитов внутри скрипта не поможет этому запросу.

Расширение файла в PHP и проверка MIME-типа

pathinfo($name, PATHINFO_EXTENSION) возвращает суффикс после последней точки. Например, для photo.backup.PNG результатом будет PNG. Если нужно сравнить суффикс с допустимыми значениями, приведите его к нижнему регистру. По имени файла невозможно установить, что внутри действительно изображение или архив.

Для определения MIME-типа по содержимому используйте finfo из расширения Fileinfo. Сопоставьте результат с явным списком форматов и берите расширение для хранения из этого списка. MIME-тип сам по себе не гарантирует, что изображение корректно декодируется. Если приложение меняет размеры или перекодирует изображения, ограничивайте ширину, высоту и число пикселей до декодирования и обрабатывайте ошибки библиотеки изображений.

Пример обработчика загрузки на PHP

Пусть оба обработчика лежат непосредственно в публичном каталоге, а каталог private-uploads создан рядом с ним и доступен PHP для записи и чтения. Пример связывает файлы с текущей сессией. Для постоянного личного кабинета храните идентификатор, формат и владельца файла в базе данных.

PHP
<?php

declare(strict_types=1);

function reject(int $status, string $message): never
{
    http_response_code($status);
    header('Content-Type: text/plain; charset=UTF-8');
    exit($message);
}

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    header('Allow: POST');
    reject(405, 'Используйте POST');
}

$file = $_FILES['photo'] ?? null;
if (!is_array($file) || !is_int($file['error'] ?? null)) {
    reject(400, 'Ожидается одно поле photo');
}

match ($file['error']) {
    UPLOAD_ERR_OK => null,
    UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_FORM_SIZE => reject(413, 'Файл слишком большой'),
    UPLOAD_ERR_PARTIAL => reject(400, 'Файл загружен частично'),
    UPLOAD_ERR_NO_FILE => reject(400, 'Выберите файл'),
    default => reject(500, 'Сервер не смог принять файл'),
};

$tmp = $file['tmp_name'] ?? null;
if (!is_string($tmp) || !is_uploaded_file($tmp)) {
    reject(400, 'Некорректная загрузка');
}

$size = filesize($tmp);
if ($size === false) {
    reject(500, 'Не удалось определить размер файла');
}
if ($size === 0) {
    reject(400, 'Файл пуст');
}
if ($size > 5 * 1024 * 1024) {
    reject(413, 'Допустимый размер — до 5 МиБ');
}

$mime = (new finfo(FILEINFO_MIME_TYPE))->file($tmp);
$extension = match ($mime) {
    'image/jpeg' => 'jpg',
    'image/png' => 'png',
    default => reject(415, 'Допустимы JPEG и PNG'),
};

if (!session_start()) {
    reject(500, 'Не удалось открыть сессию');
}
$id = bin2hex(random_bytes(16));
$path = dirname(__DIR__) . '/private-uploads/' . $id . '.' . $extension;

// Имя назначает сервер. PHP проверяет происхождение файла при перемещении.
if (!move_uploaded_file($tmp, $path)) {
    reject(500, 'Не удалось сохранить файл');
}

$_SESSION['uploads'][$id] = $extension;
http_response_code(201);
header('Content-Type: text/plain; charset=UTF-8');
echo $id;

is_uploaded_file() проверяет происхождение файла до чтения его содержимого. move_uploaded_file() выполняет собственную проверку и может перезаписать существующий файл назначения. Поэтому обработчик генерирует случайное имя для каждой загрузки. В приложении с постоянным хранилищем задайте квоты, срок хранения и очистку файлов, для которых не сохранилась запись о владельце.

Как скачать файл через PHP

Передавайте в обработчик идентификатор, например параметр id, и ищите файл только среди записей, доступных текущему пользователю или сессии. Идентификатор из запроса нельзя подставлять в путь без проверки формата и доступа. Заголовок Content-Disposition: attachment предлагает браузеру скачать файл, а fpassthru() передаёт его содержимое без загрузки всего файла в PHP-строку.

PHP
<?php

declare(strict_types=1);

if (!session_start(['read_and_close' => true])) {
    http_response_code(500);
    exit;
}

$id = $_GET['id'] ?? null;
if (!is_string($id) || preg_match('/\A[a-f0-9]{32}\z/', $id) !== 1) {
    http_response_code(404);
    exit;
}

$extension = $_SESSION['uploads'][$id] ?? null;
if (!in_array($extension, ['jpg', 'png'], true)) {
    http_response_code(404);
    exit;
}

$path = dirname(__DIR__) . '/private-uploads/' . $id . '.' . $extension;
// Файл мог быть удалён после загрузки. Возвращаем 404 без вывода пути.
$stream = @fopen($path, 'rb');
if ($stream === false) {
    http_response_code(404);
    exit;
}

header('Content-Type: application/octet-stream');
header('Content-Disposition: attachment; filename="photo.' . $extension . '"');
header('X-Content-Type-Options: nosniff');
header('Cache-Control: private, no-store');
fpassthru($stream);
fclose($stream);

Отправляйте заголовки до любого вывода. Пробелы перед открывающим тегом PHP, BOM и показ предупреждений могут испортить ответ. Если требуется сохранить исходное имя при скачивании, формируйте Content-Disposition с безопасным ASCII-именем и параметром filename* для UTF-8. Строку из $_FILES['photo']['name'] нельзя вставлять в заголовок напрямую.

ZIP в PHP: как читать загруженный архив

Класс ZipArchive доступен при включённом расширении zip. Проверяйте результат open() через === true: при ошибке метод может вернуть целочисленный код, который обычное логическое условие примет за успех.

Если нужен конкретный элемент, его можно прочитать из архива без распаковки на диск. Функция ниже принимает серверный путь к уже загруженному архиву и читает только manifest.json из его корня. Ограничение применяется к распакованному содержимому.

PHP
<?php

declare(strict_types=1);

function readZipManifest(string $path): string
{
    $zip = new ZipArchive();
    if ($zip->open($path, ZipArchive::RDONLY) !== true) {
        throw new RuntimeException('Не удалось открыть ZIP');
    }

    try {
        $limit = 64 * 1024;
        $entry = $zip->statName('manifest.json');
        if ($entry === false || $entry['size'] > $limit) {
            throw new RuntimeException('Манифест отсутствует или слишком велик');
        }

        // Читаем максимум на один байт больше допустимого размера.
        $data = $zip->getFromIndex($entry['index'], $limit + 1);
        if ($data === false || strlen($data) > $limit) {
            throw new RuntimeException('Не удалось прочитать манифест');
        }
        return $data;
    } finally {
        $zip->close();
    }
}

Если нужен JSON, разберите возвращённую строку через json_decode() с флагом JSON_THROW_ON_ERROR и проверьте ожидаемые поля. Для полной распаковки пользовательского ZIP ограничьте число записей, фактический объём распакованных данных и время обработки. Отклоняйте абсолютные пути, компоненты .. и символические ссылки. Пишите в отдельный закрытый каталог, проверяйте принадлежность каждого пути этому каталогу и очищайте частичный результат при отказе. Вложенные архивы обрабатывайте только при явной необходимости и с общими лимитами.

Что меняется в PHP 8.3–8.5

  • PHP 8.3. Для обычного POST с multipart/form-data используйте $_FILES. Встроенной функции request_parse_body() в этой ветке ещё нет. Для загрузок через PUT и PATCH используйте multipart-парсер фреймворка или принимайте загрузки через отдельный POST-маршрут.
  • PHP 8.4. Появилась request_parse_body(). Она возвращает два массива с полями и файлами и позволяет разбирать multipart для методов вроде PUT и PATCH. Вызывайте её до чтения php://input и обрабатывайте RequestParseBodyException. Повторно прочитать уже потреблённое тело запроса нельзя.
  • PHP 8.5. Для показанных обработчиков сохраняются те же API и схема. Обычная POST-форма работает через $_FILES, а ручной разбор тела доступен через request_parse_body().

declare(strict_types=1) помогает контролировать типы при вызовах функций. Структуру суперглобальных массивов всё равно нужно проверять явно. HTTP-клиент может прислать массив вместо ожидаемого поля, а часть ключей может отсутствовать.

Чек-лист перед запуском

  1. Проверьте форму, серверные лимиты и ответы на пустую, частичную и слишком большую загрузку.
  2. Принимайте файл только после проверки UPLOAD_ERR_OK, структуры поля, размера и допустимого формата.
  3. Генерируйте имя на сервере и сохраняйте файл вне публичного каталога через move_uploaded_file().
  4. Привязывайте файл к владельцу или сессии. Проверяйте доступ при каждом скачивании и выдавайте файл как вложение.
  5. Для ZIP ограничивайте распакованный объём. Если нужен один элемент, читайте его внутри архива.
  6. Проверьте доступность временного каталога и хранилища, квоты и удаление файлов по истечении срока хранения.

Частые вопросы

Почему после отправки формы массив $_FILES пуст?

Проверьте метод POST, кодировку multipart/form-data и имя поля. Если тело запроса превышает post_max_size, PHP может оставить пустыми и $_FILES, и $_POST. При ответе 413 до запуска PHP проверьте лимит веб-сервера или прокси.

Как получить расширение файла в PHP и проверить его?

Используйте pathinfo($name, PATHINFO_EXTENSION), чтобы получить суффикс имени. Проверяйте содержимое через finfo и список разрешённых MIME-типов. Расширение для хранения выбирайте по типу, который определил сервер.

Как скачать ZIP-файл через PHP?

Проверьте доступ к архиву по идентификатору, откройте его для чтения и передайте содержимое через fpassthru(). Укажите заголовок Content-Disposition со значением attachment и безопасным именем. Для выдачи готового архива открывать его через ZipArchive не требуется.

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

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

Интерфейсы, трейты и перечисления (enum) в PHP

Как применять interface, trait и enum в PHP 8.3–8.5: рабочие примеры, правила совместимости, разрешение конфликтов и разбор типичных ошибок.

9 мин

Исключения в PHP: try, catch, finally и свои классы ошибок

Как работают исключения в PHP 8.3–8.5: try, catch, finally и throw, перехват Exception и Error, собственные классы и типичные ошибки обработки.

9 мин

Как добавить и удалить элемент массива в PHP

Как добавить и удалить элемент массива в PHP 8, сохранить или переиндексировать ключи, получить первый и последний элементы с reset(), end() и без них.

8 мин

Как запустить PHP-файл: встроенный сервер, CLI и локальное окружение

Как создать и запустить PHP-файл из терминала или открыть его в браузере через localhost. Примеры для PHP 8.3–8.5, настройка сервера и разбор ошибок.

9 мин