Download the PHP package resumable/chunked-uploader without Composer

Resumable Chunked Uploader

Enterprise-grade, framework-agnostic PHP 8.2 library for handling large file uploads via chunking with constant-memory stream assembly, resume capability, and cryptographic integrity checks.

Chunks are persisted independently, progress is kept in a durable store (Redis or a relational database), and the final file is assembled using native PHP streams — never buffering the whole file into memory, regardless of how large it is.

Table of contents

• Highlights
• Architecture
• Core benefits
• Installation
• Standalone PHP quickstart
• Framework integration
  • Laravel 10 / 11
  • Symfony 6 / 7
• Vanilla JavaScript client
• Security model
• API reference
• Configuration options
• Testing
• License

Highlights

• O(1) memory chunk assembly via fopen() + stream_copy_to_stream().
• Resume support for out-of-order chunks and interrupted requests.
• Atomic progress updates in Redis (optimistic locking).
• HMAC tokens bound to upload metadata and client context.
• Magic-byte MIME validation (only reads the first 4096 bytes).
• Strict path sanitization against directory traversal.
• Optional ClamAV scanning and Redis rate limiting.
• Atomic failure cleanup removes a stored chunk when its metadata update fails, so transient database errors do not create permanent orphan bytes.
• Bounded cleanup scans local directories, S3 pages, Redis cursors, and PDO rows incrementally, including S3 deletion batches larger than 1,000 objects.
• ChunkUploader is the single canonical coordinator.
• Optional PHP 8 attributes provide endpoint-specific immutable config overrides without changing global defaults.
• Flysystem v3 storage is available as an optional driver.
• Zero framework dependency in the core package.
• Laravel and Symfony bridges + a dependency-free vanilla JS client.

Architecture

Data flow for a single chunk:

Core benefits

Installation

Requirements:

• PHP ^8.2
• ext-json
• One of ext-redis or predis/predis (for the Redis metadata driver)
• ext-pdo (for the PDO metadata driver)
• aws/aws-sdk-php (for the S3 storage driver)

Standalone PHP quickstart

Create one Chunk per HTTP request. index is zero-based. Retrying an already-accepted index is safe and idempotent.

Framework integration

Laravel 10 / 11

1. Register the service provider

In bootstrap/providers.php (Laravel 11) or config/app.php (Laravel 10):

2. Publish configuration (optional)

Then adjust config/chunk-uploader.php (allowed MIME types, spool directory, storage driver, etc.).

New in this version: token_salt (binds tokens to a client fingerprint), virus_scanning (ClamAV host/port), and rate_limiting (Redis-backed chunk flood protection) — all with matching .env variable names (see the config file for the full list).

3. Use the Facade

4. Add routes (see the example controller)

A complete, copy-pasteable controller lives at examples/laravel/ChunkUploadController.php.

Symfony 6 / 7

1. Enable the bundle

2. Configure the bundle

3. Add routes via attribute on the controller

The example at examples/symfony/ChunkUploadController.php uses attribute routing and constructor injection, so no routing YAML is needed.

Vanilla JavaScript client

A 100% dependency-free ES6+ client, using Blob.prototype.slice(), the Fetch API and FormData, is included in examples/vanilla-js/.

Features:

• Splits a File into binary chunks with file.slice(start, end).
• Sends each chunk as multipart/form-data via fetch().
• Automatic retry with exponential backoff on transient failures.
• pause() / resume() for interactive control.
• missingChunks() queries GET {endpoint}/status/{id} so a partially uploaded file resumes instead of restarting.
• Works in any modern browser with native fetch, FormData, and Blob.

Open examples/vanilla-js/index.html in a browser for a ready-to-run drag-and-drop demo.

Security model

1. Tokens — UploadTokenService issues HMAC-SHA256 tokens bound to the upload identifier, chunk count, total size, and an optional client salt (IP / fingerprint). Verification uses hash_equals() (constant-time).
2. Paths — PathSanitizer rejects null bytes, directory separators, traversal markers (.., ../), and unsafe identifiers. Never build a filesystem path from user input without running it through the sanitizer.
3. MIME — MagicByteValidator inspects only the first 4096 bytes via finfo and compares against an allow-list. Client-supplied MIME headers are never trusted.
4. Extension matching — ExtensionMimeMatchRule rejects files whose claimed extension disagrees with their detected MIME type.
5. Malware — ClamAvScanner streams data to clamd over the INSTREAM protocol in 1 MiB chunks. Use NullVirusScanner when scanning is handled elsewhere.
6. Abuse — RedisRateLimiter can key limits per IP, user, or upload token and applies them before accepting chunk bodies.
7. Storage — Keep temporary and final directories outside the public document root, and configure permissions and retention deliberately.

API reference

ChunkUploaderInterface

Chunk (readonly DTO)

identifier, token, index, totalChunks, chunkSize, totalSize, tmpFilePath, originalFilename, and optional checksum.

UploadState (readonly DTO)

identifier, totalChunks, totalSize, originalFilename, uploadedChunks, isCompleted, finalPath; plus hasChunk(), isComplete(), withUploadedChunk(), and withFinalPath().

Contracts

Endpoint-specific attributes

Global Laravel or Symfony configuration remains the default. A controller method can opt into a narrower immutable configuration for its own uploads:

The core resolver accepts either a ReflectionMethod or ReflectionClass and returns the unchanged global instance when no attribute is present.

Configuration options

Testing

The full suite runs completely offline: all disk I/O uses ephemeral temporary files that are cleaned up automatically; storage and metadata are in-memory doubles (FakeRedis, FakePdo); and Redis, S3, and ClamAV are never contacted. The suite covers:

• Unit tests against PathSanitizer, MagicByteValidator, UploadTokenService, StreamAssembler (memory ceiling), ClamAvScanner (stream-pair seam), RedisRateLimiter, S3ChunkStorage, and PdoMetadataRepository (with Postgres/MySQL dialect assertions).
• Feature tests for the full sequential upload flow, out-of-order resumable uploads, interrupted-upload recovery (idempotent retries, resume-from-missing-index, service-restart continuity), and both the Laravel and Symfony framework bridges.

License

MIT. See LICENSE.