TurboPush is for web applications that need users to upload big files: video, archives, datasets. A single multi-gigabyte POST is fragile. One dropped connection and the user starts again, and PHP’s upload limits get in the way. TurboPush splits each file into chunks, sends several at once and puts the file back together on the server.
\nThe browser client:
\nresumable: true, carries on after a page reload, asking the server which chunks it already has and sending only the restThe PHP endpoint is the part that faces the internet, so it’s strict. It checks every ID, chunk index and size against limits you set. It cleans file names, blocks extensions a web server might execute or a browser might run scripts in, and can check an extension allowlist and the MIME type detected from the file’s contents. Chunks wait outside the web root, and each upload is locked so parallel or repeated requests can’t corrupt a file. Its error messages never reveal server paths. It’s same-origin only unless you list other origins.
\nThe client is one TypeScript file with no dependencies, published as ESM and CommonJS builds with type declarations. It targets ES2020 and current browsers, and Node.js 18 or later.
\nThe server is a single PHP class with no dependencies, for PHP 7.4 to 8.5. Each chunk is written to a unique temporary name and then renamed into place, so a retried or duplicate chunk can never leave a half-written file behind. A running total of bytes received stops a client storing more than it declared. Finalising holds the upload’s lock, joins the chunks into a temporary file in the upload directory and renames it into place. It’s idempotent: repeat it after success and you get the same answer.
\nThe protocol between the two halves is small and written down in PROTOCOL.md, and a conformance suite tests any server against it, so either half can be paired with your own code. The tests include Jest for the client, PHPUnit with concurrency tests that start real parallel PHP processes, and interop tests that run the client against tusd and tus-php in Docker. GitHub Actions runs the client tests on Node.js 18 to 24 and the PHP tests on PHP 7.4 to 8.5.
Install the PHP endpoint with Composer, and the client from GitHub:
\ncomposer require tomgould/turbopush\nnpm install github:tomgould/TurboPush\nThen point the client at your endpoint:
\nimport { TurboPush } from 'turbopush';\n\nconst uploader = new TurboPush({ endpoint: '/upload.php', resumable: true })\n .onProgress(files => files.forEach(f => console.log(`${f.fileName}: ${Math.round(f.percentage)}%`)));\n\ninput.addEventListener('change', () => uploader.addFiles(input.files).push());\nAnd handle the uploads on the server, with the files stored outside the web root:
\nuse TurboPush\\TurboPushEndpoint;\n\n(new TurboPushEndpoint('/var/lib/myapp/uploads'))\n ->setMaxFileSize(2 * 1024 * 1024 * 1024)\n ->setAllowedExtensions(['jpg', 'png', 'pdf', 'zip'])\n ->handle();\nCheck the user’s session before calling handle(): anyone who can reach the endpoint can upload. The demo lets you try it, and deletes each upload as soon as it’s checked.