is_uploaded_file()

Функция is_uploaded_file() проверяет, был ли указанный файл загружен через HTTP POST запрос. Это один из основных инструментов безопасности PHP при работе с загрузкой файлов: она позволяет убедиться, что путь действительно указывает на временный файл, созданный самим PHP из текущего запроса, а не на произвольный путь, который злоумышленник мог подставить в ваш скрипт.

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

Синтаксис

is_uploaded_file(string $filename): bool

• $filename — путь для проверки. На практике это всегда значение, взятое из $_FILES['...']['tmp_name'].
• Возвращаемое значение — true, если $filename является загруженным файлом из текущего запроса, иначе false.

Функция возвращает true только для временного имени файла, назначенного PHP во время загрузки. Передача пути, который вы сформировали самостоятельно (например, конечного места назначения после перемещения файла), вернёт false.

Базовый пример

<?php

$file = $_FILES['file']['tmp_name'];

if (is_uploaded_file($file)) {
    echo 'The file was uploaded via HTTP POST.';
} else {
    echo 'The file was NOT uploaded via HTTP POST.';
}

Здесь $_FILES['file'] — это запись, создаваемая при отправке поля формы с именем file и атрибутом enctype="multipart/form-data". Ключ tmp_name содержит временный путь на стороне сервера, а is_uploaded_file() проверяет, что файл действительно поступил из запроса.

Зачем нужна эта функция (безопасность)

Без этой проверки злоумышленник мог бы отправить обычное поле формы (не файл), значение которого является серверным путём, например /etc/passwd. Если бы ваш код слепо доверял этой строке и затем читал или копировал её, вы бы раскрыли системные файлы. is_uploaded_file() защищает от этого, возвращая true только для файлов, которые PHP сам получил как загрузки в текущем запросе.

Безопасный обработчик загрузки проверяет файл перед любыми действиями с ним:

<?php

if (
    isset($_FILES['file']) &&
    $_FILES['file']['error'] === UPLOAD_ERR_OK &&
    is_uploaded_file($_FILES['file']['tmp_name'])
) {
    $destination = __DIR__ . '/uploads/' . basename($_FILES['file']['name']);

    if (move_uploaded_file($_FILES['file']['tmp_name'], $destination)) {
        echo 'File stored safely.';
    } else {
        echo 'Failed to move the uploaded file.';
    }
} else {
    echo 'No valid upload received.';
}

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

is_uploaded_file() и move_uploaded_file()

Типичные ошибки

• Всегда передавайте tmp_name, но не конечный путь. После перемещения файла с помощью move_uploaded_file() временный файл больше не существует, поэтому повторная проверка вернёт false.
• Проверка актуальна только для текущего запроса. Путь, который был загрузкой в предыдущем запросе, не считается действительным в текущем.
• Функция не валидирует содержимое. is_uploaded_file() ничего не говорит о типе или размере файла. Отдельно проверяйте $_FILES['file']['size'], MIME-тип и расширение перед тем, как доверять пользовательским данным.
• Сначала проверяйте код ошибки. Проверяйте $_FILES['file']['error'] === UPLOAD_ERR_OK перед вызовом is_uploaded_file(); при неудачной загрузке tmp_name может оказаться пустым.

Связанные функции

• move_uploaded_file() — безопасное перемещение загруженного файла в место назначения.
• $_FILES и другие суперглобальные переменные — как данные загруженного файла передаются вашему скрипту.
• Загрузка файлов в PHP — полная HTML-форма и PHP-обработчик для принятия файлов.

Итоги

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

Практика