PHP: полный мануал с примерами, функциями и ООП

Выбрать фотографию и понять, где она окажется

Посетитель прикладывает фотографию сломанной дрели к заявке. Нужно получить реальные байты изображения, проверить ограничения и сохранить файл для сотрудника. Поле с локальным путём C:\Pictures\drill.jpg само по себе не даёт PHP доступа к диску посетителя: браузер должен передать файл.

Сначала разберите обычную форму. У файловой формы три обязательных части: method="post", enctype="multipart/form-data" и input type="file" с name. enctype задаёт формат тела с отдельными частями для полей и файла. Например name="photo" создаёт ключ $_FILES["photo"], а не $_POST["photo"].

Без переноса временный upload обычно исчезает после запроса. move_uploaded_file проверяет, что исходник получен PHP через HTTP POST upload, и переносит его; rename такой проверки происхождения не делает. Ни одна из этих функций не доказывает, что файл — безопасная фотография. Это различие отвечает на реальный вопрос о move_uploaded_file.

Сначала разобрать результат приёма, затем читать файл

После error проверяем ожидаемую форму массива: посетитель может отправить photo[] и получить вложенные значения вместо одного файла. Неотмеченный файловый выбор и полное отсутствие ключа — разные ситуации. На уровне прокси задают ограничение размера запроса; post_max_size должен вмещать файл и служебные части multipart. Превышение общего POST-лимита может обнулить $_POST и $_FILES ещё до нашего обработчика.

Следующий обработчик принимает только один PNG/JPEG до 100 КиБ. finfo_file определяет MIME по данным файла с помощью расширения Fileinfo; расширение для хранения выбираем из своей карты. Это первичная сортировка для закрытого хранилища проверки. Картинка пока не выдаётся посетителям и не декодируется графической библиотекой. Для публичных изображений нужны отдельный проверенный этап обработки, пределы размеров/декодирования и безопасная выдача.

Передать настоящий PNG и сохранить его вне публичного каталога

Распакуйте ZIP в новую папку. public/index.php подключает example.php, storage существует рядом с public. Запуск: php -d display_errors=0 -d log_errors=1 -S 127.0.0.1:8080 -t public. Откройте /index.php, выберите небольшой PNG и нажмите «Передать фотографию». Нужны сессии, Fileinfo, file_uploads=On и доступный PHP временный каталог.

Токен сессии здесь работает так же, как в форме заявки. Новые действия: is_uploaded_file подтверждает происхождение tmp_name; filesize читает фактический размер; finfo_open создаёт анализатор, finfo_file возвращает MIME. Массив extensions разрешает только два формата. random_bytes и bin2hex дают своё имя; move_uploaded_file возвращает true либо false. Ветвь успеха появляется только после true.

<?php
session_start(['use_strict_mode' => true, 'cookie_httponly' => true, 'cookie_samesite' => 'Lax']);
$_SESSION['csrf'] ??= bin2hex(random_bytes(32));
header('Content-Type: text/html; charset=utf-8');
header('Cache-Control: no-store');
$message = 'Выберите PNG или JPEG размером до 100 КиБ.';
if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    $token = $_POST['csrf'] ?? null;
    $file = $_FILES['photo'] ?? null;
    if (!is_string($token) || !hash_equals($_SESSION['csrf'], $token)) {
        http_response_code(403);
        $message = 'Обновите форму и попробуйте снова.';
    } elseif (!is_array($file) || !is_int($file['error'] ?? null)) {
        http_response_code(422);
        $message = 'Отправьте один файл через поле фотографии.';
    } elseif ($file['error'] === UPLOAD_ERR_NO_FILE) {
        http_response_code(422);
        $message = 'Сначала выберите фотографию.';
    } elseif ($file['error'] !== UPLOAD_ERR_OK) {
        http_response_code(422);
        $message = 'Файл не получен полностью или превышает лимит сервера.';
    } elseif (!is_string($file['tmp_name'] ?? null) || !is_uploaded_file($file['tmp_name'])) {
        http_response_code(422);
        $message = 'Не удалось подтвердить получение файла.';
    } else {
        $path = $file['tmp_name'];
        $size = filesize($path);
        $mime = finfo_file(finfo_open(FILEINFO_MIME_TYPE), $path);
        $extensions = ['image/png' => 'png', 'image/jpeg' => 'jpg'];
        if ($size === false || $size < 1 || $size > 102400 || !isset($extensions[$mime])) {
            http_response_code(422);
            $message = 'Нужен PNG или JPEG размером от 1 байта до 100 КиБ.';
        } else {
            $id = bin2hex(random_bytes(16));
            $destination = __DIR__ . '/storage/' . $id . '.' . $extensions[$mime];
            if (!move_uploaded_file($path, $destination)) {
                http_response_code(503);
                $message = 'Сейчас не удалось сохранить фотографию. Попробуйте позже.';
            } else {
                $message = 'Фотография получена и сохранена для проверки.';
            }
        }
    }
} elseif ($_SERVER['REQUEST_METHOD'] !== 'GET') {
    http_response_code(405);
    header('Allow: GET, POST');
    exit('Допустимы GET и POST.');
}
?>
<!doctype html><html lang="ru"><meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Фотография для заявки</title><h1>Фотография для заявки</h1>
<p role="status"><?= htmlspecialchars($message, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8') ?></p>
<form action="/index.php" method="post" enctype="multipart/form-data">
<input type="hidden" name="csrf" value="<?= $_SESSION['csrf'] ?>">
<p><label for="photo">PNG или JPEG, до 100 КиБ</label>
<input id="photo" name="photo" type="file" accept="image/png,image/jpeg" required style="max-width:100%"></p>
<button type="submit">Передать фотографию</button></form></html>

Для публичной системы добавляют привязку вложения к заявке/владельцу, права доступа, квоты и срок хранения, ограничение частоты и при необходимости проверку содержимого. CSRF сам не аутентифицирует отправителя. Ни accept в HTML, ни расширение имени, ни MIME от клиента не заменяют серверные правила. Далее сохранённые справочные разделы развивают множественную загрузку, ограничения сервера и безопасную выдачу.

Файл проходит собственный конвейер

В магазине менеджер загружает фотографию товара, клиент — документ на возврат, интеграция — CSV с остатками. Эти файлы требуют разных правил. Для фотографии разумно разрешить несколько растровых форматов и выполнить контролируемое декодирование с ограничением размеров. Документ можно хранить как скачиваемое вложение, не исполняя и не открывая его на основном домене. SVG и HTML содержат активный контент; разрешать их как обычный аватар опасно.

Сначала нужны аутентификация, полномочие на объект, CSRF и лимит частоты. Размер ограничивают в прокси/веб-сервере, post_max_size, upload_max_filesize и прикладной политике. Если превысить общий POST-лимит, $_POST и $_FILES могут быть пустыми; это не означает, что пользователь просто забыл выбрать файл. Согласуйте лимиты и понятный ответ 413. Атрибут accept помогает диалогу выбора, но не серверу.

$_FILES содержит error, tmp_name, size, name и type. Форму массива тоже проверяют: неожиданные вложенные значения не должны попадать в файловые функции. Затем проверяют UPLOAD_ERR_OK и фактический размер временного файла. Клиентские name и type не используют для принятия решения. Определение MIME через Fileinfo — один слой, а не доказательство безвредности содержимого.

Получаем только ожидаемую структуру

После работающего приёма картинки выделим уже знакомую проверку error в отдельную функцию. Значение null в её ответе означает «ошибки приёма нет»; строки choose-file/incomplete — внутренние коды, которые интерфейс переведёт человеку. match выбирает код по константе UPLOAD_ERR_*, default описывает оставшиеся отказы. Это небольшая проверка одного слоя, она не заменяет multipart-проект выше.

<?php
declare(strict_types=1);

function uploadProblem(array $file): ?string {
    if (!isset($file['error']) || !is_int($file['error'])) return 'bad-shape';
    return match ($file['error']) {
        UPLOAD_ERR_OK => null,
        UPLOAD_ERR_NO_FILE => 'choose-file',
        UPLOAD_ERR_INI_SIZE, UPLOAD_ERR_FORM_SIZE => 'too-large',
        UPLOAD_ERR_PARTIAL => 'incomplete',
        default => 'storage-unavailable',
    };
}
foreach ([['error'=>UPLOAD_ERR_OK],['error'=>UPLOAD_ERR_PARTIAL],['error'=>[]]] as $file) {
    echo uploadProblem($file) ?? 'continue';
    echo "
";
}

continue
incomplete
bad-shape

Случайное имя и каталог вне public

Новое требование — принимать PDF и вернуть его внутреннее имя вызывающему коду. storePdf получает метаданные одного файла и закрытый каталог, а возвращает строку имени. throw сообщает вызывающему коду об отказе вместо ложного имени. Запись (new finfo(FILEINFO_MIME_TYPE))->file(...) — объектный вариант знакомых finfo_open/finfo_file: создаём анализатор и вызываем его метод file. DIRECTORY_SEPARATOR задаёт разделитель пути платформы; 5_000_000 — целое 5000000 с разделителями для чтения. Ниже контекстная функция, которую HTTP-контроллер вызывает после метода, CSRF и проверки доступа.

<?php
declare(strict_types=1);

function storePdf(array $file, string $privateDirectory): string {
    if (($file['error'] ?? null) !== UPLOAD_ERR_OK
        || !is_string($file['tmp_name'] ?? null)
        || !is_uploaded_file($file['tmp_name'])) {
        throw new InvalidArgumentException('Invalid upload');
    }
    $size = filesize($file['tmp_name']);
    if ($size === false || $size < 1 || $size > 5_000_000) {
        throw new InvalidArgumentException('File size rejected');
    }
    $mime = (new finfo(FILEINFO_MIME_TYPE))->file($file['tmp_name']);
    if ($mime !== 'application/pdf') throw new InvalidArgumentException('Expected PDF');
    $name = bin2hex(random_bytes(24)).'.pdf';
    $path = $privateDirectory.DIRECTORY_SEPARATOR.$name;
    if (file_exists($path) || !move_uploaded_file($file['tmp_name'], $path)) {
        throw new RuntimeException('Cannot store upload');
    }
    return $name;
}

Не подставляйте исходное имя в путь. Последовательности ../, разделители, одинаковые имена и различия регистров файловых систем создают ошибки и уязвимости. Исходное имя можно хранить как метаданные, а физический ключ генерировать случайно. move_uploaded_file дополнительно проверяет происхождение источника как HTTP-upload; обычный rename этого не делает. При этом функция может перезаписать существующее назначение, поэтому проектируйте уникальность и приватность хранилища.

База хранит владельца, тип, размер, состояние проверки и физический ключ. Если файл сохранён, а вставка метаданных не удалась, его нужно удалить либо подобрать фоновым уборщиком сирот. Обратная последовательность требует состояния pending. Файловая система и SQL не составляют общую транзакцию, поэтому приходится явно проектировать восстановление после сбоя.

Выдача — отдельное авторизованное действие

Закрытый файл отдаёт контроллер, который проверяет пользователя и принадлежность вложения, выбирает путь только из доверенных метаданных и задаёт Content-Type, Content-Disposition и X-Content-Type-Options: nosniff. Для документов предпочтительна загрузка attachment. Имя в Content-Disposition требует безопасного формирования: нельзя вставлять сырые кавычки и переводы строк. Большие файлы лучше передавать веб-серверу через контролируемый внутренний механизм после авторизации, чтобы не занимать PHP-воркер долгой отдачей.

Для картинок ограничьте не только байты, но и ширину, высоту, число пикселей и ресурсы декодера. Маленький сжатый файл может требовать много памяти после распаковки. Перекодирование снимает часть риска и метаданные, но библиотека обработки тоже нуждается в обновлениях и лимитах. Проверки ZIP требуют защиты от выхода путей за каталог, симлинков и чрезмерной распаковки. Автоматически распаковывать любой архив из формы нельзя.

Тестируйте пустой файл, обрыв загрузки, запрещённое расширение с разрешённым MIME, подменённый MIME, огромные размеры изображения и скачивание чужого документа. Время антивирусной проверки и перекодирования измеряют отдельно; если оно велико, интерфейс показывает состояние «проверяется», а работа уходит в очередь.

Карантин, квоты и восстановление после сбоя

Хранилище должно учитывать общую квоту пользователя, а не только размер одного файла. Сто разрешённых файлов по пять мегабайт тоже способны заполнить диск. Проверка квоты до записи подвержена гонке двух загрузок; резервирование места или атомарный учёт в базе решают её надёжнее, чем доверие одному предварительному SELECT. Учитывайте и временные файлы во время приёма.

Состояния pending, scanning, ready и rejected делают процесс понятным человеку. Пока проверка не завершилась, файл не выдаётся как готовый. Если сканер недоступен, выбирают явное отложенное состояние, а не автоматически принимают документ. Отказ объясняют без раскрытия внутренних путей; исходное имя можно показать только после HTML-экранирования.

Фоновая уборка должна удалять только объекты, отмеченные вашей моделью как сироты или истёкшие временные загрузки. Нельзя рекурсивно очищать путь, вычисленный из клиентского имени. Для каждого удаления сверяйте корень хранилища и ожидаемый ключ. Полезный отказной тест останавливает процесс после сохранения файла, но до записи метаданных, затем проверяет, что механизм восстановления не удаляет чужие успешные вложения.

Практика: проверьте решение, а не только успешный путь

Нужно принимать аватары JPEG/PNG. Почему проверки размера и finfo недостаточно?