README

This package contains a static wrapper around the symfony file system component with some additional features. Since version 5.3 it also contains an extension for the Path utility, and replaces Neunerlei/path-util.

Installation

Install this package using composer:

composer require neunerlei/filesystem

Filesystem Utility

The filesystem class can be found at Neunerlei\FileSystem\Fs.

getFs()

Returns the singleton instance of the symfony file system class

use Neunerlei\FileSystem\Fs;
// Access the symfony methods as you would normally
Fs::getFs()->isAbsolutePath("...");

copy()

Copies a file or a directory. If the target file is older than the origin file, it's always overwritten.

use Neunerlei\FileSystem\Fs;
// Copy a file
Fs::copy("/path/file.txt", "/anotherPath/file.txt");

// Copy / mirror a directory
Fs::copy("/path/to/directory", "/anotherPath");

mkdir()

Creates a directory recursively.

use Neunerlei\FileSystem\Fs;
Fs::mkdir("/create/directory/recursively");

exists()

Checks the existence of files or directories.

use Neunerlei\FileSystem\Fs;
Fs::exists("/check/existence.txt"); // TRUE|FALSE

isReadable()

Tells whether a file or list of files exists and is readable.

use Neunerlei\FileSystem\Fs;
Fs::isReadable("/check/readability.txt"); // TRUE|FALSE

isWritable()

Tells whether a file or list of files exists and is writable.

use Neunerlei\FileSystem\Fs;
Fs::isWritable("/check/writeability.txt"); // TRUE|FALSE

isFile()

Tells whether a file or list of paths exists and contains only files

use Neunerlei\FileSystem\Fs;
Fs::isFile("/check/if/fileExists.txt"); // TRUE|FALSE

isDir()

Tells whether a file or list of paths exists and contains only directories

use Neunerlei\FileSystem\Fs;
Fs::isDir("/check/if/directoryExists.txt"); // TRUE|FALSE

touch()

Sets access and modification time of file.

NOTE: You can also pass DateTime objects as timestamps!

use Neunerlei\FileSystem\Fs;
Fs::touch("/check/touchy.txt", new DateTime());

remove()

Removes files or directories.

use Neunerlei\FileSystem\Fs;
Fs::remove("/path/to/remove.txt");

flushDirectory()

Removes all contents from a given directory without removing the element itself.

use Neunerlei\FileSystem\Fs;
Fs::flushDirectory("/path/to/clean");

getDirectoryIterator()

Helper to create a directory iterator either for a single folder or recursively. Dots will automatically be skipped. It can also find only files matching a regular expression. By default the folder will come after the children, which can be toggled using the options.

use Neunerlei\FileSystem\Fs;
// Traverse the direct children of a directory
Fs::getDirectoryIterator("/path/to/iterate");

// Traverse a directory recursively
Fs::getDirectoryIterator("/path/to/iterate", true);

// Filter by regex
Fs::getDirectoryIterator("/path/to/iterate", true, ["regex" => "/\.txt$/"]);

// Return the folders before returning the children
Fs::getDirectoryIterator("/path/to/iterate", true, ["dirFirst"]);

rename()

Allows you to rename a file or directory

use Neunerlei\FileSystem\Fs;
Fs::rename("/path/a", "/path/b");

getPermissions()

Returns the unix file permissions for a given file like "0777" as a string.

use Neunerlei\FileSystem\Fs;
Fs::getPermissions("/file/with/full/access.txt"); // "0777"
Fs::getPermissions("/file/with/read/access.txt"); // "0222"

setPermissions()

Can be used to set the unix permissions for a file or folder.

use Neunerlei\FileSystem\Fs;
Fs::setPermissions("/file/path.txt", 0222);
Fs::setPermissions("/directory", 0222);

getOwner()

Returns the numeric unix user id for the given file or folder

use Neunerlei\FileSystem\Fs;
Fs::getOwner("/file/access.txt"); // 1000

setOwner()

Can be used to update the owner of a given file or folder

use Neunerlei\FileSystem\Fs;
Fs::setOwner("/file/access.txt", 1001);

getGroup()

Returns the numeric unix user group for the given filename

use Neunerlei\FileSystem\Fs;
Fs::getGroup("/file/access.txt"); // 5

setGroup()

Can be used to update the group of a given file or folder

use Neunerlei\FileSystem\Fs;
Fs::setGroup("/file/access.txt", 10);

readFile()

A wrapper around file_get_contents which reads the contents, but handles unreadable or non existing files with speaking exceptions.

use Neunerlei\FileSystem\Fs;
$content = Fs::readFile("/file/access.txt");

readFileAsLines()

A wrapper around file() which handles non existing, or unreadable files with speaking exceptions.

use Neunerlei\FileSystem\Fs;
$lines = Fs::readFileAsLines("/file/access.txt");

writeFile()

Writes the given content into a file on your file system.

use Neunerlei\FileSystem\Fs;
Fs::writeFile("/file.txt", "myContent");

appendToFile()

Appends content to an existing file. By default all content will be added on a new line.

use Neunerlei\FileSystem\Fs;

// Add "myContent" as a new line to the file
Fs::appendToFile("/file.txt", "myContent");

// Add "myContent" directly at the end
Fs::appendToFile("/file.txt", "myContent", false);

Path Utility

The filesystem class can be found at Neunerlei\FileSystem\Path.

use Neunerlei\FileSystem\Path;

// These methods are added by this fork
// ==========================================================
echo Path::unifySlashes("\\foo/bar\\baz");
// => /foo/bar/baz (on linux) or \foo\bar\baz (on windows)

echo Path::unifyPath("\\foo/bar\\baz");
// => /foo/bar/baz/ (on linux) or \foo\bar\baz\ (on windows)

echo Path::classBasename(\Neunerlei\FileSystem\Path::class);
// => Path

echo Path::classNamespace(\Neunerlei\FileSystem\Path::class);
// => Neunerlei\FileSystem

$link = Path::makeUri();
// => Returns a new Uri object -> See "URI" Section for details.

// Those methods were already in the base implementation
// ==========================================================
echo Path::canonicalize('/var/www/vhost/webmozart/../config.ini');
// => /var/www/vhost/config.ini

echo Path::canonicalize('C:\Programs\Webmozart\..\config.ini');
// => C:/Programs/config.ini

echo Path::canonicalize('~/config.ini');
// => /home/webmozart/config.ini

echo Path::makeAbsolute('config/config.yml', '/var/www/project');
// => /var/www/project/config/config.yml

echo Path::makeRelative('/var/www/project/config/config.yml', '/var/www/project/uploads');
// => ../config/config.yml

$paths = array(
    '/var/www/vhosts/project/httpdocs/config/config.yml',
    '/var/www/vhosts/project/httpdocs/images/banana.gif',
    '/var/www/vhosts/project/httpdocs/uploads/../images/nicer-banana.gif',
);

Path::getLongestCommonBasePath($paths);
// => /var/www/vhosts/project/httpdocs

Path::getFilename('/views/index.html.twig');
// => index.html.twig

Path::getFilenameWithoutExtension('/views/index.html.twig');
// => index.html

Path::getFilenameWithoutExtension('/views/index.html.twig', 'html.twig');
Path::getFilenameWithoutExtension('/views/index.html.twig', '.html.twig');
// => index

Path::getExtension('/views/index.html.twig');
// => twig

Path::hasExtension('/views/index.html.twig');
// => true

Path::hasExtension('/views/index.html.twig', 'twig');
// => true

Path::hasExtension('/images/profile.jpg', array('jpg', 'png', 'gif'));
// => true

Path::changeExtension('/images/profile.jpeg', 'jpg');
// => /images/profile.jpg

Path::join('phar://C:/Documents', 'projects/my-project.phar', 'composer.json');
// => phar://C:/Documents/projects/my-project.phar/composer.json

Path::getHomeDirectory();
// => /home/webmozart

Running tests

Clone the repository
Install the dependencies with composer install
Run the tests with composer test

Special Thanks

Special thanks goes to the folks at LABOR.digital (which is the word german for laboratory and not the english "work" :D) for making it possible to publish my code online.

Postcardware

You're free to use this package, but if it makes it to your production environment I highly appreciate you sending me a postcard from your hometown, mentioning which of our package(s) you are using.

You can find my address here.

Thank you :D

neunerlei / filesystem

Maintainers

Details