File is a abstract class provides methods to operate files.

Write & Delete files

use Windwalker\Filesystem\File;

$file = '/path/to/file.txt';

File::write($file, $content);


Move & Copy

$src = '/path/to/file.txt';
$dest = '/path/of/new/file.txt';

// Move
File::move($src, $dest);

// Force move if file exsits
File::move($src, $dest, true);

// Copy
File::copy($src, $dest);

// Force copy if file exists
File::copy($src, $dest, true);


File::upload($src, $dest);

It is basically the wrapper for the PHP move_uploaded_file() function, but also does checks availability and permissions on both source and destination path.

File Name

Strip extension and get simple path:

$file = '/path/to/flower.txt';

$name = File::stripExtension($file); // /path/to/flower

Get extension:

$file = '/path/to/flower.txt';

File::getExtension($file); // txt

Get only file name.

$file = '/path/to/flower.txt';

File::getFilename($file); // flower.txt

Make file name safe to store.

$path = /path!/to/flower sakura.

File::makeSafe($path); // /path/to/flowersakura


Folder class help us operate folders and list files of a folder.

Folder Operation

Move & Copy

use Windwalker\Filesystem\Folder;

// Move folder
Folder::move($src, $dest);

// Force move if folder exists
Folder::move($src, $dest, true);

// Copy folder, will also copy all children
Folder::copy($src, $dest);

// Force copy if folder exists
Folder::copy($src, $dest, true);

Create & Delete



List Files

List Folders

// List folders of a folder

// List folders recursive
Folder::folders($dir, true);

// Path type: Get basename of every item
Folder::folders($dir, true, Folder::PATH_BASENAME);

Available path type:

  • Folder::PATH_ABSOLUTE - Absolute full path.
  • Folder::PATH_RELATIVE - Relative path from folder you scan.
  • Folder::PATH_BASENAME - The folder or file name.

List Files

// List files of a folder

// List files recursive
Folder::files($dir, true);

// Path type: Get basename of every item
Folder::files($dir, true, Folder::PATH_BASENAME);

List Files & Folders

// List files & folders of a folder

// List files & folders recursive
Folder::items($dir, true);

// Path type: Get basename of every item
Folder::items($dir, true, Folder::PATH_RELATIVE);

Filesystem Class

Filesystem class is a universal finder to find and operate folders & files.

Folder & File Operation

Filesystem move & copy method will auto detect the path is a folder or file, if is folder, it will call Folder::move(), if is file, it will call File::move().

// we don't need to know $src is a folder or file, Filesystem will detect it.
Filesystem::move($src, $dest);
Filesystem::copy($src, $dest);
Filesystem::delete($src, $dest);


A simple helper to handler some path string.

Clean Path

To strip additional / or \ in a path name.

$path = '/var/www\flower\sakura/olive';

$path = Path::clean($path); // Will be: '/var/www/flower/sakura/olive'


// Get by number
Path::getPermissions($path); // 755

// Get by string
Path::getPermissions($path, true); // dwrxwrx--x

// Set permissions, if is file, set to 644, if is folder set to 755
Path::setPermissions($path, '0644', '0755');

// Check can change Permissions
Path::canChmod($path); // Bool


Finder is the most powerful function of Filesystem, it provides an interface to let us use our logic to filter files.

Simple Finder

// Argument 2 is recursive
$folders = Filesystem::folders($path, true);
$files   = Filesystem::files($path, true);
$items   = Filesystem::items($path, true);

The simple finder are same as Folder, but it will not scan all files instantly, but returns an Iterator instead, we can send this iterator to foreach and do some filter by SplFileInfo object.

foreach ($items as $item)
    if ($item->isDir() || $item->isDot())

    // Do something

If you really need array not an Iterator, use Filesystem::iteratorToArray().

$folders = Filesystem::folder($path, true);

// To array
$folders = Filesystem::iteratorToArray($folders);

Or set argument 3 to TRUE.

$folders = Filesystem::folder($path, true, true);

is_array($folders); // TRUE

Advanced Finder

Find by name.

$files = Filesystem::find($path, 'flower.php');

Multiple name.

$files = Filesystem::find($path, array('flower.php', 'sakura.php'));

Find by regex

$files = Filesystem::find($path, '^[a-zA-Z0-9]');

Only find first matched.

$file = Filesystem::findOne($path, array('flower.php', 'sakura.php'));

Find recursive

$files = Filesystem::find($path, array('flower.php', 'sakura.php'), true);

To array

$files = Filesystem::find($path, array('flower.php', 'sakura.php'), true, true);

Callback Finder

Inject our filter logic to find files.

 * Files callback
 * @param \SplFileInfo                $current  Current item's value
 * @param string                      $key      Current item's key
 * @param \RecursiveDirectoryIterator $iterator Iterator being filtered
 * @return boolean   TRUE to accept the current item, FALSE otherwise
$closure = function($current, $key, $iterator)
    return Path::getPermissions($current->getPath()) >= 755;

$files = Filesystem::find($path, $closure, true);

Or create a FileComparator object.

use Windwalker\Filesystem\Comparator\FileComparatorInterface;

class MyComparator implements FileComparatorInterface
   public function compare($current, $key, $iterator)
       return Path::getPermissions($current->getPath()) >= 755;

$files = Filesystem::find($path, new MyComparator, true);

Advanced Comparator

We can create our own comparator like an finder object.

// This is just an example

$comparator = new MyAdvancedComparator;

$comparator->setTimeGreaterThan(new DataTime)
    ->setSize('< 2M')
    ->setPermission('>= 644');

$files = Filesystem::find($path, $comparator, true);

PathLocator object

A Path locator, help us locate a system path or relative path.

We can use this object to find files or list files, and also support using callback to filter files.

Create a new PathLocator

$path = new PathLocator('/var/www/flower');

Convert to string

echo $path


(string) $path;

Path operation

Use chaining to operate path.

$path->child('plugins')           // => /var/www/flower/plugins
    ->child('system/flower/lib'); // => /var/www/flower/plugins/system/flower/lib
$path->parent()       // => /var/www/flower/plugins/system/flower (Up one level)
    ->parent(2)       // => /var/www/flower/plugins               (Up 2 levels)
    ->parent('www');  // => /var/www                              (Find a parent and go this level)

Add a prefix of system path, we can change it, only when converting to string, the prefix will be added to path.

$path2 = new PathLocator('src/Sakura/Olive');

echo $path->addPrefix($_SERVER['DOCUMENT_ROOT']); // => /var/www/src/Sakura/Olive

Filesystem Operation

echo $path->isDir();  // true or false
echo $path->isFile(); // true or false
echo $path->exists(); // true or false
Get file info

This function has not prepared yet.

$path->getInfo();            // return SplFileInfo of current directory

$path->getInfo('index.php'); // return SplFileInfo of this file
Scan dir

Get Folders

$dirs = $path->getFolders([true to recrusive]);

foreach($dirs as $dir)
    echo $dir . '<br />'; // print all dir's name

Get Files

$files = $path->getFiles([true to recrusive]);

foreach($files as $file)
    echo $file->getPathname() . '<br />'; // print all file's name
Find files

Find by string or regex

echo $path->find('config.json');     // Find one file and return fileinfo object

echo $path->find(array('^config'));  // Find one file by regex

// Second argument set to TRUE for recursive
foreach($path->findAll(array('^config_*.json', '!^..'), true) as $file)
    // Find all files as array, param 2 to recursive

Find by callback

$callback = function($current, $key, $iterator)
    return return @preg_match('^Foo', $current->getFilename())  && ! $iterator->isDot();

foreach($path->findAll($callback, true) as $file)
    // ...

Find by Comparator

This comparator object may contain the filter logic, but not prepared yet.

$comparator = new FileComparator;

foreach($path->findAll(FileComparatorInterface $comparator, true) as $file)
    // ...

Strict Mode

This function not prepared yet.

$dl2 = new \DirectoryLocator($_SERVER['DOCUMENT_ROOT'] . '/src', true);
$dls->child('Campenont');        // throw PathNotExistsException();
$dls->child('../www/index.php'); // throw PathNotDirException();


PathCollection object

A collection of paths, we can put many paths to this object, and use it as array.

And we can use this collection to iterate all sub dirs and files, also find files.

The iterator will travel to every PathLocator in this collection object, and return an SplFileInfo for us.

Create a new PathCollection

Add with no key
$paths = new PathCollection(array(
    new PathLocator('templates/' . $template . '/html/' . $option),
    new PathLocator('Sakuras/' . $option . '/view/tmpl/'),
    'layouts/' . $option ,     // Auto convert to PathLocator
Add with key name
$paths = new PathColleciotn(array(
    'Template'  => new PathLocator('templates/' . $template . '/html/' . $option),
    'Sakura' => new PathLocator('Sakuras/' . $option . '/view/tmpl/'),
    'Layout'    => new PathLocator('layouts/' . $option)

Paths operations

Add path
$paths->addPath(new PathLocator('Foo'));        // No key name, will using number as key

$paths->addPath(new PathLocator('Foo'), 'Foo'); // With key name
Add paths
$paths->addPaths(array(new PathLocator('Bar'))); // Add by array
Remove path
$paths->removePath('Foo');  // Remove by key name
$paths->removePath(0);      // Remove by number
Set prefix to all paths

We can change this prefix, only when converting to string, the prefix will have been added to path.

// Prepend all path with a prefix path.



List all PathLocator

foreach($paths as $path)
    echo $path // print path string

Return a raw array

foreach($paths->toArray() as $path)
    echo $path // print path string

List all files and folders of all paths

foreach($paths->getAllChildren([true to recrusive]) as $file)
    echo $file // SplFileInfo

List all files

foreach($paths->getFiles([true to recrusive]) as $file)
    echo $file->getFilename() // SplFileInfo

List all folders

foreach($paths->getFolders([true to recrusive]) as $dir)
    echo $file->getPathname() // SplFileInfo

Find Files and Folders

Same as PathLocator, but return all paths' file & folders.



Using it as array or string

$cache  = new PathLocator($_SERVER['DOCUMENT_ROOT'] . '/cache');
$loader = new \Twig_Loader_Filesystem($paths);

$twig = new \Twig_Environment($loader, array(
    'cache' => (string) $cache,

If you found a typo or error, please help us improve this document.