usage.md

Usage

The package has three common usage styles: using FilesystemManager, working directly with mounts and paths, and plugging in a custom driver.

FilesystemManager

FilesystemManager is the main entry point. It combines a MountRegistry with a FilesystemDriverInterface implementation.

use CommonPHP\Filesystem\FilesystemManager;

$filesystem = FilesystemManager::native(__DIR__ . '/storage', 'storage');

$filesystem->write('reports/monthly.txt', 'Report contents');
$filesystem->append('reports/monthly.txt', PHP_EOL . 'Generated at ' . date(DATE_ATOM));

$contents = $filesystem->read('reports/monthly.txt');

Common Operations

$filesystem->exists('reports/monthly.txt');
$filesystem->isFile('reports/monthly.txt');
$filesystem->isDirectory('reports');

$filesystem->copy('reports/monthly.txt', 'reports/monthly-copy.txt');
$filesystem->move('reports/monthly-copy.txt', 'archive/monthly.txt');
$filesystem->delete('archive/monthly.txt');

$filesystem->createDirectory('exports');
$filesystem->deleteDirectory('exports');

Use deleteDirectory($path, recursive: true) for non-empty directories:

$filesystem->deleteDirectory('reports', recursive: true);

Metadata

$info = $filesystem->info('reports/monthly.txt');

echo $info->basename();
echo $info->extension();
echo $info->size;

The direct helpers are useful when only one value is needed:

$bytes = $filesystem->fileSize('reports/monthly.txt');
$modifiedAt = $filesystem->lastModified('reports/monthly.txt');
$checksum = $filesystem->checksum('reports/monthly.txt');

Directory Listings

$listing = $filesystem->list('reports', recursive: true);

foreach ($listing->files() as $file) {
    echo $file->path . ': ' . $file->size . PHP_EOL;
}

Listings return DirectoryListing, which is iterable, countable, sorted by logical path, and serializable through toArray().

Mount Registry Access

$filesystem->mounts()->setDefault('storage');

foreach ($filesystem->mounts() as $name => $mount) {
    echo $name . ' -> ' . $mount->primaryRoot() . PHP_EOL;
}

Use registry access for configuration and diagnostics. Most application code should stay on FilesystemManager.