Class Salient\Utility\File

`final`
`extends`	`AbstractUtility`


					
	public
					static

isAbsolute(string $path): bool

Check if a path is absolute without accessing the filesystem

Returns true if $path starts with /, \\, <letter>:\, <letter>:/ or a URI scheme with two or more characters.

#


					
	public
					static

resolvePath(string $path, bool $withUriSegments = false): string

Resolve "/./" and "/../" segments in a path without accessing the filesystem

If $withUriSegments is true, "/../" segments after empty segments (e.g. "/dir1/dir2//../") are resolved by removing an empty segment, otherwise consecutive directory separators are treated as one separator.

#


					
	public
					static

sanitiseDir(string $directory): string

Sanitise the path to a directory without accessing the filesystem

Returns "." if $directory is an empty string, otherwise removes trailing directory separators.

#


					
	public
					static

chdir(string $directory): void

Change the current directory

#


					
	public
					static

mkdir(string $directory, int $permissions = 0777, bool $recursive = false): void

Create a directory

#


					
	public
					static

chmod(string $filename, int $permissions): void

Change file permissions

#


					
	public
					static

rename(string $from, string $to): void

Rename a file or directory

#


					
	public
					static

symlink(string $target, string $link): void

Create a symbolic link to a target with a given name

#


					
	public
					static

touch(string $filename, ?int $mtime = null, ?int $atime = null): void

Set file access and modification times

#


					
	public
					static

getClosestPath(string $path): ?string

Get a path or its closest parent that exists

Returns null if the leftmost segment of $path doesn't exist, or if the closest parent that exists is not a directory.

#


					
	public
					static

create(string $filename, int $permissions = 0777, int $dirPermissions = 0777, bool $umaskApplies = true): void

Safely create a file if it doesn't exist

Parameters

`$permissions`	Applied if `$filename` is created.
`$dirPermissions`	Applied if `$filename`'s directory is created. Parent directories, if any, are created with file mode `0777 & ~umask()`, or `0755` if `$umaskApplies` is `false`.

#


					
	public
					static

createDir(string $directory, int $permissions = 0777, bool $umaskApplies = true): void

Safely create a directory if it doesn't exist

Parameters

$permissions

Applied if $directory is created. Parent directories, if any, are created with file mode 0777 & ~umask(), or 0755 if $umaskApplies is false.

#


					
	public
					static

createTemp(string|null $directory = null, string|null $prefix = null): string

Create a temporary file with mode 0600

Parameters

`$directory`	If `null`, the directory returned by `sys_get_temp_dir()` is used.
`$prefix`	If `null`, the basename of the file used to run the script is used.

#


					
	public
					static

createTempDir(string|null $directory = null, string|null $prefix = null): string

Create a temporary directory with file mode 0700

Parameters

`$directory`	If `null`, the directory returned by `sys_get_temp_dir()` is used.
`$prefix`	If `null`, the basename of the file used to run the script is used.

#


					
	public
					static

delete(string $filename): void

Delete a file if it exists

#


					
	public
					static

deleteDir(string $directory): void

Delete a directory if it exists

#


					
	public
					static

find(): RecursiveFilesystemIterator

Iterate over files in one or more directories

#


					
	public
					static

getcwd(): string

Get the current working directory without resolving symbolic links

#


					
	public
					static

isCreatable(string $path): bool

Check if a path exists and is writable, or doesn't exist but descends from a writable directory

#


					
	public
					static

pruneDir(string $directory, bool $delete = false, bool $setPermissions = false): void

Recursively delete the contents of a directory before optionally deleting the directory itself

If $setPermissions is true, file modes in $directory are changed if necessary for deletion to succeed.

#


					
	public
					static

realpath(string $path): string

Resolve symbolic links and relative references in a path or Phar URI

An exception is thrown if $path does not exist.

#


					
	public
					static

getRelativePath<TDefault is string|null>(
	string $path,
	string $parentDirectory,
	TDefault $default = null,
): string|TDefault

Get a path relative to a parent directory

Returns $default if $path does not belong to $parentDirectory.

An exception is thrown if $path or $parentDirectory do not exist.

#


					
	public
					static

same(string $filename1, string $filename2): bool

Check if two paths refer to the same filesystem entry

#


					
	public
					static

getIdentifier(string $filename): string

Get a unique identifier for a file from its device and inode numbers

#


					
	public
					static

size(string $filename): int

Get the size of a file

#


					
	public
					static

Get the type of a file

#


					
	public
					static

writeContents(
	string $filename,
	resource|array<int|float|string|bool|Stringable|null>|string $data,
	int-mask-of<FILE_USE_INCLUDE_PATH|FILE_APPEND|LOCK_EX> $flags = 0,
): int

Write data to a file

#


					
	public
					static

checkEof(resource $stream, Stringable|string|null $uri = null): void

Check for errors after fgets(), fgetcsv(), etc. return false

#


					
	public
					static

close(resource $stream, Stringable|string|null $uri = null): void

Close an open stream

#


					
	public
					static

closePipe(resource $pipe, ?string $command = null): int

Close a pipe to a process and return its exit status

#


					
	public
					static

eof(resource $stream, bool $returnFalseOnError = false): bool

Check if a stream is at end-of-file

#


					
	public
					static

getSeekableStream(resource $stream, Stringable|string|null $uri = null): resource

If a stream is not seekable, copy it to a temporary stream that is and close it

#


					
	public
					static

getStreamUri(resource $stream): string|null

Get the URI associated with a stream

Returns

null if $stream is closed or does not have a URI.

#


					
	public
					static

isSeekableStream(mixed $value): bool

Check if a value is a seekable stream resource

#


					
	public
					static

isStream(mixed $value): bool

Check if a value is a stream resource

#


					
	public
					static

open(string $filename, string $mode): resource

Open a file or URI

#


					
	public
					static

maybeOpen<TUri is Stringable|string|null>(
	Stringable|string|resource $resource,
	string $mode,
	?bool &$close,
	TUri &$uri,
): resource

Open a resource if it is not already open

#


					
	public
					static

openPipe(string $command, string $mode): resource

Open a pipe to a process

#


					
	public
					static

read(resource $stream, int<1, max> $length, Stringable|string|null $uri = null): string

Read from an open stream

#


					
	public
					static

readAll(resource $stream, int<0, max> $length, Stringable|string|null $uri = null): string

Read from an open stream until data of the expected length is read

Throws

Salient\Utility\Exception\UnreadDataException

if fewer bytes are read than expected and the stream is at end-of-file.

#


					
	public
					static

readLine(resource $stream, Stringable|string|null $uri = null): string

Read a line from an open stream

#


					
	public
					static

rewind(resource $stream, Stringable|string|null $uri = null): void

Rewind to the beginning of a stream

#


					
	public
					static

maybeRewind(resource $stream, Stringable|string|null $uri = null): void

Rewind to the beginning of a stream if it is seekable

#


					
	public
					static

seek(
	resource $stream,
	int $offset,
	SEEK_SET|SEEK_CUR|SEEK_END $whence = SEEK_SET,
	Stringable|string|null $uri = null,
): void

Set the file position indicator for a stream

#


					
	public
					static

maybeSeek(
	resource $stream,
	int $offset,
	SEEK_SET|SEEK_CUR|SEEK_END $whence = SEEK_SET,
	Stringable|string|null $uri = null,
): void

Set the file position indicator for a stream if it is seekable

#


					
	public
					static

select<TRead is resource[]|null, TWrite is resource[]|null, TExcept is resource[]|null>(
	TRead &$read,
	TWrite &$write,
	TExcept &$except,
	?int $seconds,
	?int $microseconds = null,
): int

Wait for the given streams to change status

#


					
	public
					static

tell(resource $stream, Stringable|string|null $uri = null): int

Get the file position indicator for a stream

#


					
	public
					static

truncate(resource $stream, int<0, max> $size = 0, Stringable|string|null $uri = null): void

Rewind to the beginning of a stream and truncate it

#


					
	public
					static

write(resource $stream, string $data, int<0, max>|null $length = null, Stringable|string|null $uri = null): int

Write to an open stream

Throws

Salient\Utility\Exception\UnwrittenDataException

if fewer bytes are written than expected.

#


					
	public
					static

writeAll(resource $stream, string $data, int<0, max>|null $length = null, Stringable|string|null $uri = null): int

Write to an open stream until there is no unwritten data

#


					
	public
					static

maybeWrite(
	resource $stream,
	string $data,
	?string &$buffer,
	int<0, max>|null $length = null,
	Stringable|string|null $uri = null,
): int

Write to an open stream and apply any unwritten data to a buffer

#


					
	public
					static

writeCsvLine(
	resource $stream,
	(int|float|string|bool|null)[] $fields,
	string $separator = ',',
	string $enclosure = '"',
	string $eol = "\n",
	Stringable|string|null $uri = null,
): int

Write a line of comma-separated values to an open stream

A shim for {@see fputcsv()} with $eol (added in PHP 8.1) and without $escape (which should never have been added).

#


					
	public
					static

copy(
	Stringable|string|resource $from,
	Stringable|string|resource $to,
	Stringable|string|null $fromUri = null,
	Stringable|string|null $toUri = null,
): void

Copy a file or stream to another file or stream

#


					
	public
					static

getContents(Stringable|string|resource $resource, ?int $offset = null, Stringable|string|null $uri = null): string

Get the contents of a file or stream

#


					
	public
					static

getCsv(Stringable|string|resource $resource, Stringable|string|null $uri = null): list<array{null}|list<string>>

Get CSV-formatted data from a file or stream

#


					
	public
					static

Guess the end-of-line sequence used in a file or stream

Recognised line endings are LF ("\n"), CRLF ("\r\n") and CR ("\r").

Returns

null if there are no recognised newline characters in the file.

#


					
	public
					static

getIndentation(
	Stringable|string|resource $resource,
	?Indentation $default = null,
	bool $alwaysGuessTabSize = false,
	Stringable|string|null $uri = null,
): Indentation

Guess the indentation used in a file or stream

Returns $default if $resource appears to use the default indentation.

#


					
	public
					static

getLines(Stringable|string|resource $resource, Stringable|string|null $uri = null): string[]

Get lines from a file or stream

#


					
	public
					static

hasPhp(Stringable|string|resource $resource, Stringable|string|null $uri = null): bool

Check if a file or stream appears to contain PHP code

Returns true if $resource has a PHP open tag (<?php) at the start of the first line that is not a shebang (#!).

#


					
	public
					static

stat(Stringable|string|resource $resource, Stringable|string|null $uri = null): int[]

Get the status of a file or stream

#


					
	public
					static

writeCsv<TValue>(
	Stringable|string|resource $resource,
	iterable<TValue> $data,
	bool $headerRow = true,
	int|float|string|bool|null $null = null,
	(callable(TValue, int $index): mixed[])|null $callback = null,
	int|null &$count = null,
	string $eol = "\r\n",
	bool $utf16le = true,
	bool $bom = true,
	Stringable|string|null $uri = null,
): void

Write CSV-formatted data to a file or stream

For maximum interoperability with Excel across all platforms, output is written in UTF-16LE with a BOM (byte order mark) by default.

Parameters

`$headerRow`	Write the first entry's keys before the first row of data?
`$null`	Replace `null` values in `$data`.
`$callback`	Apply a callback to each entry before it is written.
`$count`	Receives the number of entries written.

#

Namespaces

Classes

Parameters

Parameters

Parameters

Parameters

Returns

Throws

Throws

Returns

Parameters