Download the PHP package zenstruck/filesystem without Composer

zenstruck/filesystem

This library is a wrapper for the excellent league/flysystem File Storage Abstraction library. It provides an alternate API with the following major changes:

1. The main difference is the concept of Image objects. These are wrappers for an individual filesystem node and provide info, metadata and more features. These can be passed around (ie sent to your templates) or even used as Doctrine Types.
2. Combine certain Flysystem methods. For example, delete() removes both files and directories, write() can write both strings and streams (+ more).
3. Eases the use of filesystem files as real, local files. Many 3rd party libraries that manipulate files require local files.

Additionally, the following features are provided:

1. Filesystem wrappers to add additional functionality (ie MultiFilesystem, and LoggableFilesystem).
2. Powerful testing helpers.
3. TarFile representing a local zip/tar(.gz/bz2) file that acts as both a filesystem and a real file.
4. Doctrine Integration.
5. Symfony Integration
   • Custom Responses
   • Validators
   • Bundle to help configure filesystem services, wire the Doctrine integration and additional testing helpers.

Installation

API

Filesystem

Node

Interface: Zenstruck\Filesystem\Node.

File

Interface: Zenstruck\Filesystem\Node\File (extends Node).

[!NOTE] See zenstruck/temp-file for more details about File::tempFile().

[!NOTE] See zenstruck/stream for more details about File::stream().

PendingFile

Class: Zenstruck\Filesystem\Node\File\PendingFile (extends \SplFileInfo and implements File).

Image

Interface: Zenstruck\Filesystem\Node\File\Image (extends File).

[!NOTE] See zenstruck/image for more details about Image::transform() and Image::thumbHash().

PendingImage

Class: Zenstruck\Filesystem\Node\File\Image\PendingImage (extends Image).

Directory

Interface: Zenstruck\Filesystem\Node\Directory (extends Node).

[!NOTE] Most of the advanced filters require symfony/finder (composer require symfony/finder).

Filesystems

FlysystemFilesystem

Filesystem DSNs

ScopedFilesystem

MultiFilesystem

CacheFilesystem

[!NOTE] A psr/cache-implementation is required.

LoggableFilesystem

[!NOTE] A psr/log-implementation is required.

EventDispatcherFilesystem

[!NOTE] A psr/event-dispatcher-implementation is required.

[!NOTE] See event classes to see what is made available to them.

[!NOTE] The Pre*Event properties can be manipulated.

ZipFile

[!NOTE] league/flysystem-ziparchive is required (composer require league/flysystem-ziparchive).

This is a special filesystem wrapping a local zip archive. It acts as both a Filesystem and \SplFileInfo object:

When creating without a path, creates a temporary archive file (that's deleted at the end of the script):

Write operations can be queued and committed via a transaction:

Static helper for quickly creating zip archives:

TarFile

[!NOTE] league/flysystem-read-only is required (composer require league/flysystem-read-only).

This is a special filesystem wrapping an existing local tar(.gz/bz2) archive. It acts as both a readonly Filesystem and \SplFileInfo object:

TestFilesystem

This filesystem wraps another and provides assertions for your tests. When using PHPUnit, these assertions are converted to PHPUnit assertions.

[!NOTE] zenstruck/assert is required to use the assertions (composer require --dev zenstruck/assert).

InteractsWithFilesystem

Use the InteractsWithFilesystem trait in your unit tests to quickly provide an in-memory filesystem.

[!NOTE] By default, league/flysystem-memory is required (composer require --dev league/flysystem-memory).

FilesystemProvider

To provide your own filesystem for your tests, have your tests (or base test-case) implement FilesystemProvider:

[!NOTE] By default, the provided filesystem isn't reset before each test. See the ResetFilesystem to enable this behaviour.

FixtureFilesystemProvider

A common requirement for filesystem tests, is to have a set of known fixture files that are used in your tests. Have your test's (or base test-case) implement FixtureFilesystemProvider to provide in your tests:

[!NOTE] If the league/flysystem-read-only adapter is available, it's used to wrap your fixture adapter to ensure you don't accidentally overwrite/delete your fixture files (composer require --dev league/flysystem-read-only).

ResetFilesystem

If using your own FilesystemProvider, you can use the ResetFilesystem trait to purge your filesystem before each test.

Symfony Integration

Responses

Helpful custom Symfony responses are provided.

FileResponse

Take a filesystem File and send as a response:

ArchiveResponse

Zip file(s) and send as a response. Can be created with a local file, local directory, instance of Directory.

Validators

Both a PendingImage validator is provided. The constraints have the same API as Symfony's native File and Image constraints.

Bundle

Configuration

Services

Serializer

Form Types

PendingFileType

PendingImageType

Commands

zenstruck:filesystem:purge

Routing

Public Url Route

Temporary Url Route

Transform Url Route

RouteTransformUrlGenerator

Doctrine Integration

Functional/Integration Testing

TODO: Note about Mock::pendingFile()/pendingImage(). TODO: Note about Foundry\LazyMock::pendingFile()/pendingImage().

Testing Performance

Full Default Bundle Configuration

Backward Compatibility Promise

This library follows Symfony's BC Promise with the following exceptions:

1. Zenstruck/Filesystem and any implementations are considered internal for implementation/extension.
2. Zenstruck/Filesystem/Node and any implementations are considered internal for implementation/extension.