PHPackages                             phpdot/filesystem - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [HTTP & Networking](/categories/http)
4. /
5. phpdot/filesystem

ActiveLibrary[HTTP & Networking](/categories/http)

phpdot/filesystem
=================

Coroutine-safe, PSR-native file storage for the PHPdot ecosystem: local and S3-compatible (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces) over a PSR-18 + SigV4 client, with typed streams, resumable chunked uploads and first-class progress.

v0.2.0(2w ago)01MITPHPPHP >=8.5

Since Jul 18Pushed 1w agoCompare

[ Source](https://github.com/phpdot/filesystem)[ Packagist](https://packagist.org/packages/phpdot/filesystem)[ RSS](/packages/phpdot-filesystem/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependencies (29)Versions (4)Used By (0)

phpdot/filesystem
=================

[](#phpdotfilesystem)

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
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Architecture](#architecture)
- [Testing](#testing)
- [License](#license)

Requirements
------------

[](#requirements)

RequirementConstraintPHP`>= 8.5``ext-fileinfo``*``ext-hash``*``league/mime-type-detection``^1.16``phpdot/console``^0.2``psr/event-dispatcher``^1.0``psr/http-client``^1.0``psr/http-factory``^1.0``psr/http-message``^2.0``psr/http-server-handler``^1.0``symfony/console``^8.0`Bring any PSR-17/PSR-18 implementation. `phpdot/container` is a dev-only suggestion (the binding attributes are inert without it).

Installation
------------

[](#installation)

```
composer require phpdot/filesystem
```

Usage
-----

[](#usage)

```
use Nyholm\Psr7\Factory\Psr17Factory;
use PHPdot\Filesystem\Adapter\LocalAdapter;
use PHPdot\Filesystem\Filesystem;
use PHPdot\Filesystem\FilesystemConfig;
use PHPdot\Filesystem\Write\WriteContents;

$psr17      = new Psr17Factory();
$adapter    = new LocalAdapter(new FilesystemConfig(root: '/var/storage'), $psr17);
$filesystem = new Filesystem($adapter, new WriteContents($psr17));

$filesystem->write('invoices/2026.pdf', $pdfBytes);   // string | PSR-7 stream | UploadedFile
$pdf = $filesystem->read('invoices/2026.pdf');
$url = $filesystem->url('invoices/2026.pdf');          // public or presigned, by visibility

foreach ($filesystem->listContents('invoices', deep: true) as $entry) {
    echo $entry->path(), PHP_EOL;
}
```

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
------------

[](#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.

 ```
graph TD
    APP["Application / FilesystemInterface"]
    FS["Filesystemread / write / url / listContents"]
    WRITE["WriteContentsstring | stream | UploadedFile → readable stream"]
    ADAPTER["AdapterInterfaceLocalAdapter (fopen/rename) / S3 adapter"]
    S3["S3Client + SignatureV4PSR-18 client, header-auth + presign, no AWS SDK"]
    EXTRAS["Validation · Path generator · Upload engineMIME/size/dimensions, token keys, resumable multipart"]

    APP --> FS
    FS --> WRITE
    FS --> ADAPTER
    ADAPTER --> S3
    FS --> EXTRAS
```

      Loading Testing
-------

[](#testing)

```
composer install
composer test        # PHPUnit
composer analyse     # PHPStan, level max + strict rules
composer cs-check    # PHP-CS-Fixer
composer check       # All three
```

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
-------

[](#license)

MIT.

**This repository is a read-only mirror**, generated by CI from [phpdot/monorepo](https://github.com/phpdot/monorepo). [Pull requests](https://github.com/phpdot/monorepo/pulls)and [issues](https://github.com/phpdot/monorepo/issues) belong in the monorepo.

###  Health Score

39

—

LowBetter than 84% of packages

Maintenance97

Actively maintained with recent releases

Popularity2

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~16 days

Total

3

Last Release

14d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/62e82421bda4b5d6ba9a47ba6d88caca060dcd0d1a2862f351f3a97657385db0?d=identicon)[phpdot](/maintainers/phpdot)

---

Top Contributors

[![o3AM](https://avatars.githubusercontent.com/u/252500?v=4)](https://github.com/o3AM "o3AM (4 commits)")

---

Tags

filesystems3psr-18storageswoolecoroutineuploads

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/phpdot-filesystem/health.svg)

```
[![Health](https://phpackages.com/badges/phpdot-filesystem/health.svg)](https://phpackages.com/packages/phpdot-filesystem)
```

###  Alternatives

[typo3/cms

TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL.

1.2k1.9M122](/packages/typo3-cms)[tempest/framework

The PHP framework that gets out of your way.

2.3k42.4k21](/packages/tempest-framework)[typo3/cms-core

TYPO3 CMS Core

3714.0M5.9k](/packages/typo3-cms-core)[shopware/core

Shopware platform is the core for all Shopware ecommerce products.

605.9M718](/packages/shopware-core)[shopware/platform

The Shopware e-commerce core

3.4k1.5M3](/packages/shopware-platform)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

86538.6k](/packages/flow-php-flow)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)