#Files

Phuture\Coherence\Type\Files

class Files extends FluentClass implements Fileable

A fluent wrapper around the Files utility class for chainable file manipulation.

Each method delegates to the corresponding static method on \Phuture\Coherence\Files, stores the result internally, and returns $this to enable method chaining. The wrapped value is always the current file path as a string.

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'

#Methods

#append()

public function append(string $content): self

Appends content to the end of the wrapped file.

Returns self — Returns the current instance for method chaining

Throws

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

See also

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

#chgrp()

public function chgrp(string|int $group): self

Changes the group ownership of the wrapped file.

Returns self — Returns the current instance for method chaining

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the group cannot be changed

See also

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

#chmod()

public function chmod(int $mode): self

Changes the permission mode of the wrapped file.

Returns self — Returns the current instance for method chaining

Throws

• \Phuture\Coherence\Exception\RuntimeException — When permissions cannot be changed

See also

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

#chown()

public function chown(string|int $user): self

Changes the owner of the wrapped file.

Returns self — Returns the current instance for method chaining

Throws

• \Phuture\Coherence\Exception\RuntimeException — When the owner cannot be changed

See also

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

#compress()

public function compress(string $destination, CompressionFormat $format = CompressionFormat::Zip): self

Compresses the wrapped file or directory into an archive and switches the internal path to it.

After compression, the internal path is updated to point to the newly created archive file, so subsequent operations act on the compressed archive.

Returns self — Returns the current instance for method chaining

Throws

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

See also

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

#copy()

public function copy(string $destination, bool $overwrite = true): self

Copies the wrapped file to a new location and updates the internal path.

After copying, the internal path remains unchanged (it still points to the source). Use copyTo() when you want the path to switch to the destination after copying.

Returns self — Returns the current instance for method chaining

Throws

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

See also

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

#copyTo()

public function copyTo(string $destination, bool $overwrite = true): self

Copies the wrapped file to a new location and switches the internal path to the destination.

This is the same as copy() but after copying, the internal path is updated to point to the destination, so subsequent operations act on the copy.

Returns self — Returns the current instance for method chaining

Throws

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

See also

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

#decompress()

public function decompress(string $destination, CompressionFormat $format = CompressionFormat::Zip): self

Extracts or decompresses the wrapped archive to a destination path.

Returns self — Returns the current instance for method chaining

Throws

• \Phuture\Coherence\Exception\InvalidArgumentException — If the archive does not exist
• \Phuture\Coherence\Exception\RuntimeException — If extraction fails

See also

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

#delete()

public function delete(): void

Deletes the file or directory at the current path.

After deletion, the internal path is set to an empty string. This method returns void because no further chaining is possible after the path is removed.

Throws

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

See also

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

#extension()

public function extension(): string

Returns the file extension without the leading dot.

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

See also

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

#lastModified()

public function lastModified(): int

Returns the last modification time of the file as a Unix 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::lastModified()

#makeWritable()

public function makeWritable(int $directoryMode = 0777, int $fileMode = 0666): self

Sets file permissions to make the current path writable.

Returns self — Returns the current instance for method chaining

Throws

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

See also

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

#mimeType()

public function mimeType(): string

Returns the MIME type of the file detected from its content.

Returns string — The MIME type of the file (e.g., '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::mimeType()

#move()

public function move(string $destination, bool $overwrite = true): self

Moves the wrapped file to a new location and updates the internal path to the destination.

Returns self — Returns the current instance for method chaining

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::move()

#name()

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

Returns the name of the file.

Returns string — The file name with or without extension

See also

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

#path()

public function path(): string

Returns the full absolute path to the file.

Returns string — The full absolute path to the file

#prepend()

public function prepend(string $content): self

Prepends content to the beginning of the wrapped file.

Returns self — Returns the current instance for method chaining

Throws

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

See also

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

#read()

public function read(): string

Reads and returns the entire contents of the file as a string.

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::read()

#rename()

public function rename(string $newName, bool $overwrite = true): self

Renames the file within its current directory and updates the internal path.

Returns self — Returns the current instance for method chaining

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::rename()

#replaceInFile()

public function replaceInFile(string|array $search, string|array $replace): self

Replaces all occurrences of a search string within the wrapped file.

Returns self — Returns the current instance for method chaining

Throws

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

See also

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

#size()

public function size(): int

Returns the size of the file in bytes.

Returns int — The file size in bytes

Throws

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

See also

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

#write()

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

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

Returns self — Returns the current instance for method chaining

Throws

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

See also

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