Download the PHP package phpdot/filesystem without Composer

phpdot/filesystem

Coroutine-safe, PSR-native file storage. One FilesystemInterface spans local disk and S3-compatible backends (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces) through a hand-rolled PSR-18 + Signature V4 client — no AWS SDK. Bodies flow as PSR-7 streams with bounded memory, uploads are resumable, validation is built in, and the server (not the browser) picks where bytes land.

Table of Contents

• Requirements
• Installation
• Usage
• Architecture
• Testing
• License

Requirements

Bring any PSR-17/PSR-18 implementation. phpdot/container is a dev-only suggestion (the binding attributes are inert without it).

Installation

Usage

Presigned direct uploads (S3 / R2 / MinIO)

Let the client PUT straight to the bucket — PHP only mints the grant:

The content type is pinned into the signature when given — a client sending any other type is rejected by the bucket (403 SignatureDoesNotMatch), so the stored type stays a server decision. Pass null only when nothing from the bucket is served to a browser. A declared size is pinned the same way: Content-Length joins the signature and the bucket refuses a body of any other length. Without one the grant accepts any size; verify on completion against the storage's own truth:

Upload progress moves client-side with this lane — XHR/fetch progress events — while the through-PHP lanes (streamed writes, resumable chunks) keep the server-side progress bar.

Large files (the resumable direct lane) — one grant per multipart part; a dropped part retries alone instead of restarting the upload:

The single-PUT 5 GB ceiling does not apply, and a part grant pins its declared size exactly like a whole-object grant does. complete() refuses any upload whose stored bytes differ from the declaration in either direction and aborts it (UploadSizeMismatch).

Checksums without downloads (SHA-256). Every upload path carries the digest as x-amz-checksum-sha256 — server writes hash the stream they hold, grants sign the digest you pass (presignedUpload(..., $sha256Base64); the client computes it with SubtleCrypto and the server mints the grant around it). S3 verifies the value against the bytes it receives (a lying digest is a 400) and stores it, so the object's checksum comes back by HEAD — never by downloading the file:

For multipart, the create call decides: pass ['checksum_algorithm' => 'SHA256'] (through UploadManager::create()'s $config, or any createMultipart() config) and the bucket tracks every part's digest into a stored composite — the finished object's checksum comes back by HEAD as "<sha256-of-concatenated-part-digests>-<partCount>" on both S3 and MinIO. Without the directive, a multipart complete stores nothing object-level on MinIO, and on AWS only the automatically computed CRC64NVME. storedChecksum($path) reads whatever the storage actually holds — "sha256:<hex>", "sha256:<hex>-N", or "crc64nvme:<base64>" (AWS stamps every object with CRC64NVME, so even legacy ones answer) — from one HEAD, never by downloading. Objects whose storage holds nothing still fall back to streaming the object once through checksum().

On R2, part digests must be CRC64NVME — R2 refuses SHA-256 part headers outright (501) but verifies CRC64NVME against the bytes at the door and stores the finished object's CRC64, so storedChecksum() answers there too:

Crc64Nvme is the package's own implementation (big-endian base64 wire form); a browser client mirrors it with a small table-driven routine — crypto.subtle has SHA-256 natively but no CRC.

CORS: the bucket must accept the browser's origin and PUT method (AWS: a CORS configuration allowing PUT with the Content-Type header; R2 and MinIO equivalent).

You talk to one interface; swap the backend by swapping one binding. In a PHPdot application the container auto-binds FilesystemInterface, so the wiring above disappears.

Beyond read/write/list, the package adds a collect-all validation pipeline (MIME, size, extension, image dimensions over a bounded prefix), a token path generator ({date}/{uuid}/{hash}…) so the server picks the key, an optional managed-files layer that persists a FileRecord per file with soft-delete and quarantine, and a tus-compatible resumable upload endpoint plus CLI uploader.

Architecture

Filesystem is the operator — it drives an AdapterInterface (LocalAdapter native fopen/rename, or the S3 adapter over a PSR-18 + SigV4 client with no AWS SDK) and a WriteContents pipeline that collapses a string, stream, or uploaded file into one readable stream. Validation, path generation, and the resumable upload engine sit alongside, and I/O goes non-blocking automatically under Swoole without any ext-swoole dependency.

Testing

The unit suite (including the S3 client, signing vectors, and adapters against an in-memory HTTP client) runs with no external services. The S3 integration suite connects to a real bucket and skips unless AWS credentials and PHPDOT_S3_TEST_BUCKET are set.

License

MIT.

This repository is a read-only mirror, generated by CI from phpdot/monorepo. Pull requests and issues belong in the monorepo.