README

The Sally FAL is a lean, very straightforward abstraction layer with basic operations for creating, reading, deleting, etc. files. It does not try to solve every problem and also tries to keep a reasonable OOP overhead.

Requirements

Sally FAL requires PHP 5.3.2+. Specific adapters (like PDO or S3) may need additional libraries which are not installed by default. You will have to add them to your project yourself.

Note that even though this library originates in SallyCMS, Sally is not required to use it. They merely share the same base namespace (sly), but nothing else.

Installation

Add the following requirements to your composer.json:

:::json
{
    "require": {
        "sallycms/filesystem": "$VERSION"
    }
}

Replace $VERSION with one of the available versions on Packagist.

Overview

The library offers the following adapters:

Adapter\Blackhole is always empty and can never contain any files. Write operations are simply ignored.
Adapter\Local stores files inside the regular filesystem.
Adapter\LocalHttp is similar to Adapter\Local, but returns an HTTP URL for files.
Adapter\Memory stores all files in memory.
Adapter\Pdo uses an already established PDO connection to store files inside a database.

Additionally, you can decorate these adapters with either your own or the already available decorators:

Decorator\CaseInsensitive forces all file names and paths to be lowercase.
Decorator\Encrypted encrypts and decrypts file contents using the phpsec/phpsec library.
Decorator\Gzip uses gzencode() and gzdecode() to transparently compress file contents.
Decorator\Prefixed can be used to restrict access to an underlying filesystem to a forced prefix path.

Interface

The following constraints are vital and must be implemented by every adapter:

The library only manages files, never directories (like Mercurial and Git do). However, implementations are free to consider using the regular directory separators (/ and \) to map file names to the underlying storage.
All paths are case-sensitive.
File contents may never be touched (i.e. never be trimmed).
All thrown exceptions must be either sly\Filesystem\FilesystemException or any subclass of it.
listFiles() must the files returned in a sorted fashion, matching the algorithm in Util::sortFilenames() (basically children first).
There can never be a Directory foo and a file foo in the same directory (this is a restriction specifically from the local filesystem and needs to be adopted by all other adapters to ensure a consistent behaviour).
All methods must properly handle both / and \ as a directory separator.

The PHP interface sly\Filesystem\Filesystem defines the following methods (in pseudo code):

::::php

<?php

interface Filesystem {
  public /* int    */ function getSize(string $filename);
  public /* int    */ function getMtime(string $filename);
  public /* string */ function getUrl(string $filename);
  public /* bool   */ function exists(string $filename);
  public /* bool   */ function read(string $filename);
  public /* string */ function write(string $filename, string $content);
  public /* string */ function touch(string $filename);
  public /* string */ function remove(string $filename);
  public /* string */ function copy(string $source, string $target);
  public /* string */ function move(string $source, string $target);
  public /* array  */ function listFiles(string $prefix = '');
}

License

Sally FAL is licensed under the MIT License - see the LICENSE file for details.

sallycms / filesystem

Maintainers

Details