Download the PHP package pinoox/pinion without Composer

Pinion — Resumable Upload Protocol for PHP

Pinion (pinoox/pinion) lets users upload large files in small parts — even when PHP upload_max_filesize / post_max_size are low.

Protocol id: pinion · protocol version: 2 · PHP 8.2+

Protocol version (2) is the wire format (protocol_version in API responses). Release columns are separate semver for the PHP and npm packages.

Quick start

1 — Install

2 — Server: three HTTP steps

3 — Browser: one function

That is the whole idea: init → upload parts → complete. The client does the loop for you.

Table of contents

• Quick start
• What is Pinion
• How it works
• Install
• Level 1 — Simple
  • Browser: upload one file
  • Server: wire HTTP routes
  • Routing & baseURL
• Level 2 — Practical patterns
  • Reusable uploader
  • Progress, retry, parallel
  • Small files vs large files
  • Auth headers & CORS
• Level 3 — Framework integration
  • Plain PHP
  • Pinoox
  • Laravel
• Level 4 — Advanced
  • Programmatic API (no HTTP)
  • Resume & fingerprint
  • Checksums & integrity
  • Configuration reference
  • Storage strategies
  • Custom destinations
  • Maintenance & CLI
• HTTP protocol (full reference)
• Browser client (full reference)
• PHP API surface
• Troubleshooting
• Package structure
• License

What is Pinion

The problem

On shared hosting or default PHP configs you often hit limits like:

A 500 MB video cannot be sent in one multipart/form-data request. Pinion splits the file into parts (default 5 MB), uploads them one by one, and assembles the final file on disk.

What Pinion is — and is not

When to use it

How it works

Key concepts:

Install

PHP — Packagist

Current release: 1.1.0 (pinoox/pinion)

Pinoox monorepo (local path):

JavaScript — npm

Current release: 1.2.0 (@pinooxhq/pinion-client)

Without npm (vendor copy)

Level 1 — Simple

Browser: upload one file

The fastest API — no setup object, no Axios:

unwrapPreset: 'pinoox' unwraps responses shaped like { data: { … } } (Pinoox / Laravel envelope). Use 'flat' if your API returns the payload directly.

Server: wire HTTP routes

Pinion needs five endpoints under one prefix. You choose the prefix; the client appends /init, /upload, etc.

Example prefix: /api/v1/upload

Minimal PHP router (no framework):

Return JSON from HttpHandler as-is, or map success / data / error to your framework response helper.

Routing & baseURL

baseURL in the JS client is the prefix only — not a single upload URL.

The client calls:

If you only have one endpoint POST /api/v1/upload for a regular single-file upload, that is not Pinion — use FormData + fetch instead.

Level 2 — Practical patterns

Reusable uploader

Create one client, upload many files:

Progress, retry, parallel

With Axios (optional) you also get raw per-chunk upload events:

Small files vs large files

Use auto to skip Pinion for files below a threshold (default 8 MB):

Auth headers & CORS

Pass headers once on the client — they apply to every step (init, upload, complete):

On the server, ensure CORS allows POST + GET on all five routes if the frontend is on another origin.

Cancel an upload

Batch upload

Level 3 — Framework integration

Plain PHP

HTTP handler — recommended for web apps:

Fluent builder — for scripts and jobs:

Pinoox (HMVC)

Inside a Pinoox project use Pinoox\Portal\Pinion — config, temp storage, Flysystem/S3, and pinx_file integration are wired in pincore.

Storage modes (pinion.config.php → defaults.mode):

Chunks always stage under storage/pinion. On complete, managed mode streams the assembled file to the app disk (local or S3) via UploadBuilder.

App controller (HMVC) — use the trait:

Local-only upload (no Flysystem — e.g. manager .pinx packages):

Browser client — npm @pinooxhq/pinion-client:

On complete with managed storage, the API returns file_id, url, and thumb (when applicable).

Routes (per app under apps/{package}/routes/):

→ client baseURL: '/app/pinion'

Template: pincore/config/pinion.routes.template.php

Config: pincore/config/pinion.config.php · temp: storage/pinion (pinion_uploads)

CLI:

Laravel

Laravel 10+ — auto-discovery via PinionServiceProvider.

1. Publish config

2. Routes (routes/api.php)

3. Controller

4. Facade (server-side jobs)

Level 4 — Advanced

Programmatic API (no HTTP)

Use Manager directly when chunks arrive from CLI, queue workers, or non-HTTP sources:

Low-level browser control (manual steps):

Resume & fingerprint

The client builds a fingerprint from file metadata:

On init, if the same fingerprint already has a pending session, the server returns it with resumed: true and missing_indexes — only missing parts are uploaded.

The JS client caches upload_id in localStorage (key: pinion_sessions) until complete succeeds.

Force resume explicitly:

Check stored session:

Checksums & integrity

Client sends chunk_hash automatically. To send whole-file hash on complete:

Configuration reference

Pass to Pinion::configure() or copy config/pinion.php.

Laravel .env:

Per-request defaults via HttpHandler:

Storage strategies

Temp files live under storage_path. On complete, the assembled file moves to the resolved destination. Expired pending sessions are cleaned via cleanExpired().

Custom destinations

By default NativePathResolver maps to('uploads/videos') relative to a base path. For multi-root apps implement PathResolverInterface:

Maintenance & CLI

Pinoox CLI:

HTTP protocol (full reference)

Endpoints

Init request

Init response

Same fingerprint on a pending session → resumed: true, missing_indexes only lists gaps.

Upload part request

multipart/form-data fields:

Do not set Content-Type: multipart/form-data manually — let the client / browser set the boundary.

Complete request

Error envelope

HttpHandler returns:

Common codes: PINION_INIT_FAILED, PINION_INVALID, PINION_CHUNK_HASH_MISMATCH, PINION_SESSION_EXPIRED, PINION_FILE_TOO_LARGE.

Browser client (full reference)

Published as @pinooxhq/pinion-client 1.2.0. Detailed npm guide: client/README.md

Usage levels

Transport

Unwrap presets

Set unwrapPreset: 'pinoox' when your PHP API wraps data in { data: … }.

Key exports

PHP API surface

Pinoox (pincore): Pinoox\Portal\Pinion, Pinoox\Component\Pinion\HttpHandler, CLI commands.

Laravel: PinionServiceProvider, Pinion facade.

Troubleshooting

Package structure

License

MIT — Pinoox