Download the PHP package jardisadapter/filesystem without Composer

Jardis Filesystem

Part of Jardis — the Domain-Driven Design platform for PHP. You model your domain; Jardis generates the production-ready hexagonal code (DTOs, Command/Query handlers, repositories, persistence). This package is part of the open-source foundation that generated code runs on.

File operations without the framework. A lean filesystem abstraction for PHP covering local and S3-compatible storage — designed for applications that store uploads, manage assets, or sync backups. No Flysystem, no AWS SDK, no dependency bloat. Just cURL and PHP builtins.

Why This Filesystem?

• Two classes are enough — FilesystemService + a config object, nothing else
• Multiple instances — local for uploads, S3 for backups, both in the same project
• Atomic handler pipeline — each operation is its own invokable, orchestrated by closures
• Stream support — read and write large files without memory overhead
• S3 without the SDK — AWS Signature v4 via cURL, works with MinIO, DigitalOcean Spaces, etc.
• Security hardened — path traversal protection, symlink containment, XXE prevention, secret masking
• ~78% test coverage — integration tests against real MinIO, not mocks

Installation

Quick Start

Local Filesystem

S3-Compatible Storage

Multiple Backends

Advanced Configuration

For custom permissions, symlink settings, or other advanced options — use create() with a config object:

File Operations

Stream Support

For large files — no memory overhead:

Directory Operations

Visibility

Control file permissions (local: Unix chmod, S3: ACL):

Configuration

LocalConfig

S3Config

The secret is protected with #[\SensitiveParameter] and masked in var_dump() / debug output.

Error Handling

All exceptions implement FilesystemExceptionInterface — catch one, catch all:

Architecture

The user only sees FilesystemService + config objects. Internally, the orchestrator builds a pipeline of atomic invokable handlers — one __invoke per operation:

Each handler is an invokable object (__invoke) — independently testable, replaceable, composable. The orchestrator extracts closures via ->__invoke(...) and stores only the closures. No handler object survives as a property.

Security

• Path traversal — .. segments and null bytes rejected before any I/O
• Symlink containment — realpath() check ensures resolved paths stay inside root
• Root validation — LocalConfig resolves root via realpath() at construction time
• XXE prevention — LIBXML_NONET on all XML parsing (S3 responses)
• Secret masking — S3Config::$secret uses #[\SensitiveParameter] + __debugInfo()
• Bucket wipe guard — deleteDirectory('') with empty prefix is rejected

Contracts

The package implements interfaces from jardissupport/contracts:

Jardis Kernel Integration

jardiscore/foundation is deleted. Its Handler\FilesystemHandler was ported 1:1 into jardiscore/kernel as Bootstrap\Handler\BuildFilesystemFromEnv, which the packer Bootstrap\BuildDomainKernelFromEnv composes into the DomainKernel. In a class extending {Domain}Context, the filesystem is available via resource():

DomainKernel::filesystem() is typed ?FilesystemServiceInterface (core/kernel/src/DomainKernel.php:106) — the return value is the instance or null, there is no third state; null means the adapter is not installed.

The kernel reads no ENV for this adapter. BuildFilesystemFromEnv takes no arguments and returns a stateless FilesystemService factory — the developer reads the FS_*/FS_S3_* variables above directly, builds the Config objects, and passes them to FilesystemService.

No singleton, no handler call in application code — the developer decides how many filesystem instances exist and how they are configured. resource()->filesystem() returns FilesystemServiceInterface.

Development

Documentation

Full documentation, guides, and API reference:

docs.jardis.io/en/adapter/filesystem

License

MIT License — free for any use, including commercial.

AI-Assisted Development

This package ships with a skill for Claude Code, Cursor, Continue, and Aider. Install it in your consuming project:

More details: https://docs.jardis.io/en/skills