Symfony Filesystem

https://github.com/symfony/filesystem
Admin
Symfony Filesystem provides basic utilities and tools for manipulating the filesystem, including...
Tokens:41,942
Snippets:416
Trust Score:9.5
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Symfony Filesystem

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Install the Symfony Filesystem component using Composer.

```bash
composer require symfony/filesystem
```

--------------------------------

### chmod() Parameters and Example

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Set file permissions using chmod(). The example shows how to apply a mode and umask to determine the effective permissions.

```php
chmod($files, $mode, $umask = 0o000, $recursive = false)
// Example: chmod($files, 0o777, 0o022) => effective: 0o755
```

--------------------------------

### UNIX File Permissions Examples

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Provides examples of standard octal notation for UNIX file permissions, illustrating common modes for files, directories, private files, and unrestricted access.

```php
// Standard octal notation
0o644  // rw-r--r-- (files)
0o755  // rwxr-xr-x (directories)
0o700  // rwx------ (private)
0o777  // rwxrwxrwx (unrestricted)
```

--------------------------------

### Syncing Directories with mirror() Options

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Provides an example of using the `mirror()` method with options to synchronize directories, including overwriting files, removing extra files, and copying symlink targets.

```php
// Sync directories with full cleanup
$filesystem->mirror(
    '/source',
    '/target',
    null,
    [
        'override' => true,      // Overwrite all files
        'delete' => true,        // Remove extra files in target
        'follow_symlinks' => true // Copy symlink targets
    ]
);
```

--------------------------------

### Error Handling

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Examples of how to catch exceptions thrown by the Filesystem component.

```APIDOC
## Error Handling

### Basic Try-Catch

Catches generic `IOException` for filesystem errors.

```php
use Symfony\Component\Filesystem\Exception\IOException;

try {
    $fs->copy($source, $target);
} catch (IOException $e) {
    echo $e->getMessage();
    echo $e->getPath();  // Affected file path
}
```

### Specific Exceptions

Catches specific exceptions like `FileNotFoundException`.

```php
use Symfony\Component\Filesystem\Exception\FileNotFoundException;
use Symfony\Component\Filesystem\Exception\IOException;

try {
    $fs->copy($source, $target);
} catch (FileNotFoundException $e) {
    // File doesn't exist
} catch (IOException $e) {
    // Other IO error
}
```

### Catch All Filesystem Exceptions

Catches any exception implementing `ExceptionInterface` from the filesystem component.

```php
use Symfony\Component\Filesystem\Exception\ExceptionInterface;

try {
    // ... operations
} catch (ExceptionInterface $e) {
    // Any filesystem error
}
```
```

--------------------------------

### Path Canonicalization: Root Handling Examples

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Shows how the Path::getRoot() method handles different root directory formats across various operating systems, including special cases for Windows drive letters and file URIs.

```php
// Different roots on different OSes
Path::getRoot("/var/www");        // => "/"
Path::getRoot("C:/Windows");      // => "C:/" (Windows only)
Path::getRoot("file:///tmp");     // => "file:///"
```

--------------------------------

### Mock Filesystem Operations in Tests

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Use the Filesystem class with temporary directories for testing. Set up a temporary directory in setUp and clean it up in tearDown to isolate test file operations.

```php
use Symfony\Component\Filesystem\Filesystem;

class FileProcessorTest extends TestCase {
    private Filesystem $filesystem;
    private string $testDir;
    
    protected function setUp(): void {
        $this->filesystem = new Filesystem();
        $this->testDir = sys_get_temp_dir() . '/test-' . uniqid();
        $this->filesystem->mkdir($this->testDir);
    }
    
    protected function tearDown(): void {
        $this->filesystem->remove($this->testDir);
    }
    
    public function testFileProcessing(): void {
        $file = $this->testDir . '/input.txt';
        $this->filesystem->dumpFile($file, 'test content');
        
        $content = $this->filesystem->readFile($file);
        $this->assertEquals('test content', $content);
    }
}
```

--------------------------------

### Path Conversion and Joining Utilities

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Provides examples of using the static `Path` class for common path manipulations. This includes converting between absolute and relative paths, and joining multiple path segments into a single, normalized path.

```php
use Symfony\Component\Filesystem\Path;

// Make path absolute relative to base
$absolute = Path::makeAbsolute(
    '../templates/base.html',
    '/app/views/pages'
);
// => "/app/templates/base.html"

// Make path relative
$relative = Path::makeRelative(
    '/var/www/app/config/db.php',
    '/var/www'
);
// => "app/config/db.php"

// Join segments
$path = Path::join('/var/www', 'app', 'config');
// => "/var/www/app/config"
```

--------------------------------

### Throwing Nullable Exceptions

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Provides examples of throwing custom exceptions like FileNotFoundException and IOException, demonstrating how to pass null for optional parameters such as the message or path.

```php
// FileNotFoundException with auto-generated message
throw new FileNotFoundException(null, 0, null, '/path/to/file');

// IOException with optional path
throw new IOException('Error occurred', 0, null, null);
```

--------------------------------

### Mirroring with Recursive Iterator

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

This example shows how to use the `mirror` method with a `RecursiveIteratorIterator` and `RecursiveDirectoryIterator` to efficiently copy directory contents. It utilizes flags like `SKIP_DOTS` for cleaner iteration.

```php
$flags = FilesystemIterator::SKIP_DOTS;
$iterator = new RecursiveIteratorIterator(
    new RecursiveDirectoryIterator($originDir, $flags),
    RecursiveIteratorIterator::SELF_FIRST
);

$filesystem->mirror($source, $target, $iterator);
```

--------------------------------

### Instantiate Filesystem and Path

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Instantiate the Filesystem component. The Path utility is static and does not require instantiation.

```php
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Filesystem\Path;

$fs = new Filesystem();
// Path is static - no instantiation needed
```

--------------------------------

### Basic Filesystem Operations

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Demonstrates basic filesystem operations like creating directories, copying files, and removing paths using the Filesystem class.

```php
use Symfony\Component\Filesystem\Filesystem;

$filesystem = new Filesystem();

// Create directory
$filesystem->mkdir('/path/to/directory');

// Copy file
$filesystem->copy('/source/file.txt', '/dest/file.txt');

// Remove
$filesystem->remove(['/path/1', '/path/2']);
```

--------------------------------

### File Permission Modes

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Demonstrates setting file permissions using octal notation for regular files, directories, private files, and all permissions. Also shows how to apply a umask to effective permissions.

```php
0o644  // rw-r--r-- (regular file)
0o755  // rwxr-xr-x (directory or executable)
0o600  // rw------- (private file)
0o777  // rwxrwxrwx (all permissions)
```

```php
$filesystem = new Filesystem();

// Readable by everyone, writable by owner only
$filesystem->chmod('/var/www/app/config/database.php', 0o644);

// Executable directory
$filesystem->chmod('/var/www/public', 0o755);

// Private directory
$filesystem->chmod('/var/www/private', 0o700);

// Apply umask
$filesystem->chmod('/var/www', 0o777, 0o022); // Effective: 0o755
```

--------------------------------

### Get File Extension

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Path.md

Retrieves the file extension from a path. Optionally converts the extension to lowercase.

```php
Path::getExtension("/path/file.txt");
// => "txt"

Path::getExtension("/path/file.TXT");
// => "TXT"

Path::getExtension("/path/file.TXT", true);
// => "txt"

Path::getExtension("/path/file");
// => ""
```

--------------------------------

### Get File Extension

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/README.md

Extracts the extension from a filename. Returns an empty string if the file has no extension.

```php
use Symfony\Component\Filesystem\Path;

$extension = Path::getExtension('/path/to/image.jpeg');
// $extension will be 'jpeg'
```

--------------------------------

### Directory Mirroring with Cleanup Options

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Illustrates how to synchronize the contents of one directory to another, with options to overwrite existing files, delete files in the target that are not in the source, and follow symbolic links. This is ideal for deployment or backup scenarios where a target directory needs to exactly match a source.

```php
$filesystem = new Filesystem();

// Sync directories: overwrite all, delete extras, follow symlinks
$filesystem->mirror(
    '/source',
    '/target',
    null,  // Use default recursive iterator
    [
        'override' => true,       // Overwrite newer files
        'delete' => true,         // Remove files not in source
        'follow_symlinks' => true // Copy symlink targets
    ]
);
```

--------------------------------

### Get Filename Without Extension

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/README.md

Extracts the filename from a path, excluding its extension. Returns the full filename if there is no extension.

```php
use Symfony\Component\Filesystem\Path;

$filename = Path::getFilenameWithoutExtension('/path/to/archive.tar.gz');
// $filename will be 'archive.tar'
```

--------------------------------

### Get Directory from Path

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/README.md

Extracts the directory part of a given path. Returns an empty string if the path has no directory component.

```php
use Symfony\Component\Filesystem\Path;

$directory = Path::getDirectory('/path/to/some/file.txt');
// $directory will be '/path/to/some'
```

--------------------------------

### Copying Files via Stream Wrappers

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Demonstrates copying files using supported stream wrappers like ftp:// and gs://, as well as reading local files using file://.

```php
$fs->copy('ftp://user:pass@host/file.txt', '/local/file.txt');
$fs->copy('gs://bucket/file.txt', '/local/file.txt');
$fs->readFile('file:///tmp/file.txt');
```

--------------------------------

### Get Directory from Path

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Path.md

Extract the directory part of a path using getDirectory. It handles various cases robustly and returns a canonical path.

```php
Path::getDirectory("/var/www/app/file.txt");
// => "/var/www/app"

Path::getDirectory("C:/symfony");
// => "C:/" (on Windows)

Path::getDirectory("symfony");
// => "" (relative path with no slashes)

Path::getDirectory("/");
// => "/"
```

--------------------------------

### Path Validation for Relative Paths

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Validate that both start and end paths are absolute before attempting to make a path relative. Throws `InvalidArgumentException` if paths are not absolute.

```php
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Filesystem\Path;
use Symfony\Component\Filesystem\Exception\InvalidArgumentException;

$filesystem = new Filesystem();

function safeMakePathRelative($end, $start) {
    if (!Path::isAbsolute($start)) {
        throw new InvalidArgumentException("Start path must be absolute: $start");
    }
    if (!Path::isAbsolute($end)) {
        throw new InvalidArgumentException("End path must be absolute: $end");
    }
    return $filesystem->makePathRelative($end, $start);
}

// Safe to call
$relative = safeMakePathRelative('/var/www/file.txt', '/var/www');
```

--------------------------------

### Import Filesystem and Path Classes

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Import the necessary classes for using the Filesystem and Path components. This is typically done at the beginning of your PHP file.

```php
use Symfony\Component\Filesystem\{Filesystem, Path};
use Symfony\Component\Filesystem\Exception\ExceptionInterface;
```

--------------------------------

### Get Home Directory

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Path.md

Retrieve the canonical path of the user's home directory using getHomeDirectory. This method is supported on UNIX and modern Windows versions.

```php
$home = Path::getHomeDirectory();
// On UNIX: "/home/username"
// On Windows: "C:/Users/username"
```

--------------------------------

### Handle InvalidArgumentException in makePathRelative

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/errors.md

Demonstrates how to catch InvalidArgumentException when using the makePathRelative method with an invalid start path. This exception is typically thrown when paths are not absolute or have different roots.

```php
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Filesystem\Exception\InvalidArgumentException;

$filesystem = new Filesystem();

try {
    // Error: start path is not absolute
    $filesystem->makePathRelative('/var/www/file.txt', 'relative/path');
} catch (InvalidArgumentException $e) {
    echo "Error: " . $e->getMessage();
}
```

--------------------------------

### Safe Rollback with Mirror

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Implement a safe deployment process by backing up the current version before mirroring a new one. If the deployment fails, restore the backup.

```php
use Symfony\Component\Filesystem\Filesystem;

$filesystem = new Filesystem();
$target = '/var/www/app';
$backup = "/var/www/app.backup." . date('Y-m-d-H-i-s');

// Backup current version
if ($filesystem->exists($target)) {
    $filesystem->mirror($target, $backup, null, [
        'delete' => false // Keep all files
    ]);
}

try {
    // Deploy new version
    $filesystem->mirror('/app/releases/v2.0', $target, null, [
        'override' => true,
        'delete' => true
    ]);
} catch (IOException $e) {
    // Restore backup
    $filesystem->mirror($backup, $target, null, [
        'override' => true,
        'delete' => true
    ]);
    throw new Exception("Deployment failed, restored backup", 0, $e);
}
```

--------------------------------

### Configuring mirror() Method Options

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Illustrates the associative array of options available for the `mirror()` method, including `override`, `follow_symlinks`, and `delete`.

```php
$options = [
    'override' => bool,
    'follow_symlinks' => bool,
    'delete' => bool,
];

$filesystem->mirror($source, $target, null, $options);
```

--------------------------------

### makePathRelative()

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Filesystem.md

Converts an absolute path to a relative path relative to a given starting path. Both paths must be absolute. Handles Windows drive letters and cross-platform path separators.

```APIDOC
## makePathRelative()

### Description
Converts an absolute path to a relative path relative to a given starting path. Both paths must be absolute. Handles Windows drive letters and cross-platform path separators.

### Method
`public function makePathRelative(string $endPath, string $startPath): string`

### Parameters
#### Path Parameters
- **endPath** (string) - Required - The absolute path to convert to relative
- **startPath** (string) - Required - The absolute starting path (reference point)

### Return
string - The relative path from $startPath to $endPath

### Throws
- `InvalidArgumentException` - When either path is not absolute

### Example
```php
$filesystem = new Filesystem();

// Make a path relative
$relative = $filesystem->makePathRelative('/var/www/app/views', '/var/www');
// => 'app/views/'

// Go up directories
$relative = $filesystem->makePathRelative('/var/www/file.txt', '/var/www/app');
// => '../file.txt/'
```
```

--------------------------------

### Import Filesystem Class

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Filesystem.md

Import the Filesystem class to use its methods.

```php
use Symfony\Component\Filesystem\Filesystem;
```

--------------------------------

### Instantiate Filesystem Class

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Instantiate the Filesystem class to perform high-level filesystem operations.

```php
$filesystem = new Filesystem();
```

--------------------------------

### Get Root Directory of Path

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Path.md

Use getRoot to find the root directory of a path. It correctly handles stream schemes and Windows drive letters, returning an empty string for relative paths.

```php
Path::getRoot("/var/www/app");
// => "/"

Path::getRoot("C:/Windows");
// => "C:/"

Path::getRoot("file:///tmp");
// => "file:////"

Path::getRoot("relative/path");
// => ""
```

--------------------------------

### Catch All Filesystem Exceptions

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Illustrates catching all filesystem-related exceptions by implementing the ExceptionInterface.

```php
use Symfony\Component\Filesystem\Exception\ExceptionInterface;

try {
    // ... operations
} catch (ExceptionInterface $e) {
    // Any filesystem error
}
```

--------------------------------

### Get Normalized Windows Root Path

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Retrieve the normalized root path of a Windows drive using the Path::getRoot method. This ensures consistent path handling across different environments.

```php
use Symfony\Component\Filesystem\Path;

$root = Path::getRoot('C:\\Windows\\System32');
// => 'C:/' (normalized)
```

--------------------------------

### Create Directory

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Creates a directory. Can create multiple directories at once or specify permissions.

```php
$fs->mkdir('/path/to/dir');
$fs->mkdir(['/path/1', '/path/2']);  // Multiple
$fs->mkdir('/path', 0o755);  // With permissions
```

--------------------------------

### Convert Absolute Path to Relative Path

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Filesystem.md

Use makePathRelative to convert an absolute path to a relative one based on a starting path. Both paths must be absolute. Handles Windows drive letters and cross-platform separators.

```php
$filesystem = new Filesystem();

// Make a path relative
$relative = $filesystem->makePathRelative('/var/www/app/views', '/var/www');
// => 'app/views/'

// Go up directories
$relative = $filesystem->makePathRelative('/var/www/file.txt', '/var/www/app');
// => '../file.txt/'
```

--------------------------------

### Catch Specific Exceptions (FileNotFoundException, IOException)

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/errors.md

Shows how to catch specific filesystem exceptions like FileNotFoundException and IOException. This allows for granular error handling based on the type of filesystem operation failure.

```php
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Filesystem\Exception\FileNotFoundException;
use Symfony\Component\Filesystem\Exception\IOException;

$filesystem = new Filesystem();

try {
    $filesystem->copy($source, $target);
} catch (FileNotFoundException $e) {
    // Handle missing files specifically
    echo "Source file missing: " . $e->getPath();
} catch (IOException $e) {
    // Handle other IO errors
    echo "IO Error: " . $e->getMessage();
    if ($path = $e->getPath()) {
        echo "Affected path: " . $path;
    }
}
```

--------------------------------

### Create Symbolic Link or Copy Directory on Windows

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Filesystem.md

Use `symlink()` to create symbolic links. On Windows, if `copyOnWindows` is `true`, it copies the directory instead of creating a symlink. The target directory is created if it doesn't exist.

```php
$filesystem = new Filesystem();

// Create a symbolic link
$filesystem->symlink('/path/to/origin', '/path/to/symlink');

// On Windows, copy instead of creating symlink
$filesystem->symlink('/path/to/origin', '/path/to/copy', true);
```

--------------------------------

### Efficient Batch File Removal with Generators

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Process multiple paths efficiently using iterables like generators for memory efficiency. This example shows how to remove a large number of log files without loading all their paths into memory at once.

```php
$filesystem = new Filesystem();

// Generators for memory efficiency
function logFiles() {
    for ($i = 1; $i <= 1000; $i++) {
        yield "/var/log/app_$i.log";
    }
}

// Process all logs without loading them all at once
$filesystem->remove(logFiles());
```

--------------------------------

### Basic Path Operations

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Demonstrates basic path manipulation using static methods from the Path class.

```php
use Symfony\Component\Filesystem\Path;

$absolute = Path::makeAbsolute('../style.css', '/app/views');
$relative = Path::makeRelative('/app/config/db.php', '/app');
```

--------------------------------

### Progress Tracking during Directory Mirroring

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Track progress during directory mirroring operations by using a custom iterator that counts processed files. This example defines a `ProgressIterator` to echo progress updates every 100 files processed during a mirror operation.

```php
use RecursiveDirectoryIterator;
use RecursiveIteratorIterator;
use FilesystemIterator;

$filesystem = new Filesystem();

// Create custom iterator to track progress
class ProgressIterator extends RecursiveIteratorIterator {
    private $count = 0;
    
    public function next(): void {
        parent::next();
        if (++$this->count % 100 === 0) {
            echo "Processed $this->count files\n";
        }
    }
}

$flags = FilesystemIterator::SKIP_DOTS;
$iterator = new ProgressIterator(
    new RecursiveDirectoryIterator('/source', $flags)
);

$filesystem->mirror('/source', '/target', $iterator, [
    'delete' => true,
    'override' => true
]);
```

--------------------------------

### Path Normalization for UNIX and Windows

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Demonstrates how Path::normalize handles backslashes differently on UNIX and Windows systems, preserving them on UNIX and converting them to forward slashes on Windows.

```php
// UNIX: Backslashes preserved as valid filename characters
Path::normalize("/path\\to\\file");  // => "/path\\to\\file"

// Windows: Backslashes converted to forward slashes
Path::normalize("C:\\Users\\file");  // => "C:/Users/file"
```

--------------------------------

### Handling Resource Types in File Operations

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Shows how methods like dumpFile can accept either a string or a file resource (handle) as input for writing content to a file. Demonstrates reading from a resource and writing a JSON string.

```php
$filesystem = new Filesystem();

// From resource
$handle = fopen('/path/source.txt', 'r');
$filesystem->dumpFile('/path/target.txt', $handle);
fclose($handle);

// From string
$filesystem->dumpFile('/path/config.json', json_encode(['key' => 'value']));
```

--------------------------------

### Windows Symlink Creation Handling

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Handles Windows-specific path conversion for symlinks and offers a fallback to copy if requested.

```php
if (DIRECTORY_SEPARATOR === \'\\') {
    // Convert to backslashes for Windows
    $originDir = strtr($originDir, \'/', \'\\');
    $targetDir = strtr($targetDir, \'/', \'\\');
    
    if ($copyOnWindows) {
        // User wants copy instead of symlink
        $this->mirror($originDir, $targetDir);
        return;
    }
}
```

--------------------------------

### Batch Operations for Directories and Files

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Shows how to efficiently create multiple directories or remove multiple files using a single method call by passing an array of paths. This is useful for bulk management tasks, simplifying code and potentially improving performance.

```php
$filesystem = new Filesystem();

// Create multiple directories
$filesystem->mkdir([
    '/app/cache',
    '/app/logs',
    '/app/sessions'
]);

// Remove multiple files
$filesystem->remove([
    '/tmp/cache.bin',
    '/tmp/session.dat',
    '/tmp/upload_dir'
]);
```

--------------------------------

### Create Directory

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Filesystem.md

Creates a single directory or multiple directories recursively. Existing directories are skipped.

```php
$filesystem->mkdir('/path/to/new/directory');
```

```php
$filesystem->mkdir(['/path/one', '/path/two']);
```

```php
$filesystem->mkdir('/path/restricted', 0o755);
```

--------------------------------

### tempnam() Stream Wrapper Support Logic

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Illustrates the logic for creating temporary files, supporting both local 'file://' and remote streams. It prioritizes built-in tempnam for local files and falls back to manual creation with atomic checks for others.

```php
[$scheme, $hierarchy] = getSchemeAndHierarchy($dir);

// Use built-in tempnam for local files
if ((null === $scheme || 'file' === $scheme || 'gs' === $scheme) && '' === $suffix) {
    if ($tmpFile = tempnam($hierarchy, $prefix)) {
        return (null !== $scheme && 'gs' !== $scheme) ? "$scheme://$tmpFile" : $tmpFile;
    }
}

// Manual creation for remote streams or custom suffixes
for ($i = 0; $i < 10; ++$i) {
    $tmpFile = $dir.'/'.$prefix.bin2hex(random_bytes(4)).$suffix;
    
    // Atomic check + create with 'x+' mode (fail if exists)
    if ($handle = fopen($tmpFile, 'x+')) {
        fclose($handle);
        return $tmpFile;
    }
}
```

--------------------------------

### Handle IO Exceptions

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Demonstrates basic try-catch block for handling IOExceptions, which include the error message and the affected file path.

```php
use Symfony\Component\Filesystem\Exception\IOException;

try {
    $fs->copy($source, $target);
} catch (IOException $e) {
    echo $e->getMessage();
    echo $e->getPath();  // Affected file path
}
```

--------------------------------

### Dump File to User Home Directory

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

The Filesystem::dumpFile method supports path expansion, allowing you to directly write to files in the user's home directory using the '~' shortcut.

```php
$filesystem = new Filesystem();
$filesystem->dumpFile('~/.bashrc', $bashrcContent);
```

--------------------------------

### Smart Symlink Creation with Fallback

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Attempt to create a symbolic link and fall back to copying the directory contents if symlinking fails, particularly useful on Windows where symlink creation might require elevated privileges.

```php
$filesystem = new Filesystem();

// Try symlink, fall back to copy on Windows if needed
$sourceDir = '/path/to/vendor/library';
$targetDir = '/app/lib/library';

try {
    $filesystem->symlink($sourceDir, $targetDir);
} catch (IOException $e) {
    // Windows without admin rights, copy instead
    if (PHP_OS_FAMILY === 'Windows') {
        $filesystem->mirror($sourceDir, $targetDir);
    } else {
        throw;
    }
}
```

--------------------------------

### Create Directory

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/README.md

Creates a directory. The parent directories are created automatically if they don't exist. Use for ensuring directory existence.

```php
use Symfony\Component\Filesystem\Filesystem;

$filesystem = new Filesystem();
$filesystem->mkdir('/path/to/new-directory');
```

--------------------------------

### touch()

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Filesystem.md

Sets the access and modification times for one or more files. If a file does not exist, it will be created.

```APIDOC
## touch()

### Description
Sets access and modification time of one or more files. Creates the file if it doesn't exist.

### Method
POST

### Endpoint
/filesystem/touch

### Parameters
#### Path Parameters
- **files** (string|iterable) - Required - One or more file paths to touch

#### Query Parameters
- **time** (int|null) - Optional - Modification time as Unix timestamp; current time if null
- **atime** (int|null) - Optional - Access time as Unix timestamp; current time if null

### Request Example
```json
{
  "files": "/path/to/file.txt",
  "time": 1704067200,
  "atime": 1704067200
}
```

### Response
#### Success Response (200)
- **void** - No content on success.

#### Response Example
```json
null
```

**Throws:**
- `IOException` - When touch operation fails
```

--------------------------------

### Cross-platform Filesystem Operations

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Illustrates cross-platform compatibility for filesystem operations and path normalization.

```php
// Works the same on Windows and UNIX
$filesystem = new Filesystem();
$filesystem->copy('source.txt', 'dest.txt');
$filesystem->mkdir(['dir1', 'dir2']);

// Path methods normalize automatically
Path::canonicalize("..\\css\\./style.css");  // Works on any OS
// => "../css/style.css"
```

--------------------------------

### Filesystem Class API

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/README.md

Detailed API documentation for the Filesystem class, including 24 methods for various file and directory operations such as copy, dumpFile, appendToFile, readFile, touch, mkdir, remove, mirror, exists, symlink, hardlink, readlink, chmod, chown, chgrp, rename, makePathRelative, isAbsolutePath, and tempnam.

```APIDOC
## Filesystem Class Methods

This section details the API for the Filesystem class, which provides a comprehensive set of tools for interacting with the filesystem.

### File Operations

- **copy(string $source, string $destination, bool $overwrite = false): void**
  - Description: Copies a file from a source to a destination. Optionally overwrites the destination if it exists.
  - Parameters:
    - `source` (string): The path to the source file.
    - `destination` (string): The path to the destination file.
    - `overwrite` (bool): Whether to overwrite the destination if it exists. Defaults to false.
  - Throws: `IOExceptionInterface` if the copy operation fails.

- **dumpFile(string $path, string $content): void**
  - Description: Dumps content into a file. Creates the file if it does not exist, and overwrites it if it does.
  - Parameters:
    - `path` (string): The path to the file.
    - `content` (string): The content to write to the file.
  - Throws: `IOExceptionInterface` if the dump operation fails.

- **appendToFile(string $path, string $content): void**
  - Description: Appends content to a file. Creates the file if it does not exist.
  - Parameters:
    - `path` (string): The path to the file.
    - `content` (string): The content to append to the file.
  - Throws: `IOExceptionInterface` if the append operation fails.

- **readFile(string $path): string**
  - Description: Reads the content of a file.
  - Parameters:
    - `path` (string): The path to the file.
  - Returns: The content of the file as a string.
  - Throws: `FileNotFoundException` if the file does not exist, or `IOExceptionInterface` if reading fails.

- **touch(string $path): void**
  - Description: Updates the access and modification times of a file. Creates the file if it does not exist.
  - Parameters:
    - `path` (string): The path to the file.
  - Throws: `IOExceptionInterface` if the touch operation fails.

### Directory Operations

- **mkdir(string $path): void**
  - Description: Creates a directory. Creates parent directories as needed.
  - Parameters:
    - `path` (string): The path to the directory to create.
  - Throws: `IOExceptionInterface` if the directory creation fails.

- **remove(string $path): void**
  - Description: Removes a file or a directory recursively.
  - Parameters:
    - `path` (string): The path to the file or directory to remove.
  - Throws: `IOExceptionInterface` if the removal fails.

- **mirror(string $source, string $destination, array $options = []): void**
  - Description: Mirrors a directory from a source to a destination. Options can control behavior like deletion of non-existent files in the destination.
  - Parameters:
    - `source` (string): The path to the source directory.
    - `destination` (string): The path to the destination directory.
    - `options` (array): An array of options to control the mirroring process.
  - Throws: `IOExceptionInterface` if the mirroring fails.

- **exists(string $path): bool**
  - Description: Checks if a file or directory exists.
  - Parameters:
    - `path` (string): The path to check.
  - Returns: True if the path exists, false otherwise.

### Link Operations

- **symlink(string $target, string $link): void**
  - Description: Creates a symbolic link.
  - Parameters:
    - `target` (string): The target of the symbolic link.
    - `link` (string): The path where the symbolic link will be created.
  - Throws: `IOExceptionInterface` if the symlink creation fails.

- **hardlink(string $source, string $destination): void**
  - Description: Creates a hard link.
  - Parameters:
    - `source` (string): The path to the source file.
    - `destination` (string): The path where the hard link will be created.
  - Throws: `IOExceptionInterface` if the hardlink creation fails.

- **readlink(string $path): string**
  - Description: Reads the target of a symbolic link.
  - Parameters:
    - `path` (string): The path to the symbolic link.
  - Returns: The target of the symbolic link.
  - Throws: `IOExceptionInterface` if reading the link fails.

### Permission Operations

- **chmod(string $path, int $mode): void**
  - Description: Changes the mode (permissions) of a file or directory.
  - Parameters:
    - `path` (string): The path to the file or directory.
    - `mode` (int): The new mode (permissions) in octal format.
  - Throws: `IOExceptionInterface` if changing the mode fails.

- **chown(string $path, int|string $user): void**
  - Description: Changes the owner of a file or directory.
  - Parameters:
    - `path` (string): The path to the file or directory.
    - `user` (int|string): The new owner's ID or username.
  - Throws: `IOExceptionInterface` if changing the owner fails.

- **chgrp(string $path, int|string $group): void**
  - Description: Changes the group of a file or directory.
  - Parameters:
    - `path` (string): The path to the file or directory.
    - `group` (int|string): The new group's ID or name.
  - Throws: `IOExceptionInterface` if changing the group fails.

### Path Operations

- **rename(string $path, string $newName): void**
  - Description: Renames a file or directory.
  - Parameters:
    - `path` (string): The current path.
    - `newName` (string): The new name for the file or directory.
  - Throws: `IOExceptionInterface` if renaming fails.

- **makePathRelative(string $path, string $basePath): string**
  - Description: Computes the path relative to a base path.
  - Parameters:
    - `path` (string): The path to make relative.
    - `basePath` (string): The base path.
  - Returns: The relative path.

- **isAbsolutePath(string $path): bool**
  - Description: Checks if a path is an absolute path.
  - Parameters:
    - `path` (string): The path to check.
  - Returns: True if the path is absolute, false otherwise.

- **tempnam(string $dir, string $prefix): string**
  - Description: Creates a temporary file with a unique name in the specified directory.
  - Parameters:
    - `dir` (string): The directory in which to create the temporary file.
    - `prefix` (string): The prefix for the temporary file name.
  - Returns: The path to the created temporary file.
  - Throws: `IOExceptionInterface` if the temporary file cannot be created.
```

--------------------------------

### mkdir()

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Filesystem.md

Creates one or more directories recursively. Existing directories are silently skipped. Custom file modes can be specified.

```APIDOC
## mkdir()

### Description
Creates one or more directories recursively. If a directory already exists, it is silently skipped.

### Method
POST

### Endpoint
/filesystem/mkdir

### Parameters
#### Path Parameters
- **dirs** (string|iterable) - Required - One or more directory paths to create

#### Query Parameters
- **mode** (int) - Optional - File mode in octal notation (default: 0o777)

### Request Example
```json
{
  "dirs": "/path/to/new/directory",
  "mode": 777
}
```

### Response
#### Success Response (200)
- **void** - No content on success.

#### Response Example
```json
null
```

**Throws:**
- `IOException` - When directory creation fails
```

--------------------------------

### Import Path Class

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Path.md

Import the Path class to use its static methods.

```php
use Symfony\Component\Filesystem\Path;
```

--------------------------------

### Safe Temporary File Creation using 'x+' Mode

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Ensures atomic creation of temporary files using fopen with 'x+' mode to prevent TOCTOU race conditions. Only one process can successfully create the file exclusively.

```php
// Atomic create with 'x+' mode
if ($handle = fopen($tmpFile, 'x+')) {
    fclose($handle);
    return $tmpFile;
}
```

--------------------------------

### Filesystem Links

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/MANIFEST.txt

Utilities for creating and reading symbolic and hard links.

```APIDOC
## Filesystem Links

### Description
Utilities for creating and reading symbolic and hard links.

### Methods
- `symlink(string $origin, string $link, ?array $node = null)`: Creates a symbolic link.
- `hardlink(string $origin, string $link, ?array $node = null)`: Creates a hard link.
- `readlink(string $path, ?array $node = null)`: Reads the target of a symbolic link.
```

--------------------------------

### Safe File Operations with Error Handling

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Demonstrates how to perform file operations like copying with specific exception handling for common issues such as FileNotFoundException and IOException. This pattern ensures that errors are caught and handled gracefully, providing informative messages about the failure and the affected path.

```php
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Filesystem\Exception\FileNotFoundException;
use Symfony\Component\Filesystem\Exception\IOException;

$filesystem = new Filesystem();

try {
    $filesystem->copy($source, $dest);
} catch (FileNotFoundException $e) {
    echo "Source not found: " . $e->getPath();
} catch (IOException $e) {
    echo "IO Error: " . $e->getMessage();
    if ($path = $e->getPath()) {
        echo " (Path: " . $path . ")";
    }
}
```

--------------------------------

### Catch Component Exceptions (ExceptionInterface)

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/errors.md

Demonstrates catching any filesystem component exception by using the ExceptionInterface. This is useful for a general error handling strategy for all filesystem-related errors.

```php
use Symfony\Component\Filesystem\Filesystem;
use Symfony\Component\Filesystem\Exception\ExceptionInterface;

$filesystem = new Filesystem();

try {
    // Multiple operations
    $filesystem->mkdir($dir);
    $filesystem->copy($source, $target);
    $filesystem->chmod($target, 0o644);
} catch (ExceptionInterface $e) {
    // Catches any filesystem component exception
    echo "Filesystem error: " . $e->getMessage();
}
```

--------------------------------

### Handling Component Exceptions with ExceptionInterface

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Shows how to catch any custom exception thrown by the Filesystem component using the `ExceptionInterface`. This is useful for general error handling.

```php
use Symfony\Component\Filesystem\Exception\ExceptionInterface;

try {
    // ... filesystem operations
} catch (ExceptionInterface $e) {
    // Handle any component exception
}
```

--------------------------------

### mirror() Options

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Configure the behavior of the mirror() function for overwriting, deleting, and following symlinks.

```php
[
    'override' => bool,        // false - overwrite even if newer
    'delete' => bool,          // false - delete files not in source
    'follow_symlinks' => bool, // false - copy targets instead of links
]
```

--------------------------------

### Atomic File Updates using dumpFile

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/index.md

Demonstrates how to perform atomic file updates using the `dumpFile` method. This method writes to a temporary file and then renames it to the target path, ensuring that the file is never in a partially written state, even if the process crashes.

```php
$filesystem = new Filesystem();

// dumpFile() uses temp file + rename for atomicity
$filesystem->dumpFile(
    '/etc/config.json',
    json_encode($config, JSON_PRETTY_PRINT)
);

// Safe even if process crashes — never partial writes
```

--------------------------------

### Filesystem Operations

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/MANIFEST.txt

Provides methods for common filesystem operations like creating directories, removing files/directories, mirroring directories, and checking for existence.

```APIDOC
## Filesystem Operations

### Description
Provides methods for common filesystem operations like creating directories, removing files/directories, mirroring directories, and checking for existence.

### Methods
- `mkdir(string $dir, int $mode = 0777, bool $recursive = false, ?array $node = null)`: Creates a directory.
- `remove(?string $files, ?array $node = null)`: Removes files or directories.
- `mirror(string $source, string $target, ?array $node = null, bool $copy = false)`: Mirrors a directory to another location.
- `exists(?string $files, ?array $node = null)`: Checks if files or directories exist.
```

--------------------------------

### Expand User Home Directory in Paths

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/advanced-patterns.md

Use Path::canonicalize to expand the user home directory shortcut (~) into its full path. This is useful for handling user-specific configuration files.

```php
use Symfony\Component\Filesystem\Path;

// Expands ~ to user home directory
$configPath = Path::canonicalize('~/.config/app/settings.json');
// => '/home/user/.config/app/settings.json'
```

--------------------------------

### Create Symbolic Link

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Creates a symbolic link. An option exists to copy symlink targets on Windows.

```php
$fs->symlink('/origin', '/link');
$fs->symlink('/origin', '/link', true);  // Copy on Windows
```

--------------------------------

### Octal Notation Reminders and Usage

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Provides reminders for common octal permission notations and demonstrates their use with the chmod() and mkdir() methods.

```php
0o644 = rw-r--r--
0o755 = rwxr-xr-x
0o700 = rwx------

// In context:
$fs->chmod('/file', 0o644);     // File: read+write for owner
$fs->chmod('/dir', 0o755);      // Directory: all users can read/enter
$fs->mkdir('/secure', 0o700);   // Private: owner only
```

--------------------------------

### Using File Flags with Filesystem Operations

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Demonstrates appending content to a file with an exclusive lock and mirroring a directory using custom iterator flags like SKIP_DOTS and FOLLOW_SYMLINKS.

```php
$filesystem = new Filesystem();

// Append with lock
$filesystem->appendToFile('/path/log.txt', 'entry', true);

// Mirror with custom iterator
$flags = \FilesystemIterator::SKIP_DOTS | \FilesystemIterator::FOLLOW_SYMLINKS;
$iterator = new \RecursiveIteratorIterator(
    new \RecursiveDirectoryIterator('/source', $flags),
    \RecursiveIteratorIterator::SELF_FIRST
);

$filesystem->mirror('/source', '/target', $iterator);
```

--------------------------------

### Create Symbolic Link

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/README.md

Creates a symbolic link. The target must exist. Use for creating shortcuts to files or directories.

```php
use Symfony\Component\Filesystem\Filesystem;

$filesystem = new Filesystem();
$filesystem->symlink('/path/to/target', '/path/to/symlink');
```

--------------------------------

### Stream Wrapper Support for File Operations

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Illustrates using PHP stream wrappers like FTP and Google Cloud Storage with filesystem operations such as copy and creating temporary files. Notes that local filesystem operations may not work with remote streams.

```php
// FTP
$filesystem->copy('ftp://user:pass@host/file.txt', '/local/file.txt');

// Google Cloud Storage
$tmpFile = $filesystem->tempnam('gs://bucket/path', 'prefix');

// Custom schemes
$filesystem->copy('phar://archive.phar/file.txt', '/local/file.txt');
```

--------------------------------

### Path Canonicalization: Windows Drive Letter Handling

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Illustrates special case handling for drive letters in Windows paths by the Path::getRoot() method, showing normalization for different syntaxes.

```php
// Drive letter handling
Path::getRoot("C:");      // => "C:/"  (special case)
Path::getRoot("C:/");     // => "C:/"  (normal case)
Path::getRoot("C:\\file"); // => "C:/"  (normalized)
```

--------------------------------

### Handle RuntimeException for getHomeDirectory

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/errors.md

Demonstrates catching RuntimeException when Path::getHomeDirectory() fails to determine the user's home directory. This can occur due to environment issues or disabled PHP functions.

```php
use Symfony\Component\Filesystem\Path;
use Symfony\Component\Filesystem\Exception\RuntimeException;

try {
    $home = Path::getHomeDirectory();
} catch (RuntimeException $e) {
    echo "Cannot determine home directory: " . $e->getMessage();
}
```

--------------------------------

### IOException with Detailed Error Information

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Throws an IOException that includes the action, involved paths, system error message, and the specific path for programmatic access.

```php
throw new IOException(
    sprintf('Failed to copy "%s" to "%s" because: ', 
        $originFile, $targetFile) . self::$lastError,
    0, 
    null, 
    $originFile  // Accessible via $e->getPath()
);
```

--------------------------------

### Handling I/O Exceptions with IOExceptionInterface

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/types.md

Demonstrates how to catch I/O-related exceptions and access the specific file path that caused the error using the `getPath()` method from `IOExceptionInterface`.

```php
use Symfony\Component\Filesystem\Exception\IOExceptionInterface;

try {
    $filesystem->remove($path);
} catch (IOExceptionInterface $e) {
    echo "Error at: " . $e->getPath();
}
```

--------------------------------

### Umask Application for File Permissions

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/implementation-details.md

Shows how a umask value is applied to a desired file mode to determine the effective permissions, using a bitwise AND operation with the inverted umask.

```php
$filesystem->chmod('/file', 0o777, 0o022);
// Effective mode: 0o777 & ~0o022 = 0o755
```

--------------------------------

### Create Temporary File

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/quick-reference.md

Creates a unique temporary file. Allows specifying the directory, prefix, and suffix for the filename.

```php
$tmpFile = $fs->tempnam(sys_get_temp_dir(), 'prefix-');
$tmpFile = $fs->tempnam('/app/tmp', 'upload-', '.tmp');
```

--------------------------------

### join()

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/api-reference/Path.md

Joins two or more path strings into a single canonical path. Empty parts are skipped. Handles stream schemes specially.

```APIDOC
## join()

### Description
Joins two or more path strings into a single canonical path. Empty parts are skipped. Handles stream schemes specially (allows leading "/" in subsequent parts).

### Method
`public static function join(string ...$paths): string`

### Parameters
#### Path Parameters
- **paths** (string...) - Required - Two or more path segments to join

### Response
#### Success Response
- **string** - The canonical joined path

### Request Example
```php
Path::join("/var", "www");
// => "/var/www"

Path::join("/var", "www", "app", "config");
// => "/var/www/app/config"

Path::join("C:/", "Users", "name");
// => "C:/Users/name" (on Windows)

Path::join("/base", "");
// => "/base" (empty parts skipped)

Path::join("phar://", "archive.phar", "file.txt");
// => "phar://archive.phar/file.txt"
```
```

--------------------------------

### Create Temporary File

Source: https://github.com/symfony/filesystem/blob/8.2/_autodocs/README.md

Creates a temporary file with a unique name. Ensures the file is created safely. Returns the path to the temporary file.

```php
use Symfony\Component\Filesystem\Filesystem;

$filesystem = new Filesystem();
$tempFile = $filesystem->tempnam(sys_get_temp_dir(), 'myapp_');
file_put_contents($tempFile, 'Temporary data');
```
Tokens:
Raw