rzaripov.kz

Создание загрузчика файлов на PHP с прогресс-баром

Загрузка файлов через веб-форму кажется простой задачей, пока размер данных не начинает измеряться десятками или сотнями мегабайт. Обычная отправка формы не показывает пользователю, сколько уже передано и сколько осталось. Если соединение медленное, страница выглядит зависшей, а повторная отправка файла становится практически неизбежной.

Связка PHP, HTML и JavaScript позволяет создать удобный загрузчик с визуальным индикатором прогресса. Браузер передаёт файл асинхронно, сервер принимает его во временное хранилище, проверяет параметры и перемещает в нужный каталог. При этом JavaScript получает события передачи данных и обновляет шкалу выполнения без перезагрузки страницы.

Такой подход подходит для личных кабинетов, систем обмена документами, административных панелей и внутренних сервисов. В небольшом проекте достаточно XMLHttpRequest и стандартного механизма $_FILES, а для крупных объектов пригодится загрузка частями с возможностью продолжить прерванную передачу.

Ниже рассмотрен практический вариант с PHP 8, формой выбора файла, прогресс-баром, проверкой расширения и ограничением размера. Отдельное внимание уделено настройкам сервера и защите каталога, поскольку обработка пользовательских файлов требует более строгих мер, чем обычная отправка текстовых данных.

Разметка формы и индикатора передачи

Форма должна использовать метод POST и тип содержимого multipart/form-data. Именно этот формат позволяет передать бинарный файл вместе с дополнительными полями. Атрибут id понадобится JavaScript для поиска формы и подключения обработчика события отправки.

<form id="uploadForm" enctype="multipart/form-data">
    <input type="file" id="fileInput" name="file" required>
    <button type="submit">Загрузить файл</button>
</form>

<div class="progress-wrapper" aria-live="polite">
    <div id="progressBar" class="progress-bar">0%</div>
</div>

<p id="uploadStatus"></p>

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

.progress-wrapper {
    width: 100%;
    max-width: 520px;
    height: 24px;
    margin-top: 16px;
    background: #e5e7eb;
    border-radius: 5px;
    overflow: hidden;
}

.progress-bar {
    width: 0;
    height: 100%;
    color: #fff;
    background: #2563eb;
    text-align: center;
    line-height: 24px;
    transition: width .15s ease;
}

Передача файла через XMLHttpRequest

Для отслеживания отправки используется объект XMLHttpRequest. Его свойство upload содержит события, связанные именно с передачей файла на сервер. Событие progress передаёт количество отправленных байтов и общий размер объекта.

const form = document.getElementById('uploadForm');
const fileInput = document.getElementById('fileInput');
const progressBar = document.getElementById('progressBar');
const status = document.getElementById('uploadStatus');

form.addEventListener('submit', function (event) {
    event.preventDefault();

    const file = fileInput.files[0];

    if (!file) {
        status.textContent = 'Выберите файл для загрузки';
        return;
    }

    const data = new FormData();
    data.append('file', file);

    const request = new XMLHttpRequest();
    request.open('POST', 'upload.php');

    request.upload.addEventListener('progress', function (event) {
        if (event.lengthComputable) {
            const percent = Math.round(event.loaded / event.total * 100);
            progressBar.style.width = percent + '%';
            progressBar.textContent = percent + '%';
        }
    });

    request.addEventListener('load', function () {
        const result = JSON.parse(request.responseText);
        status.textContent = result.message;

        if (result.success) {
            progressBar.classList.add('success');
        }
    });

    request.addEventListener('error', function () {
        status.textContent = 'Ошибка соединения с сервером';
    });

    request.send(data);
});

Проверка event.lengthComputable обязательна: некоторые браузеры или промежуточные прокси не сообщают полный размер передачи. Ответ сервера желательно возвращать в JSON, чтобы клиент мог единообразно обработать успешный результат и ошибку.

Обработка загрузки на стороне PHP

PHP получает файл в массиве $_FILES. В нём находятся исходное имя, временный путь, размер, MIME-тип и код ошибки. Нельзя доверять имени и типу, пришедшим от браузера: эти значения используются только как исходные данные для последующей проверки.

<?php

header('Content-Type: application/json; charset=utf-8');

function response(bool $success, string $message): never
{
    echo json_encode(
        [
            'success' => $success,
            'message' => $message
        ],
        JSON_UNESCAPED_UNICODE
    );

    exit;
}

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    response(false, 'Недопустимый метод запроса');
}

if (!isset($_FILES['file'])) {
    response(false, 'Файл не передан');
}

$file = $_FILES['file'];

if ($file['error'] !== UPLOAD_ERR_OK) {
    response(false, 'Ошибка загрузки: код ' . $file['error']);
}

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

$maxSize = 20 * 1024 * 1024;

if ($file['size'] > $maxSize) {
    response(false, 'Размер файла превышает 20 МБ');
}

$allowedExtensions = ['jpg', 'jpeg', 'png', 'pdf', 'zip'];
$extension = strtolower(
    pathinfo($file['name'], PATHINFO_EXTENSION)
);

if (!in_array($extension, $allowedExtensions, true)) {
    response(false, 'Этот тип файла запрещён');
}

Безопасное имя и сохранение файла

Исходное имя файла не следует использовать напрямую. В нём могут содержаться специальные символы, управляющие последовательности или попытки выхода из каталога через ../. Безопаснее создать новое имя на основе случайного идентификатора, сохранив только проверенное расширение.

$uploadDirectory = __DIR__ . '/storage/';

if (!is_dir($uploadDirectory) &&
    !mkdir($uploadDirectory, 0750, true)) {
    response(false, 'Не удалось создать каталог');
}

$newName = bin2hex(random_bytes(16)) . '.' . $extension;
$destination = $uploadDirectory . $newName;

if (!is_uploaded_file($file['tmp_name'])) {
    response(false, 'Некорректный источник файла');
}

if (!move_uploaded_file($file['tmp_name'], $destination)) {
    response(false, 'Не удалось сохранить файл');
}

response(true, 'Файл успешно загружен');

Для изображений, архивов и документов полезно дополнительно проверять реальный MIME-тип через finfo_file, а не полагаться на значение $_FILES['type']. Если каталог доступен из интернета, исполняемые расширения нужно запретить на уровне веб-сервера. В Apache для каталога загрузок можно отключить выполнение PHP-скриптов через конфигурацию или файл .htaccess.

Настройки PHP и веб-сервера

Даже корректный код не примет большой файл, если серверные лимиты меньше его размера. Основные параметры находятся в php.ini: upload_max_filesize ограничивает один файл, а post_max_size — весь POST-запрос. Второй параметр должен быть немного больше первого, чтобы учесть служебные данные формы.

upload_max_filesize = 20M
post_max_size = 25M
max_file_uploads = 5
max_execution_time = 120
max_input_time = 120

После изменения php.ini обычно требуется перезапустить PHP-FPM или веб-сервер. В конфигурации Nginx также может действовать ограничение client_max_body_size, а прокси и балансировщики способны иметь собственные лимиты. Если сервер отвечает ошибкой 413, причина часто находится именно в настройках веб-сервера, а не в PHP.

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

Улучшение интерфейса загрузчика

Хороший прогресс-бар должен показывать не только процент, но и состояние операции. Во время передачи кнопку отправки можно отключить, чтобы пользователь случайно не создал несколько одинаковых запросов. После завершения стоит очистить поле выбора и вернуть индикатор в исходное состояние при следующей загрузке.

request.addEventListener('load', function () {
    let result;

    try {
        result = JSON.parse(request.responseText);
    } catch {
        status.textContent = 'Сервер вернул некорректный ответ';
        return;
    }

    status.textContent = result.message;
    form.querySelector('button').disabled = false;
});

form.addEventListener('submit', function () {
    form.querySelector('button').disabled = true;
    status.textContent = 'Идёт передача файла...';
});

Для доступности интерфейса полезно добавить aria-live, понятные сообщения об ошибках и текстовый процент рядом с графической полосой. На мобильных устройствах кнопка и поле выбора должны оставаться удобными для нажатия, а ширина индикатора — адаптироваться к экрану.

Если сервер возвращает идентификатор загруженного объекта, клиент может сразу вывести ссылку на него или обновить список документов. Для нескольких файлов можно обрабатывать элементы массива по очереди либо запускать параллельные запросы с ограничением количества одновременно передаваемых объектов.

Загрузка больших файлов частями

Обычный multipart/form-data удобен для файлов умеренного размера, но при нестабильном соединении его недостаток очевиден: обрыв в конце приводит к повторной передаче всего объекта. Частичная загрузка делит файл на блоки, например по 5 МБ. Каждый блок отправляется отдельным запросом с номером части и общим идентификатором.

В браузере для этого применяется file.slice, а PHP сохраняет фрагменты во временную папку. После получения всех частей сервер объединяет их в правильном порядке. Клиент может хранить идентификатор передачи и повторять только неудачный блок, что особенно важно для мобильных сетей.

const chunkSize = 5 * 1024 * 1024;
let offset = 0;

function sendChunk(file) {
    const chunk = file.slice(offset, offset + chunkSize);
    const data = new FormData();

    data.append('chunk', chunk);
    data.append('offset', offset);
    data.append('fileSize', file.size);
    data.append('fileName', file.name);

    fetch('chunk-upload.php', {
        method: 'POST',
        body: data
    })
    .then(response => response.json())
    .then(result => {
        offset = result.offset;

        const percent = Math.round(offset / file.size * 100);
        progressBar.style.width = percent + '%';
        progressBar.textContent = percent + '%';

        if (offset < file.size) {
            sendChunk(file);
        } else {
            status.textContent = 'Файл полностью загружен';
        }
    });
}

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

Проверка и эксплуатация в реальном проекте

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

Журналы PHP и веб-сервера помогут обнаружить превышение лимитов, ошибки прав доступа и неожиданные ответы. Загруженные файлы лучше хранить вне публичного каталога, если они должны быть доступны только авторизованным пользователям. Выдача в таком случае выполняется через отдельный PHP-контроллер после проверки прав.

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

Такой загрузчик сочетает понятный интерфейс на JavaScript и контролируемую серверную обработку на PHP. Для небольших файлов достаточно XMLHttpRequest с событием прогресса, а для крупных объектов лучше перейти к блочной передаче с возобновлением.