(Without Fighting upload_max_filesize)

You deploy your app. A user picks a 400 MB video. They hit upload. The progress bar freezes. Then — nothing.

You check the logs. POST Content-Length exceeded post_max_size. Again.

We've all been there. The fix is usually "raise PHP limits" or "use S3." Both work — until you're on shared hosting, a legacy VPS, or a client who won't touch php.ini.

That's the problem Pinion solves.

What is Pinion?

Pinion is an open-source resumable chunked upload protocol for PHP.

Instead of one giant multipart/form-data request, the browser sends the file in small parts (default: 5 MB). The server stores each part, then assembles the final file on disk.

Three steps. That's the whole contract:

init → upload parts → complete

Protocol id: pinion · version: 2

Why not just use S3?

Object storage is great. But sometimes you need files on your server:

• A CMS media library on local disk
• A Laravel app without cloud budget
• Shared hosting with no S3 SDK
• An admin panel behind a simple PHP API

Pinion isn't a CDN or a storage service. It's a protocol — a stable HTTP contract that works in plain PHP, Laravel, or Pinoox.

How it works (30-second version)

sequenceDiagram
    participant Browser
    participant API
    participant Disk

    Browser->>API: POST /init (filename, size, fingerprint)
    API-->>Browser: upload_id, chunk_size, missing_indexes

    loop Each part
        Browser->>API: POST /upload (chunk + SHA-256 hash)
        API->>Disk: store part
    end

    Browser->>API: POST /complete
    API->>Disk: assemble file
    API-->>Browser: done ✓

Resume is built in. The client sends a fingerprint (name:size:lastModified:type). If the connection drops, the same file picks up where it left off — only missing parts are re-uploaded.

Integrity too. Each part gets a SHA-256 chunk_hash. The server can reject corrupted chunks before they pollute your disk.

Server side: 10 lines of PHP

composer require pinoox/pinion

use Pinoox\Pinion\Pinion;

Pinion::configure(['storage_path' => '/tmp/pinion']);

$handler = Pinion::http(['destination' => 'uploads/videos']);

$handler->init($_POST);
$handler->upload($_POST, $_FILES['chunk'] ?? null);
$handler->complete($_POST);

Wire five routes under any prefix you like:

POST /api/v1/upload/init
POST /api/v1/upload/upload
POST /api/v1/upload/complete
GET  /api/v1/upload/status/{id}
POST /api/v1/upload/abort/{id}

HttpHandler returns plain arrays — map them to JSON in Laravel, Pinoox, or raw PHP. No framework lock-in.

Browser side: one function, zero extra deps

npm install @pinooxhq/pinion-client

import { uploadFile } from '@pinooxhq/pinion-client';

await uploadFile(file, {
  baseURL: '/api/v1/upload',
  unwrapPreset: 'pinoox',
  onProgress: ({ percent, speed, eta }) => {
    console.log(`${percent}% · ${speed} B/s · ETA ${eta}s`);
  },
});

No Axios required. The client uses native fetch by default. Already on Axios? Pass it in — you get per-chunk onUploadProgress too.

baseURL is just the prefix. The client calls /init, /upload, /complete for you. You don't loop over chunks manually unless you want to.

Level up when you need to

Start simple. Grow when the project demands it.

Small files? Skip Pinion entirely:

const result = await uploadFile(file, {
  baseURL: '/api/v1/upload',
  auto: true,
  threshold: 8 * 1024 * 1024,
});

if (result === null) {
  // file under 8 MB — use your normal single POST
}

What I like about the design

1. Boring HTTP. JSON for init/complete, FormData for chunks. No WebSockets, no custom binary framing. Debug with curl or DevTools.

2. Parallel by default. Upload 2 parts at once. Retry failed parts with backoff. Progress includes speed and ETA — not just a percentage.

3. Framework adapters, not framework prison. Core engine is pure PHP. Laravel gets a Service Provider and Facade. Pinoox gets a Portal and CLI (pinion:list, pinion:clean). Plain PHP gets HttpHandler.

4. Unwrap presets. Your API returns { data: { … } }? Set unwrapPreset: 'pinoox'. Flat JSON? Use 'flat'. The client adapts; you don't rewrite parsers.

Real-world fit

Try it

# Server
composer require pinoox/pinion

# Browser
npm install @pinooxhq/pinion-client

• Repo: github.com/pinoox/pinion
• PHP docs: README
• Client docs: client/README
• License: MIT

If you've fought upload_max_filesize one too many times, Pinion might save your next Friday night.

Questions, issues, or war stories welcome in the repo. 🙌