#Files

Phuture\Coherence\Files

class Files extends StaticClass

Comprehensive file system utility class with file manipulation, searching, and information capabilities.

This utility class provides a complete toolkit for working with files and directories, combining file system manipulation, file searching, file information retrieval, MIME type detection, and file upload handling into a single cohesive interface.

Key features:

• File Manipulation: Copy, create, delete, move, read, and write files and directories
• Path Utilities: Normalize, join, and convert path separators across platforms
• File Searching: Find files and directories using glob-style patterns with optional recursion
• File Information: Retrieve size, extension, modification time, and other metadata
• MIME Type Detection: Identify file types using the system's MIME database
• File Uploads: Handle single and multiple file uploads from HTTP requests
• Directory Listing: List and filter directory contents
• Fluent Interface: Call Files::of() to obtain a chainable \Phuture\Coherence\Type\Files wrapper

#Methods

#append()

public static function append(string $path, string $content): void

Appends content to the end of a file, creating it if it does not exist.

When the file does not exist, it is created. Parent directories are created automatically when they do not exist.

Example:

1use Phuture\Coherence\Files;
2
3Files::write('/path/to/log.txt', 'First line');
4Files::append('/path/to/log.txt', 'Second line');

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file cannot be written

See also

• \Phuture\Coherence\Files::write()
• \Phuture\Coherence\Files::prepend()

#chgrp()

public static function chgrp(string $path, string|int $group): void

Changes the group ownership of a file or directory.

Example:

1use Phuture\Coherence\Files;
2
3Files::chgrp('/path/to/file.txt', 'www-data');
4Files::chgrp('/path/to/directory', 1000);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path does not exist or the group cannot be changed

See also

• \Phuture\Coherence\Files::chmod()
• \Phuture\Coherence\Files::chown()

#chmod()

public static function chmod(string $path, int $mode): void

Changes the permission mode of a file or directory.

Example:

1use Phuture\Coherence\Files;
2
3Files::chmod('/path/to/file.txt', 0644);
4Files::chmod('/path/to/directory', 0755);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path does not exist or permissions cannot be changed

See also

• \Phuture\Coherence\Files::chown()
• \Phuture\Coherence\Files::chgrp()
• \Phuture\Coherence\Files::makeWritable()

#chown()

public static function chown(string $path, string|int $user): void

Changes the owner of a file or directory.

Example:

1use Phuture\Coherence\Files;
2
3Files::chown('/path/to/file.txt', 'www-data');
4Files::chown('/path/to/directory', 1000);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path does not exist or the owner cannot be changed

See also

• \Phuture\Coherence\Files::chmod()
• \Phuture\Coherence\Files::chgrp()

#compress()

public static function compress(string $source, string $destination, CompressionFormat $format = CompressionFormat::Zip): void

Compresses a file or directory into an archive.

All three formats — Zip, Tar, and Gzip — support both files and directories as input. Zip creates a .zip archive, Tar creates an uncompressed .tar archive, and Gzip creates a GZIP-compressed TAR archive (.tar.gz). When no format is given, Zip is used by default.

The parent directory of $destination is created automatically when it does not already exist.

Example:

 1use Phuture\Coherence\Files;
 2use Phuture\Coherence\Enum\CompressionFormat;
 3
 4// ZIP (default) — compress a directory
 5Files::compress('/var/app/uploads', '/var/backups/uploads.zip');
 6
 7// TAR — archive without compression
 8Files::compress('/var/app/uploads', '/var/backups/uploads.tar', CompressionFormat::Tar);
 9
10// GZIP — compress as .tar.gz, supports directories too
11Files::compress('/var/app/uploads', '/var/backups/uploads.tar.gz', CompressionFormat::Gzip);

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — If the source path does not exist
• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be created or written

See also

• \Phuture\Coherence\Files::decompress()

#copy()

public static function copy(string $source, string $destination, bool $overwrite = true): void

Copies a file or an entire directory to a new location.

When copying a directory, all files and subdirectories within it are copied recursively. By default, existing files at the destination are overwritten. When $overwrite is false and the destination already exists, a \Phuture\Coherence\Exception\RuntimeException is thrown.

Example:

1use Phuture\Coherence\Files;
2
3Files::copy('/path/to/source.txt', '/path/to/destination.txt');
4Files::copy('/path/to/source_dir', '/path/to/destination_dir');
5Files::copy('/path/to/file.txt', '/path/to/existing.txt', overwrite: false);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the source does not exist or the destination cannot be written

See also

• \Phuture\Coherence\Files::move()

#create()

public static function create(string $path, int $mode = 0777): void

Creates a file or directory at the given path.

When the path ends with a directory separator (/ or \), a directory is created including all missing parent directories. Otherwise, an empty file is created using touch(), with parent directories created automatically when they do not exist. If the path already exists, this method does nothing.

Example:

1use Phuture\Coherence\Files;
2
3Files::create('/path/to/new/file.txt');      // creates empty file
4Files::create('/path/to/new/directory/');    // creates directory
5Files::create('/path/to/nested/dirs/', 0755); // creates directory with mode

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path cannot be created

See also

• \Phuture\Coherence\Files::delete()

#createTemporaryDirectory()

public static function createTemporaryDirectory(string $prefix = 'tmp_', int $mode = 0700, string $parentDirectory = ''): string

Creates a temporary directory with a unique name.

This method creates a new empty directory inside the system's temporary directory (or a custom directory you specify) with a unique name that avoids collisions. The directory name is generated using a prefix you provide combined with random characters, so multiple calls will always produce different directories.

Example:

 1use Phuture\Coherence\Files;
 2
 3$tempDir = Files::createTemporaryDirectory();
 4// Returns something like '/tmp/tmp_664b5a3c1f8d2'
 5
 6$customDir = Files::createTemporaryDirectory(prefix: 'myapp_');
 7// Returns something like '/tmp/myapp_664b5a3c1f8d2'
 8
 9$specificParent = Files::createTemporaryDirectory(parentDirectory: '/var/tmp');
10// Creates the directory inside '/var/tmp' instead

Returns string — The full path to the newly created temporary directory

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the directory cannot be created

See also

• \Phuture\Coherence\Files::createTemporaryFile()
• \Phuture\Coherence\Files::delete()

#createTemporaryFile()

public static function createTemporaryFile(string $prefix = 'tmp_', string $extension = '', int $mode = 0600, string $parentDirectory = ''): string

Creates a temporary file with a unique name.

This method creates a new empty file inside the system's temporary directory (or a custom directory you specify) with a unique name that avoids collisions. The file name is generated using a prefix you provide combined with random characters, so multiple calls will always produce different files.

Example:

 1use Phuture\Coherence\Files;
 2
 3$tempFile = Files::createTemporaryFile();
 4// Returns something like '/tmp/tmp_664b5a3c1f8d2'
 5
 6$customFile = Files::createTemporaryFile(prefix: 'myapp_', extension: '.csv');
 7// Returns something like '/tmp/myapp_664b5a3c1f8d2.csv'
 8
 9$specificDir = Files::createTemporaryFile(parentDirectory: '/var/tmp');
10// Creates the file inside '/var/tmp' instead

Returns string — The full path to the newly created temporary file

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file cannot be created

See also

• \Phuture\Coherence\Files::createTemporaryDirectory()
• \Phuture\Coherence\Files::delete()

#decompress()

public static function decompress(string $archive, string $destination, CompressionFormat $format = CompressionFormat::Zip): void

Extracts an archive into a destination directory.

All three formats — Zip, Tar, and Gzip — extract their contents into the directory given by $destination. Gzip archives are treated as .tar.gz files and behave identically to Tar. When no format is given, Zip is used by default.

The destination directory is created automatically when it does not already exist. All extracted files are placed directly inside $destination.

Example:

 1use Phuture\Coherence\Files;
 2use Phuture\Coherence\Enum\CompressionFormat;
 3
 4// ZIP (default) — extract into a directory
 5Files::decompress('/var/backups/uploads.zip', '/var/app/uploads');
 6
 7// TAR — extract an uncompressed archive
 8Files::decompress('/var/backups/uploads.tar', '/var/app/uploads', CompressionFormat::Tar);
 9
10// GZIP — extract a .tar.gz archive
11Files::decompress('/var/backups/uploads.tar.gz', '/var/app/uploads', CompressionFormat::Gzip);

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — If the archive file does not exist
• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be extracted

See also

• \Phuture\Coherence\Files::compress()

#delete()

public static function delete(string $path): void

Deletes a file or an entire directory at the given path.

When the path points to a directory, all of its contents (files and subdirectories) are deleted recursively before the directory itself is removed. If the path does not exist, this method does nothing.

Example:

1use Phuture\Coherence\Files;
2
3Files::delete('/path/to/file.txt');
4Files::delete('/path/to/directory');

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path cannot be deleted

See also

• \Phuture\Coherence\Files::copy()
• \Phuture\Coherence\Files::move()

#directory()

public static function directory(string $path, int $levels = 1): string

Returns the parent directory path of a file or directory.

Optionally, you can specify the number of levels to go up. For example, a $levels of 2 goes up two parent directories.

Example:

1use Phuture\Coherence\Files;
2
3Files::directory('/path/to/file.txt'); // '/path/to'
4Files::directory('/path/to/file.txt', 2); // '/path'
5Files::directory('/path/to/directory/'); // '/path/to'

Returns string — The parent directory path

See also

• \Phuture\Coherence\Files::name()

#exists()

public static function exists(string $path): bool

Determines whether a file or directory exists at the given path.

Returns true for both files and directories. Use isFile() or isDirectory() for type-specific checks.

Example:

1use Phuture\Coherence\Files;
2
3Files::exists('/path/to/file.txt'); // true or false
4Files::exists('/path/to/directory'); // true or false

Returns bool — True when a file or directory exists at the path

See also

• \Phuture\Coherence\Files::isFile()
• \Phuture\Coherence\Files::isDirectory()

#extension()

public static function extension(string $path): string

Extracts the file extension from a path.

Returns the extension without the leading dot. When the file has no extension, an empty string is returned.

Example:

1use Phuture\Coherence\Files;
2
3Files::extension('/path/to/file.txt'); // 'txt'
4Files::extension('/path/to/archive.tar.gz'); // 'gz'
5Files::extension('/path/to/README'); // ''

Returns string — The file extension without the leading dot, or an empty string when there is none

See also

• \Phuture\Coherence\Files::name()
• \Phuture\Coherence\Files::mimeType()

#find()

public static function find(string $directory = '.', string|array $masks = '*', bool $recursive = false): array

Finds files and directories matching the given glob-style patterns.

Returns all files and directories within the specified directory that match any of the provided masks. When $recursive is true, subdirectories are searched as well. Masks use glob patterns: * matches any characters, ? matches a single character, and [...] matches a character class.

Example:

1use Phuture\Coherence\Files;
2
3$all = Files::find('/path/to/dir');
4$phpAndMd = Files::find('/path/to/src', ['*.php', '*.md'], recursive: true);

Returns array — Array of file and directory paths matching the patterns

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the directory does not exist

See also

• \Phuture\Coherence\Files::findFiles()
• \Phuture\Coherence\Files::findDirectories()

#findDirectories()

public static function findDirectories(string $directory = '.', string|array $masks = '*', bool $recursive = false): array

Finds only directories matching the given glob-style patterns.

Works like find() but excludes files from the results. Only directories that match any of the provided masks are returned.

Example:

1use Phuture\Coherence\Files;
2
3$dirs = Files::findDirectories('/path/to/project');
4$srcDirs = Files::findDirectories('/path/to', 'src*', recursive: true);

Returns array — Array of directory paths matching the patterns

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the directory does not exist

See also

• \Phuture\Coherence\Files::find()
• \Phuture\Coherence\Files::findFiles()

#findFiles()

public static function findFiles(string $directory = '.', string|array $masks = '*', bool $recursive = false): array

Finds only files matching the given glob-style patterns.

Works like find() but excludes directories from the results. Only regular files that match any of the provided masks are returned.

Example:

1use Phuture\Coherence\Files;
2
3$phpFiles = Files::findFiles('/path/to/src', '*.php');
4$allCode = Files::findFiles('/path/to/project', ['*.php', '*.js'], recursive: true);

Returns array — Array of file paths matching the patterns

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the directory does not exist

See also

• \Phuture\Coherence\Files::find()
• \Phuture\Coherence\Files::findDirectories()

#getLink()

public static function getLink(string $path): string

Returns the target of a symbolic link.

Returns the path that the symbolic link points to. The returned path may be relative or absolute depending on how the link was created.

Example:

1use Phuture\Coherence\Files;
2
3$target = Files::getLink('/path/to/symlink');

Returns string — The target path that the link points to

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path is not a symbolic link or cannot be read

See also

• \Phuture\Coherence\Files::isLink()
• \Phuture\Coherence\Files::link()

#isAbsolute()

public static function isAbsolute(string $path): bool

Determines whether a path is absolute.

An absolute path starts with a forward slash on Unix systems or a drive letter followed by a colon on Windows (for example, C:/).

Example:

1use Phuture\Coherence\Files;
2
3Files::isAbsolute('/usr/local/bin'); // true
4Files::isAbsolute('relative/path'); // false
5Files::isAbsolute('C:/Windows'); // true

Returns bool — True when the path is absolute, false when it is relative

See also

• \Phuture\Coherence\Files::normalizePath()
• \Phuture\Coherence\Files::joinPaths()

#isDirectory()

public static function isDirectory(string $path): bool

Determines whether the given path is a directory.

Returns false for regular files, symlinks pointing to files, and non-existent paths.

Example:

1use Phuture\Coherence\Files;
2
3Files::isDirectory('/path/to/directory'); // true
4Files::isDirectory('/path/to/file.txt'); // false

Returns bool — True when the path is a directory

See also

• \Phuture\Coherence\Files::isFile()
• \Phuture\Coherence\Files::exists()

#isEmpty()

public static function isEmpty(string $path): bool

Determines whether a directory is empty (contains no files or subdirectories).

Returns true when the directory exists and contains no entries. Returns false when the directory contains at least one file or subdirectory. Throws when the path is not a valid directory.

Example:

1use Phuture\Coherence\Files;
2
3Files::isEmpty('/path/to/empty/dir'); // true
4Files::isEmpty('/path/to/full/dir'); // false

Returns bool — True when the directory is empty, false when it contains entries

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the path is not a directory

See also

• \Phuture\Coherence\Files::isDirectory()
• \Phuture\Coherence\Files::listing()

#isFile()

public static function isFile(string $path): bool

Determines whether the given path is a regular file (not a directory).

Returns false for directories, symlinks pointing to directories, and non-existent paths.

Example:

1use Phuture\Coherence\Files;
2
3Files::isFile('/path/to/file.txt'); // true
4Files::isFile('/path/to/directory'); // false

Returns bool — True when the path is a regular file

See also

• \Phuture\Coherence\Files::isDirectory()
• \Phuture\Coherence\Files::exists()

#isLink()

public static function isLink(string $path): bool

Determines whether the given path is a symbolic link.

Example:

1use Phuture\Coherence\Files;
2
3Files::isLink('/path/to/symlink'); // true or false

Returns bool — True when the path is a symbolic link

See also

• \Phuture\Coherence\Files::link()
• \Phuture\Coherence\Files::getLink()
• \Phuture\Coherence\Files::unlink()

#isLocked()

public static function isLocked(string $path): bool

Determines whether a file has an exclusive lock.

Attempts to acquire a non-blocking shared lock on the file. When the lock cannot be acquired because another process holds an exclusive lock, returns true.

Example:

1use Phuture\Coherence\Files;
2
3if (Files::isLocked('/path/to/file.txt')) {
4    echo 'File is locked by another process';
5}

Returns bool — True when the file appears to be exclusively locked

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file does not exist or cannot be opened

See also

• \Phuture\Coherence\Files::write()

#isReadable()

public static function isReadable(string $path): bool

Determines whether a file or directory is readable.

Example:

1use Phuture\Coherence\Files;
2
3Files::isReadable('/path/to/file.txt'); // true or false

Returns bool — True when the path exists and is readable

See also

• \Phuture\Coherence\Files::isWritable()

#isWritable()

public static function isWritable(string $path): bool

Determines whether a file or directory is writable.

Example:

1use Phuture\Coherence\Files;
2
3Files::isWritable('/path/to/file.txt'); // true or false

Returns bool — True when the path exists and is writable

See also

• \Phuture\Coherence\Files::isReadable()

#joinPaths()

public static function joinPaths(string ...$segments): string

Joins multiple path segments into a single normalized path.

Segments are joined with forward slashes and the resulting path is normalized to resolve . and .. references. Trailing slashes on individual segments are handled correctly.

Example:

1use Phuture\Coherence\Files;
2
3Files::joinPaths('a', 'b', 'file.txt'); // 'a/b/file.txt'
4Files::joinPaths('/a/', '/b/'); // '/a/b/'
5Files::joinPaths('/a/', '/../b'); // '/b'

Returns string — The joined and normalized path

See also

• \Phuture\Coherence\Files::normalizePath()
• \Phuture\Coherence\Files::isAbsolute()

#lastModified()

public static function lastModified(string $path): int

Returns the last modification time of a file as a Unix timestamp.

The timestamp represents the number of seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC) when the file was last modified.

Example:

1use Phuture\Coherence\Files;
2
3$timestamp = Files::lastModified('/path/to/file.txt');
4echo date('Y-m-d H:i:s', $timestamp);

Returns int — The last modification time as a Unix timestamp

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file does not exist or the time cannot be read

See also

• \Phuture\Coherence\Files::size()

#link()

public static function link(string $target, string $link): void

Creates a symbolic link from the target to the link path.

Example:

1use Phuture\Coherence\Files;
2
3Files::link('/path/to/target', '/path/to/symlink');

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the link cannot be created

See also

• \Phuture\Coherence\Files::isLink()
• \Phuture\Coherence\Files::getLink()
• \Phuture\Coherence\Files::unlink()

#listing()

public static function listing(string $path, string|callable|null $filter = null): array

Lists the contents of a directory, optionally filtered by a pattern or callback.

Returns an array of file and directory paths within the specified directory. When $filter is a string, only entries matching the glob pattern are included. When $filter is a callable, it receives each entry's full path as the first argument and the entry name as the second argument, and must return true to include it.

Example:

1use Phuture\Coherence\Files;
2
3$all = Files::listing('/path/to/dir');
4$phpFiles = Files::listing('/path/to/dir', '*.php');
5$largeFiles = Files::listing('/path/to/dir', fn($path, $name) => filesize($path) > 1024);

Returns array — Array of file and directory paths within the directory

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When the path is not a directory
• \Phuture\Coherence\Exception\RuntimeException — When the directory cannot be opened

See also

• \Phuture\Coherence\Files::findFiles()
• \Phuture\Coherence\Files::isEmpty()

#makeWritable()

public static function makeWritable(string $path, int $directoryMode = 0777, int $fileMode = 0666): void

Sets file and directory permissions to make a path writable.

When the path points to a directory, permissions are applied recursively to all files and subdirectories within it. Directories receive $directoryMode and files receive $fileMode.

Example:

1use Phuture\Coherence\Files;
2
3Files::makeWritable('/path/to/file.txt');
4Files::makeWritable('/path/to/directory', 0755, 0644);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path does not exist or permissions cannot be changed

See also

• \Phuture\Coherence\Files::chmod()

#mimeType()

public static function mimeType(string $path): string

Returns the MIME type of a file detected from the file's content.

Uses the system's MIME database to determine the file type by examining the file's actual content rather than relying on the file extension. This provides a more accurate result than extension-based detection.

Example:

1use Phuture\Coherence\Files;
2
3Files::mimeType('/path/to/image.png'); // 'image/png'
4Files::mimeType('/path/to/document.pdf'); // 'application/pdf'
5Files::mimeType('/path/to/script.php'); // 'text/x-php'

Returns string — The MIME type of the file (for example, 'text/plain', 'image/png')

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file does not exist or the MIME type cannot be detected

See also

• \Phuture\Coherence\Files::extension()

#move()

public static function move(string $source, string $destination, bool $overwrite = true): void

Moves a file or directory to a new location.

This is equivalent to renaming the path. By default, existing files at the destination are overwritten. When $overwrite is false and the destination already exists, a \Phuture\Coherence\Exception\RuntimeException is thrown.

Example:

1use Phuture\Coherence\Files;
2
3Files::move('/path/to/old.txt', '/path/to/new.txt');
4Files::move('/path/to/old_dir', '/path/to/new_dir');

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the source does not exist, the destination cannot be written, or the move fails

See also

• \Phuture\Coherence\Files::copy()
• \Phuture\Coherence\Files::rename()

#name()

public static function name(string $path, bool $includeExtension = true): string

Returns the name of a file or directory from a path.

By default, returns the full basename including the extension. When $includeExtension is false, the extension is stripped from the result.

Example:

1use Phuture\Coherence\Files;
2
3Files::name('/path/to/file.txt'); // 'file.txt'
4Files::name('/path/to/file.txt', includeExtension: false); // 'file'
5Files::name('/path/to/directory/'); // 'directory'

Returns string — The name of the file or directory without the parent path

See also

• \Phuture\Coherence\Files::directory()
• \Phuture\Coherence\Files::extension()

#normalizePath()

public static function normalizePath(string $path): string

Normalizes a path by resolving . and .. references and converting slashes.

Removes . segments, resolves .. by removing the preceding directory, and converts all directory separators to the system's standard separator. A trailing slash is preserved only when the original path ends with a separator.

Example:

1use Phuture\Coherence\Files;
2
3Files::normalizePath('/file/.'); // '/file'
4Files::normalizePath('\\file\\..'); // '/'
5Files::normalizePath('/file/../..'); // '/..'
6Files::normalizePath('file/../../bar'); // '../bar'

Returns string — The normalized path using the system's directory separator

See also

• \Phuture\Coherence\Files::joinPaths()
• \Phuture\Coherence\Files::unixSlashes()

#of()

public static function of(string $path): Type\Files

Creates a fluent wrapper around the given file path for method chaining.

Returns a \Phuture\Coherence\Type\Files instance that wraps the provided file path and exposes chainable file manipulation methods alongside the \Phuture\Coherence\Interface\Fileable inspection methods.

The path must point to an existing file. Directories are not accepted. The path is resolved to its full absolute real path before being passed to the wrapper.

Example:

1use Phuture\Coherence\Files;
2
3$content = Files::of('/path/to/draft.txt')
4    ->copy('/path/to/backup.txt')
5    ->rename('final.txt')
6    ->write('Updated content')
7    ->read();
8// 'Updated content'

Returns \Phuture\Coherence\Type\Files — A fluent wrapper instance that enables method chaining

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path does not exist or is a directory

See also

• \Phuture\Coherence\Type\Files — For the fluent wrapper implementation

#platformSlashes()

public static function platformSlashes(string $path): string

Converts all directory separators in a path to the current platform's standard.

On Windows, backslashes are used. On all other platforms, forward slashes are used.

Example:

1use Phuture\Coherence\Files;
2
3// On Linux/macOS:
4Files::platformSlashes('path\\to\\file.txt'); // 'path/to/file.txt'
5// On Windows:
6Files::platformSlashes('path/to/file.txt'); // 'path\to\file.txt'

Returns string — The path with platform-specific slashes

See also

• \Phuture\Coherence\Files::unixSlashes()

#prepend()

public static function prepend(string $path, string $content): void

Prepends content to the beginning of an existing file.

When the file does not exist, it is created with the given content. Parent directories are created automatically when they do not exist.

Example:

1use Phuture\Coherence\Files;
2
3Files::write('/path/to/file.txt', 'Original content');
4Files::prepend('/path/to/file.txt', 'Header: ');

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file cannot be written

See also

• \Phuture\Coherence\Files::write()
• \Phuture\Coherence\Files::append()

#read()

public static function read(string $path): string

Reads and returns the entire contents of a file.

Loads the complete file contents into a string. For large files, consider using readLines() which processes the file line by line without loading it all into memory at once.

Example:

1use Phuture\Coherence\Files;
2
3$content = Files::read('/path/to/file.txt');
4echo $content;

Returns string — The complete contents of the file

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file does not exist or cannot be read

See also

• \Phuture\Coherence\Files::readLines()
• \Phuture\Coherence\Files::write()

#readLines()

public static function readLines(string $path, bool $stripNewLines = true): Generator

Reads a file line by line, yielding each line as a string.

Returns a generator that produces one line at a time, making it memory-efficient for large files. By default, trailing newline characters (\r and \n) are stripped from each line.

Example:

1use Phuture\Coherence\Files;
2
3foreach (Files::readLines('/path/to/file.txt') as $lineNumber => $line) {
4    echo "Line {$lineNumber}: {$line}\n";
5}

Returns Generator<int, — string> A generator yielding line numbers (zero-based) and line content

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file does not exist or cannot be opened

See also

• \Phuture\Coherence\Files::read()

#rename()

public static function rename(string $path, string $newName, bool $overwrite = true): void

Renames a file or directory to a new name within the same directory.

Unlike move(), which accepts a full destination path, this method takes only the new name and keeps the file in its current parent directory. When $overwrite is false and a file with the new name already exists, a \Phuture\Coherence\Exception\RuntimeException is thrown.

Example:

1use Phuture\Coherence\Files;
2
3Files::rename('/path/to/old.txt', 'new.txt');
4Files::rename('/path/to/old_dir', 'new_dir', overwrite: false);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path does not exist, the new name is empty, or the rename fails

See also

• \Phuture\Coherence\Files::move()
• \Phuture\Coherence\Files::name()

#replaceInFile()

public static function replaceInFile(string $path, string|array $search, string|array $replace): void

Replaces all occurrences of a search string with a replacement string within a file.

Reads the file, performs the replacement, and writes the result back. When $search is an array, each occurrence of any search value is replaced with the corresponding value in $replace.

Example:

1use Phuture\Coherence\Files;
2
3Files::replaceInFile('/path/to/config.php', 'old-value', 'new-value');
4Files::replaceInFile('/path/to/template.html', ['{{name}}', '{{email}}'], ['John', '[email protected]']);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file does not exist or cannot be written

See also

• \Phuture\Coherence\Files::write()
• \Phuture\Coherence\Files::read()

#size()

public static function size(string $path): int

Returns the size of a file or directory in bytes.

When the path points to a file, returns its exact size. When the path points to a directory, returns the total combined size of all files within it recursively. Throws when the path does not exist.

Example:

1use Phuture\Coherence\Files;
2
3$fileBytes = Files::size('/path/to/file.txt');
4$dirBytes = Files::size('/path/to/directory');

Returns int — The size in bytes

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path does not exist or the size cannot be read

See also

• \Phuture\Coherence\Files::lastModified()
• \Phuture\Coherence\Files::mimeType()

#unixSlashes()

public static function unixSlashes(string $path): string

Converts all directory separators in a path to forward slashes (Unix style).

Useful for normalizing paths for display or for use in contexts that require forward slashes regardless of the operating system.

Example:

1use Phuture\Coherence\Files;
2
3Files::unixSlashes('path\\to\\file.txt'); // 'path/to/file.txt'

Returns string — The path with forward slashes

See also

• \Phuture\Coherence\Files::platformSlashes()
• \Phuture\Coherence\Files::normalizePath()

#unlink()

public static function unlink(string $path): void

Removes a symbolic link.

Validates that the path is a symbolic link before removing it. Throws when the path is not a symbolic link or cannot be removed.

Example:

1use Phuture\Coherence\Files;
2
3Files::unlink('/path/to/symlink');

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the path is not a symbolic link or cannot be removed

See also

• \Phuture\Coherence\Files::isLink()
• \Phuture\Coherence\Files::link()

#upload()

public static function upload(string $key, string $destination, ?array $files = null, array $options = []): array|false

Handles file uploads from an HTTP request, saving files to a destination directory.

Supports both single file uploads and multiple file uploads (when the request field uses array notation like files[]). When the upload field contains multiple files (detected automatically), all files are saved and an array of file information arrays is returned.

When the first parameter is "files" and the request contains files[], the method detects the array structure and processes all uploaded files.

Optional validation rules can be passed via the $options array. When a file fails validation in non-strict mode (default), it is silently skipped. When 'strict' is true, an InvalidArgumentException is thrown for the first invalid file. MIME type validation uses the actual file content, not the client-provided type field.

Example:

 1use Phuture\Coherence\Files;
 2
 3// Single file upload: <input type="file" name="avatar">
 4$result = Files::upload('avatar', '/path/to/uploads');
 5// Returns: ['name' => 'photo.jpg', 'path' => '...', 'size' => 12345, ...]
 6
 7// Multiple file upload: <input type="file" name="files[]" multiple>
 8$results = Files::upload('files', '/path/to/uploads');
 9// Returns: [['name' => 'a.jpg', ...], ['name' => 'b.jpg', ...]]
10
11// With validation
12$result = Files::upload('avatar', '/uploads', null, [
13    'extensions' => ['jpg', 'png', 'gif'],
14    'mimeTypes'  => ['image/jpeg', 'image/png', 'image/gif'],
15    'maxSize'    => 2 * 1024 * 1024, // 2 MB
16]);
17
18// Strict mode: throws on invalid file
19Files::upload('document', '/uploads', null, [
20    'extensions' => ['pdf', 'docx'],
21    'strict'     => true,
22]);

Returns array|false — A single file info array, an array of file info arrays for multiple uploads, or false on failure

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When a file fails validation in strict mode

See also

• \Phuture\Coherence\Files::move()
• \Phuture\Coherence\Files::create()

#write()

public static function write(string $path, string $content, int $mode = 0666, bool $lock = false): void

Writes content to a file, creating the file if it does not exist.

If the file already exists, its contents are replaced entirely. Parent directories are created automatically when they do not exist.

When $lock is true, an exclusive lock is acquired before writing to prevent concurrent writes from corrupting the file.

Example:

1use Phuture\Coherence\Files;
2
3Files::write('/path/to/file.txt', 'Hello, World!');
4Files::write('/path/to/new/file.txt', 'New content', 0644);
5Files::write('/path/to/file.txt', 'Locked write', lock: true);

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the file cannot be written

See also

• \Phuture\Coherence\Files::read()
• \Phuture\Coherence\Files::append()
• \Phuture\Coherence\Files::prepend()

#compressGzip()

private static function compressGzip(string $source, string $destination): void

Compresses a file or directory into a GZIP-compressed TAR archive (.tar.gz).

First builds a temporary TAR archive using PharData, then compresses it with gzencode() and writes the result to the destination path. The temporary TAR file is always removed, even if an error occurs.

Throws

• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be created or written

#compressTar()

private static function compressTar(string $source, string $destination): void

Compresses a file or directory into a TAR archive using PHP's built-in PharData.

When the source is a directory, all its contents are added using PharData::buildFromDirectory(). When the source is a single file, it is added under its base name.

Throws

• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be created

#compressZip()

private static function compressZip(string $source, string $destination): void

Compresses a file or directory into a ZIP archive using nelexa/zip.

When the source is a directory, all its contents are added recursively. When the source is a single file, it is added under its base name.

Throws

• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be created or saved

#copyDirectory()

private static function copyDirectory(string $source, string $destination, bool $overwrite): void

Copies a directory recursively to a new location.

#createDirectory()

private static function createDirectory(string $path, int $mode = 0777): void

Creates a directory at the given path, including any parent directories that do not exist.

#decompressGzip()

private static function decompressGzip(string $archive, string $destination): void

Extracts a GZIP-compressed TAR archive (.tar.gz) to a destination directory.

Decompresses the archive with gzdecode() into a temporary TAR file, then uses PharData to extract its contents to the destination directory. The temporary TAR file is always removed, even if an error occurs.

Throws

• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be read, decompressed, or extracted

#decompressTar()

private static function decompressTar(string $archive, string $destination): void

Extracts a TAR archive to a destination directory using PHP's built-in PharData.

Creates the destination directory if it does not already exist, then extracts all entries from the archive into it.

Throws

• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be opened or extracted

#decompressZip()

private static function decompressZip(string $archive, string $destination): void

Extracts a ZIP archive to a destination directory using nelexa/zip.

Creates the destination directory if it does not already exist, then extracts all entries from the archive into it.

Throws

• \Phuture\Coherence\Exception\RuntimeException — If the archive cannot be opened or extracted

#deleteDirectory()

private static function deleteDirectory(string $path): void

Deletes a directory and all of its contents recursively.

#directorySize()

private static function directorySize(string $path): int

Calculates the total size of all files in a directory recursively.

Returns int — The total size in bytes

#findByType()

private static function findByType(string|array $masks, string $directory, bool $recursive, ?string $type): array

Finds files and/or directories by type, matching the given masks.

Returns array — Array of matching paths

#handleLastError()

private static function handleLastError(string $prefix): never

Throws a RuntimeException that includes the last PHP-level error message.

Use this after calling error_clear_last() and then a PHP filesystem function that may fail. The actual PHP error (e.g. "Permission denied") is appended to $prefix so the developer can see the real reason.

Throws

• \Phuture\Coherence\Exception\RuntimeException — Always

#handleMultipleUpload()

private static function handleMultipleUpload(array $files, string $destination, array $options): array

Handles a multiple file upload by processing each file individually.

Returns array — Array of file information arrays for each successfully uploaded file

#handleSingleUpload()

private static function handleSingleUpload(array $file, string $destination, array $options): array|false

Handles a single file upload by moving it to the destination directory.

Runs validation checks (extension, MIME type, file size) when the corresponding options are provided. In non-strict mode invalid files return false; in strict mode an InvalidArgumentException is thrown.

Returns array|false — File information array or false on failure

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — When validation fails in strict mode

#matchesAnyMask()

private static function matchesAnyMask(string $filename, array $masks): bool

Checks whether a filename matches any of the given glob patterns.

Returns bool — True when the filename matches at least one pattern