Object oriented high level filesystem abstraction

This is a high level filesystem abstraction for php, inspired by the Java filesystem API.

Why another filesystem abstraction?

We evaluated some filesystem abstraction frameworks, like Gaufrette. But none of the frameworks we found, is a real filesystem abstraction. Gaufrette for example is more a key => value storage, that use a filesystem or online storage as source. Some essential functions, like delete directory are not available in Gaufrette. Copying files across filesystem adapters is also not possible.

The benefit of php-filesystem is that it is a unique layer that can be...

• used every time you work with files (also for temporary files)
• used across multiple filesystem (also move or copy files between each other)
• nearly complete replace the php file api
• do not hide the file structure
• provide high and low level functions to the filesystem
• works with php iterators
• provide a "merged" filesystem, that build a merged structure from several filesystems
• support streaming
• provide configurable public url generation (useful for web apps)

Filesystem api

Filesystem is the basic interface to access any filesystem. You need a Filesystem instance to connect to the filesystem and get files, but not to work with it.

File is the basic interface to access files and directories inside of a filesystem. A File instance represents a pathname inside of the underlaying filesystem. With a File you can do all what you want, create files and directories, delete files and directories, read and write files and list directory content including glob'ing it.

FS is an static object, to control and access global filesystem access. Currently FS only handle the system temporary filesystem.

TemporaryFilesystem is an extending interface of Filesystem. The TemporaryFilesystem provide a createTempFile and createTempDirectory method. All files/directories created with these methods will be deleted if the filesystem gets destroyed.

Util is a static object with some filesystem related methods.

PublicUrlProvider is an interface for a class that generated public urls for a file.

AbstractFile is a basic abstract implementation of File.

Work with the filesystem

Get the root / node of a filesystem

/** @var Filesystem $fs *//** @var File $root */$root = $fs->getRoot();

Get a file from the filesystem

/** @var Filesystem $fs *//** @var File $file */$file = $fs->getFile('/example.txt');

Test if file exists and test if it is a file, directory or link

/** @var File $file */if ($file->exists()) {
if ($file->isLink()) {
// $file is a link
}
if ($file->isFile()) {
// $file is a file
}
if ($file->isDirectory()) {
// $file is a directory
}
}

Get basic informations about a file

/** @var File $file */// get the passname INSIDE of the filesystem (this may not be the real pathname)$pathname = $file->getPathname();
// get the basename$basename = $file->getBasename();
// the the extension$extension = $file->getExtension();
// get the parent directory/** @var File $parent */$parent = $file->getParent();
// get last access time$accessTime = $file->getAccessTime();
// get creation time$creationTime = $file->getCreationTime();
// get last modified time$lastModified = $file->getLastModified();
// get file size$size = $file->getSize();
// get owner (may be the name or uid)$owner = $file->getOwner();
// get group (may be the name or gid)$group = $file->getGroup();

Get and test permissions

/** @var File $file */// get permissions$mode = $file->getMode();
// test if file is readableif ($file->isReadable()) {
// do something...
}
// test if file is writeableif ($file->isWriteable()) {
// do something...
}
// test if file is executableif ($file->isExecutable()) {
// do something...
}

Delete files and directories

/** @var File $file */if ($file->isDirectory()) {
$file->delete(true); // recursive delete!!!
}
else {
$file->delete();
}

Copy files

Keep in mind: $source and $target does not need to be files in the same filesystem!

/** @var File $source *//** @var File $target */$source->copyTo($target);

Rename/Move files

Keep in mind: $source and $target does not need to be files in the same filesystem!

/** @var File $source *//** @var File $target */$source->moveTo($target);

Create a directory

/** @var File $file */if (!$file->exists()) {
$file->mkdir();
}

Create a directory path (including all missing parent directories)

/** @var File $file */if (!$file->exists()) {
$file->mkdirs();
}

Create a new empty file

/** @var File $file */if (!$file->exists()) {
$file->createNewFile();
}

Read and write files

/** @var File $file */// read the file$content = $file->getContents();
// write to the file$file->setContents("Hello world!\n");
// append to the file$file->appendContents("The world is like a pizza!\n");

Truncate files

/** @var File $file */$file->truncate(1024); // truncate to 1024 bytes

Streaming files

/** @var File $file */// read the file$stream = $file->openStream('rb');
$content = stream_get_contents($stream);
fclose($stream);
// write to the file$stream = $file->openStream('wb');
fwrite($stream, "Hello world!\n");
fclose($stream);
// append to the file$stream = $file->openStream('ab');
fwrite($stream, "The world is like a pizza!\n");
fclose($stream);

Calculate file hashes

/** @var File $file */// get md5 hash$md5 = $file->hashMD5();
// get raw md5 hash$md5raw = $file->hashMD5(true);
// get sha1 hash$sha1 = $file->hashSHA1();
// get raw sha1 hash$sha1raw = $file->hashSHA1(true);

List files in a directory

/** @var File $file */if ($file->isDirectory()) {
// get files and directories$children = $file->listAll();
// get files only$files = $file->ls();
// get directories only$directories = $file->listDirectories();
}

Glob files in a directory

/** @var File $file */if ($file->isDirectory()) {
// get files and directories$children = $file->glob('*example*');
// get files only$files = $file->globFiles('*example*');
// get directories only$directories = $file->globDirectories('*example*');
}

Iterate directories (simple)

Keep in mind: the magic childrens . and .. will never be visible to you!

/** @var File $file */if ($file->isDirectory()) {
/** @var File $child */foreach ($fileas$child) {
// do somethink with $child
}
}

Iterate directories (expert)

Keep in mind: the magic childrens . and .. will never be visible to you!

useBit3\Filesystem\Iterator\FilesystemIterator;
/** @var File $file */if ($file->isDirectory()) {
$iterator = newFilesystemIterator($file, FilesystemIterator::CURRENT_AS_PATHNAME);
/** @var string $child */foreach ($fileas$child) {
// $child will be the pathname
}
}

Get real url to a file

/** @var File $file */$url = $file->getRealUrl();
// -> file:/real/path/to/file// or// -> ftp://username:password@host:port/path/to/file// or// ...

Get public url to a file

/** @var File $file */$url = $file->getPublicUrl();
// may return false|null if no public url is availableif ($url) {
header('Location: ' . $url);
}

Supported filesystems

Local filesystem

Allow access to the local filesystem.

useBit3\Filesystem\Local\LocalFilesystem;
useBit3\Filesystem\Iterator\RecursiveFilesystemIterator;
useRecursiveTreeIterator;
// access the filesystem$fs = newLocalFilesystem('/path/to/directory');
// create a filesystem iterator$filesystemIterator = newRecursiveFilesystemIterator($root, FilesystemIterator::CURRENT_AS_BASENAME);
// create a tree iterator$treeIterator = newRecursiveTreeIterator($filesystemIterator);
// output the filesystem treeforeach ($treeIteratoras$path) {
echo$path . "\n";
}

The LocalFilesystem constructor accept a base path to the root directory and an optional PublicUrlProvider as second argument. All files from the LocalFilesystem are relative to the base path, even absolute files.

Merged filesystem

A merged filesystem is similar to the union mount. With the merged filesystem several other filesystems can be mounted into a virtual structure.

useBit3\Filesystem\Merged\MergedFilesystem;
useBit3\Filesystem\Local\LocalFilesystem;
useBit3\Filesystem\Iterator\RecursiveFilesystemIterator;
useRecursiveTreeIterator;
// create a merged filesystem$fs = newMergedFilesystem();
// mount some other filesystems into the structure$fs->mount('/home', newLocalFilesystem('/path/to/directory'));
$fs->mount('/remote/server', newLocalFilesystem('/other/path'));
$fs->mount('/tmp', newLocalTemporaryFilesystem('/tmp'));
// create a filesystem iterator$filesystemIterator = newRecursiveFilesystemIterator($root, FilesystemIterator::CURRENT_AS_BASENAME);
// create a tree iterator$treeIterator = newRecursiveTreeIterator($filesystemIterator);
// output the filesystem treeforeach ($treeIteratoras$path) {
echo$path . "\n";
}

The MergedFilesystem constructor accept an optional filesystem object as root (/) filesystem.

FTP filesystem

The FTPFilesystem allow access to an ftp server.

useBit3\Filesystem\FTP\FTPFilesystemConfig;
useBit3\Filesystem\FTP\FTPFilesystem;
useBit3\Filesystem\Iterator\RecursiveFilesystemIterator;
useRecursiveTreeIterator;
// create a ftp configuration$config = newFTPFilesystemConfig('example.com');
$config->setPassiveMode(true);
$config->setUsername('user');
$config->setPassword('password');
$config->setPath('/path/on/the/ftp');
// access the filesystem$fs = newFTPFilesystem($config);
// create a filesystem iterator$filesystemIterator = newRecursiveFilesystemIterator($root, FilesystemIterator::CURRENT_AS_BASENAME);
// create a tree iterator$treeIterator = newRecursiveTreeIterator($filesystemIterator);
// output the filesystem treeforeach ($treeIteratoras$path) {
echo$path . "\n";
}

The FTPFilesystem constructor accept an instance of FTPFilesystemConfig and an optional PublicUrlProvider as second argument. The FTPFilesystemConfig object is used, to setup the ftp configuration. The instance can be reused for several FTPFilesystem instantiations.

SSH Filesystem

in work...