Filesystem

File

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);

File::delete($file);

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);

Upload

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

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

Folder::create($path);

Folder::delete($path);

List Files

List Folders

// List folders of a folder
Folder::folders($dir);

// 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
Folder::files($dir);

// 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
Folder::items($dir);

// 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);

Path

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'

Permissions

// 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

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())
    {
        continue;
    }

    // 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)
    ->setExtension('ini|php')
    ->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

//or

(string) $path;

Path operation

Use chaining to operate path.

Child

$path->child('plugins')           // => /var/www/flower/plugins
    ->child('system/flower/lib'); // => /var/www/flower/plugins/system/flower/lib

Parent

$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)

Prefix

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.

$paths->setPrefix('/var/www/flower');

Iterator

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.

$paths->find('config.json');

$paths->findAll('config_*.json');

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.

Start

Core

MVC

Database

Services

Console

More

File

Write & Delete files

Move & Copy

Upload

File Name

Folder

Folder Operation

List Files

List Folders

List Files

List Files & Folders

Filesystem Class

Folder & File Operation

Path

Clean Path

Permissions

Finder

Simple Finder

Advanced Finder

Callback Finder

Advanced Comparator

PathLocator object

Create a new PathLocator

Convert to string

Path operation

Child

Parent

Prefix

Filesystem Operation

Get file info

Scan dir

Find files

Strict Mode

PathCollection object

Create a new PathCollection

Add with no key

Add with key name

Paths operations

Add path

Add paths

Remove path

Set prefix to all paths

Iterator

Find Files and Folders

Using it as array or string