Создание загрузчика файлов на 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 с событием прогресса, а для крупных объектов лучше перейти к блочной передаче с возобновлением.