README

Yii Files

The package provides useful methods to manage files and directories.

Requirements

PHP 8.0 or higher.

Installation

The package could be installed with composer:

composer require yiisoft/files --prefer-dist

FileHelper usage

FileHelper provides static methods you can use for various filesystem-related operations.

Working with directories

Ensure a directory exists:

use \Yiisoft\Files\FileHelper;

$directory = '/path/to/dir';
FileHelper::ensureDirectory($directory);

Ensure a directory exists, and permission specified is set:

use \Yiisoft\Files\FileHelper;

$directory = '/path/to/dir';
FileHelper::ensureDirectory($directory, 0775);

Remove a directory:

use \Yiisoft\Files\FileHelper;

$directory = '/path/to/dir';
FileHelper::removeDirectory($directory);

Remove everything within a directory but not directory itself:

use \Yiisoft\Files\FileHelper;

$directory = '/path/to/dir';
FileHelper::clearDirectory($directory, [
    'traverseSymlinks' => false,
    'filter' => (new PathMatcher())
        ->only('**.png', '**.jpg')
        ->except('**/logo.png'),
]);

Check if directory is empty:

use \Yiisoft\Files\FileHelper;

$directory = '/path/to/dir';
FileHelper::isEmptyDirectory($directory);

Copy directory:

use \Yiisoft\Files\FileHelper;

$source = '/path/to/source';
$destination = '/path/to/destination';
FileHelper::copyDirectory($source, $destination);

Additional options could be specified as third argument such as filter or copyEmptyDirectories. Check method phpdoc for a full list of options.

Copy file:

use \Yiisoft\Files\FileHelper;

$source = '/path/to/file';
$destination = '/path/to/destination';
FileHelper::copyFile($source, $destination);

Additional options could be specified as third argument such as beforeCopy or afterCopy. Check method phpdoc for a full list of options.

Search

Searching for files:

use \Yiisoft\Files\FileHelper;
use Yiisoft\Files\PathMatcher\PathMatcher;

$files = FileHelper::findFiles('/path/to/where/to/search', [
    'filter' => (new PathMatcher())
        ->only('**.png', '**.jpg')
        ->except('**/logo.png'),
]);

Searching for directories:

use \Yiisoft\Files\FileHelper;
use Yiisoft\Files\PathMatcher\PathMatcher;

$directories = FileHelper::findDirectories('/path/to/where/to/search', [
    'filter' => (new PathMatcher())->except('**meta'),
]);

Path matchers

A PathMatcherInterface can be passed by filter key in the options argument of a method. Both PathMatcher and CompositeMatcher implement the PathMatcherInterface. CompositeMatcher allows using a list of PathMatcherInterface sequentially.

Pattern matching is based on yiisoft/strings package and is described in its readme.

Other

Open a file. Same as PHP's fopen() but throwing exceptions.

use \Yiisoft\Files\FileHelper;

$handler = FileHelper::openFile('/path/to/file', 'rb');

Get last modified time for a directory or file:

use \Yiisoft\Files\FileHelper;

$directory = '/path/to/dir';
$time = FileHelper::lastModifiedTime($directory);

The method is different from PHP's filemtime() because it actually scans a directory and selects the largest modification time from all files.

Remove a file or symlink:

use \Yiisoft\Files\FileHelper;

$file = '/path/to/file.txt';
FileHelper::unlink($file);

Normalize a path:

use \Yiisoft\Files\FileHelper;

$path = '/home/samdark/./test/..///dev\yii/';
echo FileHelper::normalizePath($path);
// outputs:
// /home/samdark/dev/yii

Testing

Unit testing

The package is tested with PHPUnit. To run tests:

./vendor/bin/phpunit

Mutation testing

The package tests are checked with Infection mutation framework with Infection Static Analysis Plugin. To run it:

./vendor/bin/roave-infection-static-analysis-plugin

Static analysis

The code is statically analyzed with Psalm. To run static analysis:

./vendor/bin/psalm

License

The Yii Files is free software. It is released under the terms of the BSD License. Please see LICENSE for more information.

Maintained by Yii Software.

yiisoft / files

Maintainers

Details