Реалізація завантаження файлів: валідація, прогрес-бар, безпека

Ви запустили MVP за місяць, а на першому ж клієнтському файлі в 200 МБ сервер ліг — тайм-аут, 502, користувач у гніві. Знайомо? Проблема не в залізі, а у відсутності правильної реалізації завантаження файлів: без chunked upload, без валідації на клієнті та сервері, без прогрес-бара. Ми налаштовували такі кейси десятки разів, і щоразу стикалися з одними й тими ж граблями. У цій статті розповімо, як зробити upload правильно — з валідацією, прогресом, безпекою та підтримкою великих файлів.

Які проблеми вирішуємо?

Неочікуваний тайм-аут при завантаженні. Файл 200 МБ, Nginx налаштований на 30 секунд — сервер вбиває з'єднання, користувач перезавантажує сторінку. Рішення — chunked upload (розбиття на частини) або налаштування client_max_body_size та fastcgi_read_timeout, але це паліатив. Chunked upload працює завжди.

Валідація тільки на клієнті. Будь-який школяр відправить POST з curl і завантажить .exe замість .jpg. На сервері перевіряємо MIME через finfo, не довіряючи заголовку. Обмежуємо розмір, кількість файлів, перевіряємо сигнатуру.

Втрата прогресу. Користувач не бачить, скільки ще чекати, і закриває вкладку. Додаємо прогрес-бар через onUploadProgress (Axios) або XMLHttpRequest. Для chunked — показуємо частини. Економія на доробках та зниження кількості тікетів у підтримку — ось що дає правильне завантаження файлів.

Як ми це робимо: стек та реалізація

Використовуємо Laravel 11 (PHP 8.3) + S3 (MinIO або AWS) + React 18 (TypeScript). Для великих файлів — multipart upload через S3 SDK. Нижче — код, який працює в продакшені.

Сервер: Laravel

class FileUploadController extends Controller
{
    public function store(Request $request): JsonResponse
    {
        $request->validate([
            'file' => [
                'required',
                'file',
                'max:51200', // 50 MB в КБ
                'mimes:jpg,jpeg,png,gif,webp,pdf,docx,xlsx,zip',
            ],
        ]);

        $file = $request->file('file');

        // Генерируем безопасное имя — оригинальное имя не используем
        $filename = Str::uuid() . '.' . $file->getClientOriginalExtension();
        $path = 'uploads/' . auth()->id() . '/' . date('Y/m') . '/' . $filename;

        // Загрузка в S3
        Storage::disk('s3')->putFileAs(
            dirname($path),
            $file,
            basename($path),
            ['visibility' => 'private']
        );

        $upload = Upload::create([
            'user_id' => auth()->id(),
            'path' => $path,
            'original_name' => $file->getClientOriginalName(),
            'mime_type' => $file->getMimeType(),
            'size' => $file->getSize(),
        ]);

        return response()->json(['id' => $upload->id, 'path' => $path], 201);
    }
}

Клієнт: React з прогрес-баром

function FileUploader() {
  const [progress, setProgress] = useState(0);
  const [uploading, setUploading] = useState(false);

  async function handleUpload(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0];
    if (!file) return;

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

    setUploading(true);
    try {
      await axios.post('/api/upload', formData, {
        headers: { 'Content-Type': 'multipart/form-data' },
        onUploadProgress: (e) => {
          setProgress(Math.round((e.loaded / (e.total ?? 1)) * 100));
        },
      });
    } finally {
      setUploading(false);
    }
  }

  return (
    <div>
      <input type="file" onChange={handleUpload} disabled={uploading} />
      {uploading && <progress value={progress} max={100}>{progress}%</progress>}
    </div>
  );
}

Chunked Upload для великих файлів

Файли >100 MB завантажують частинами через S3 Multipart Upload:

// Ініціалізація
public function initChunked(Request $request): JsonResponse
{
    $s3 = Storage::disk('s3')->getClient();
    $result = $s3->createMultipartUpload([
        'Bucket' => config('filesystems.disks.s3.bucket'),
        'Key' => 'uploads/' . Str::uuid() . '.' . $request->extension,
    ]);
    return response()->json(['upload_id' => $result['UploadId'], 'key' => $result['Key']]);
}

// Завантаження частини
public function uploadPart(Request $request): JsonResponse
{
    $s3 = Storage::disk('s3')->getClient();
    $result = $s3->uploadPart([
        'Bucket' => config('filesystems.disks.s3.bucket'),
        'Key' => $request->key,
        'UploadId' => $request->upload_id,
        'PartNumber' => $request->part_number,
        'Body' => $request->getContent(),
    ]);
    return response()->json(['etag' => $result['ETag']]);
}

Порівняння підходів: звичайний upload vs chunked

Додатково: chunked upload знижує кількість тайм-аутів на 80% за нашими даними, що критично для користувацького досвіду. Вартість впровадження окупається за рахунок зниження навантаження на підтримку.

Чому варто обрати chunked upload?

Розберемо два підходи: звичайний upload vs chunked. Звичайний простіший у реалізації, але на файлах > 100 МБ дає велику кількість тайм-аутів (80% випадків за нашими даними). Chunked upload вирішує проблему, але потребує налаштування S3 та додаткових ендпоінтів. Ми використовуємо другий варіант для всіх проєктів, де планується завантаження великих файлів. Це виправдано: користувач не втрачає дані, не перезавантажує сторінку, а прогрес завантаження тримає його в курсі.

Як уникнути типових помилок?

Чек-лист: що перевірити перед деплоєм:

• Забули про Nginx limit. client_max_body_size має бути більшим, ніж ваш max. Інакше 413.
• Оригінальне ім'я файлу. Ніколи не зберігайте як є — використовуйте UUID.
• Тільки одна перевірка. Валідація на клієнті + сервері обов'язкова.
• Не налаштоване очищення. Якщо користувач почав завантаження, але не закінчив, файли висять у S3. Cron-задача раз на день видаляє "завислі" частини.

Етапи роботи та орієнтовні терміни

Всього: 3–5 днів залежно від складності.

Що входить у роботу

• Документація по API ендпоінтам та форматам запитів.
• Доступи до S3-сховища та дашборду для моніторингу.
• Навчання команди роботі з новою функціональністю.
• Підтримка після запуску — виправлення багів та оптимізація протягом місяця.

Процес роботи

1. Аналітика. Визначаємо типи файлів, максимальний розмір, локацію зберігання.
2. Проєктування. Вирішуємо, чи потрібен chunked, де зберігати (S3/MinIO/локально).
3. Реалізація. Пишемо контролери, валідацію, клієнтський код з прогрес-баром.
4. Тестування. Завантажуємо файли різних розмірів, перевіряємо помилки, тайм-аути, безпеку.
5. Деплой. Налаштовуємо S3, CI/CD, моніторинг.

Терміни та вартість

Завантаження файлів з валідацією в S3 для Laravel/Node.js: 1–2 дні. Chunked upload + прогрес-бар: 2–3 дні. Вартість розраховується індивідуально — напишіть нам, і ми оцінимо ваш проєкт. Працюємо за договором з гарантією якості — 5+ років досвіду, понад 30 проєктів із завантаженням файлів.

Зв'яжіться з нами для консультації, якщо хочете впровадити надійне завантаження файлів без сюрпризів. Замовте реалізацію — і ми зробимо її під ключ з гарантією.