Wiki FileSystem

class \FireHub\Core\Support\LowLevel\FileSystem()

### File System low-level proxy class

Class contains methods related to a file system.

_{This class was created by Danijel Galić <danijel.galic@outlook.com>
Copyright: 2024 FireHub Web Application Framework
License: <https://opensource.org/licenses/OSL-3.0> OSL Open Source License version 3
Version: GIT: $Id$ Blob checksum.}

_{Fully Qualified Class Name:  \FireHub\Core\Support\LowLevel\FileSystem
Source code:  view source code
Blame:  view blame
History:  view history}

Methods

Type	Name	Title
public static	exist	### Checks whether a file or folder exists
public static	isReadable	### Tells whether a file exists and is readable
public static	isWritable	Tells whether the path is writable
public static	isSymbolicLink	### Tells whether the path is a symbolic link
public static	rename	### Renames a file or directory
public static	basename	### Returns a trailing name component of a path
public static	pathInfo	### Returns information about a file path
public static	absolutePath	### Returns canonical absolute pathname
public static	parent	### Returns parent folder path
public static	getGroup	### Gets file or folder group
public static	setGroup	### Changes file or folder group
public static	getOwner	### Gets file or folder owner
public static	setOwner	### Gets file or folder owner
public static	getPermissions	### Gets path permissions
public static	setPermissions	### Sets path permissions
public static	lastAccessed	### Gets last access time of path
public static	lastModified	### Gets last modification time of a path
public static	lastChanged	### Gets inode change time of a path
public static	setLastAccessedAndModification	### Sets last access and modification time of a path
public static	inode	### Gets file inode
public static	list	### List files and folders inside the specified folder
public static	search	### Find path-names matching a pattern
public static	symlink	### Creates a symbolic link
public static	symlinkTarget	### Returns the target of a symbolic link
public static	symlinkGroup	### Changes group ownership of symlink
public static	symlinkOwner	### Changes user ownership of symlink
public static	statistics	### Gives information about a file or folder
public static	clearCache	### Clears file status cache

# method: exist

final public static FileSystem::exist(string $path):bool

Important

This method is marked as final.

Note

Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.> [!NOTE] The results of this function are cached. See FileSystem#clearCache() for more details.> [!TIP] On windows, use //computername/share/filename or \computername\share\filename to check files on network shares.

### Checks whether a file or folder exists

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the file or folder.

Returns

• bool - True if the file or directory specified by filename exists, false otherwise.

# method: isReadable

final public static FileSystem::isReadable(string $path):bool

Important

This method is marked as final.

Note

The check is done using the real UID/GID instead of the effective one.> [!NOTE] The results of this function are cached. See FileSystem#clearCache() for more details.

### Tells whether a file exists and is readable

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the file or folder.

Returns

• bool - True if the file or directory specified by $path exists and is readable, false otherwise.

# method: isWritable

final public static FileSystem::isWritable(string $path):bool

Important

This method is marked as final.

Note

The results of this function are cached. See FileSystem#clearCache() for more details.

Tells whether the path is writable

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the file.

Returns

• bool - True if the filename exists and is writable.

# method: isSymbolicLink

final public static FileSystem::isSymbolicLink(string $path):bool

Important

This method is marked as final.

Note

The results of this function are cached. See FileSystem#clearCache() for more details.

### Tells whether the path is a symbolic link

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the file.

Returns

• bool - True if the filename exists and is a symbolic link, false otherwise.

# method: rename

public static FileSystem::rename(string $path, string $new_name):void

Note

On Windows, if $new_name already exists, it must be writable, otherwise FileSystem#rename() fails and issues E_WARNING.

### Renames a file or directory

Attempts to rename $path to $new_name, moving it between directories if necessary. If renaming a file and $new_name exists, it will be overwritten. If renaming a directory and $new_name exists, this function will emit a warning.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string The old name path.
• string $new_name - non-empty-string The new name.

Throws

• \Error - If we could not rename a path.

Returns

• void

# method: basename

final public static FileSystem::basename(string $path, string $suffix = ''):string

Important

This method is marked as final.

Caution

Method is locale aware, so for it to see the correct basename with multibyte character paths, the matching locale must be set using the setlocale() function. If a path contains characters which are invalid for the current locale, the behavior of FileSystem#basename() is undefined.> [!NOTE] Method operates naively on the input string, and is not aware of the actual filesystem, or path components such as "..".

### Returns a trailing name component of a path

Given a string containing the path to a file or directory, this function will return the trailing name component.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string A path. On Windows, both slash (/) and backslash () are used as directory separator character. In other environments, it is the forward slash (/).
• string $suffix = '' - [optional] If the name component ends in suffix, this will also be cut off.

Returns

• string - The base name of the given path.

# method: pathInfo

final public static FileSystem::pathInfo(string $path):array

Important

This method is marked as final.

Caution

FileSystem#pathInfo() is locale aware, so for it to parse a path containing multibyte characters correctly, the matching locale must be set using the setlocale() function.> [!NOTE] FileSystem#pathInfo() operates naively on the input string, and is not aware of the actual filesystem, or path components such as "..".> [!NOTE] On Windows systems only, the \ character will be interpreted as a directory separator. On other systems it will be treated like any other character.

### Returns information about a file path

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - The path to be parsed.

Returns

• array - array<'dirname': string|false, 'basename': string, 'extension': string|false, 'filename': string|false >]]> Information about a file path.

# method: absolutePath

final public static FileSystem::absolutePath(string $path):string

Important

This method is marked as final.

Note

Whilst a path must be supplied, the value can be an empty string. In this case, the value is interpreted as the current directory.> [!NOTE] The running script must have executable permissions on all directories in the hierarchy, otherwise FileSystem#absolutePath() will return false.> [!NOTE] For case-insensitive filesystems absolutePath() may or may not normalize the character case.> [!NOTE] The function FileSystem#absolutePath() will not work for a file which is inside a Phar as such a path would be virtual path, not a real one.> [!NOTE] On Windows, one level only expands junctions and symbolic links to directories.> [!NOTE] Because PHP's integer type is signed and many platforms use 32bit integers, some filesystem functions may return unexpected results for files which are larger than 2GB.

### Returns canonical absolute pathname

Expands all symbolic links and resolves references to /./, /../ and extra / characters in the input path and returns the canonical absolute pathname. Trailing delimiters, such as \ and /, are also removed.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - The path being checked.

Throws

• \Error - If we could not get absolute path for path, file doesn't exist or a script doesn't have executable permissions.

Returns

• string - The canonical absolute pathname.

# method: parent

final public static FileSystem::parent(string $path, int $levels = 1):string

Important

This method is marked as final.

Caution

Be careful when using this function in a loop that can reach the top-level directory as this can result in an infinite loop.

### Returns parent folder path

Given a string containing the path of a file or directory, this function will return the parent folder's path that is levels up from the current folder.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string A path.
• int $levels = 1 - [optional] positive-int The number of parent folders to go up. This must be an integer greater than 0.

Throws

• \ValueError - If $levels are less than 1.

Returns

• string - The parent folder name of the given path. If there are no slashes in path, a dot ('.') is returned, indicating the current folder.

# method: getGroup

final public static FileSystem::getGroup(string $path):int

Important

This method is marked as final.

Warning

This method does not work on Windows.> [!NOTE] The results of this function are cached. See clearCache() for more details.> [!TIP] Use posix_getgrgid() to resolve it to a group name.

### Gets file or folder group

Gets the file or folder group. The group ID is returned in numerical format.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path of the file or folder.

Throws

• \Error - If we could not get a group for file.

Returns

• int - The group ID of the file.

# method: setGroup

final public static FileSystem::setGroup(string $path, string|int $group):void

Important

This method is marked as final.

Warning

This method does not work on Windows.> [!TIP] Use posix_getgrgid() to resolve it to a group name.

### Changes file or folder group

Attempts to change the group of the file or folder $path to $group. Only the superuser may change the group of files arbitrarily; other users may change the group of files to any group of which that user is a member.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path of the file or folder.
• string or int $group - non-empty-string|int A group name or number.

Throws

• \Error - If we could not set a group for file or folder.

Returns

• void

# method: getOwner

final public static FileSystem::getOwner(string $path):int

Important

This method is marked as final.

Warning

This method does not work on Windows.> [!NOTE] The results of this function are cached. See clearCache() for more details.> [!TIP] Use posix_getpwuid() to resolve it to a username.

### Gets file or folder owner

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path of the file or folder.

Throws

• \Error - If we could not get an owner for file or folder.

Returns

• int - The user ID of the owner for the file or folder.

# method: setOwner

final public static FileSystem::setOwner(string $path, string|int $user):void

Important

This method is marked as final.

Warning

This method does not work on Windows.> [!NOTE] This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.> [!TIP] Use posix_getpwuid() to resolve it to a username.

### Gets file or folder owner

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Pth of the file or folder.
• string or int $user - non-empty-string|int A username or number.

Throws

• \Error - If we could not get an owner for file or folder.

Returns

• void

# method: getPermissions

final public static FileSystem::getPermissions(string $path):string

Important

This method is marked as final.

Note

The results of this function are cached. See FileSystem#clearCache() for more details.

### Gets path permissions

Gets permissions for the given path.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string The path.

Throws

• \Error - If we could not get permissions for a path.

Returns

• string - Path permissions.

# method: setPermissions

final public static FileSystem::setPermissions(string $path, \FireHub\Core\Support\Enums\FileSystem\Permission $owner, \FireHub\Core\Support\Enums\FileSystem\Permission $owner_group, \FireHub\Core\Support\Enums\FileSystem\Permission $global):void

Important

This method is marked as final.

Note

The current user is the user under which PHP runs. It is probably not the same user you use for normal shell or FTP access. The mode can be changed only by user who owns the file on most systems.> [!NOTE] This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.

### Sets path permissions

Attempts to change the mode of the specified path to that given in permissions.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string The path.
• \FireHub\Core\Support\Enums\FileSystem\Permission $owner - File owner permission.
• \FireHub\Core\Support\Enums\FileSystem\Permission $owner_group - File owner group permission.
• \FireHub\Core\Support\Enums\FileSystem\Permission $global - Everyone's permission,

Throws

• \Error - If we could not set permissions for a path.

Returns

• void - non-empty-string $path

# method: lastAccessed

final public static FileSystem::lastAccessed(string $path):int

Important

This method is marked as final.

Note

The atime of a file is supposed to change whenever the data blocks of a file are being read. This can be costly performance-wise when an application regularly accesses a huge number of files or directories. Some Unix filesystems can be mounted with atime updates disabled to increase the performance of such applications; USENET news spools are a common example. On such filesystems this function will be useless.> [!NOTE] Note that time resolution may differ from one file system to another.> [!NOTE] The results of this function are cached. See FileSystem#clearCache() for more details.

### Gets last access time of path

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to file or folder.

Throws

• \Error - If we could not get last accessed time for a path.

Returns

• int - The time the file was last accessed. The time is returned as a Unix timestamp.

# method: lastModified

final public static FileSystem::lastModified(string $path):int

Important

This method is marked as final.

Note

Note that time resolution may differ from one file system to another.> [!NOTE] The results of this function are cached.See FileSystem#clearCache() for more details.

### Gets last modification time of a path

Represents when the data or content is changed or modified, not including that of metadata such as ownership or owner group.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to file or folder.

Throws

• \Error - If we could not get last modified time for a path.

Returns

• int - The time the file was last modified. The time is returned as a Unix timestamp.

# method: lastChanged

final public static FileSystem::lastChanged(string $path):int

Important

This method is marked as final.

Note

In most Unix filesystems, a file is considered changed when its inode data is changed; that is, when the permissions, owner, group, or other metadata from the inode is updated. See also FileSystem#lastModified() (which is what you want to use when you want to create "Last Modified" footers on web pages) and FileSystem#lastAccessed().> [!NOTE] On Windows, this function will return creating time, but on UNIX inode change time.> [!NOTE] Note that time resolution may differ from one file system to another.> [!NOTE] The results of this function are cached. See FileSystem#clearCache() for more details.

### Gets inode change time of a path

Represents the time when the metadata or inode data of a file is altered, such as the change of permissions, ownership or group.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to file or folder.

Throws

• \Error - If we could not get last changed time for a path.

Returns

• int - The time the file was last changed. The time is returned as a Unix timestamp.

# method: setLastAccessedAndModification

final public static FileSystem::setLastAccessedAndModification(string $path, null|int $last_accessed = null, null|int $last_modified = null):true

Important

This method is marked as final.

Note

If the file does not exist, it will be created.> [!NOTE] Note that time resolution may differ from one file system to another.

### Sets last access and modification time of a path

Attempts to set the access and modification times of the file named in the filename parameter to the value given in mtime. Note that the access time is always modified, regardless of the number of parameters.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to file or folder.
• null or int $last_accessed = null - [optional] The touch time. If mtime is null, the current system time() is used.
• null or int $last_modified = null - [optional] If not null, the access time of the given filename is set to the value of atime. Otherwise, it is set to the value passed to the mtime parameter. If both are null, the current system time is used.

Throws

• \Error - If we could not set last access and modification time of a path.

Returns

• true - True on success.

# method: inode

final public static FileSystem::inode(string $path):int

Important

This method is marked as final.

Note

The results of this function are cached. See FileSystem#clearCache() for more details.

### Gets file inode

Inode are special disk blocks they are created when the file system is created.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to file or folder.

Throws

• \Error - If we don't get inode for a path.

Returns

• int - The inode number of the file.

# method: list

final public static FileSystem::list(string $folder, null|\FireHub\Core\Support\Enums\Order $order = null):array

Important

This method is marked as final.

### List files and folders inside the specified folder

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $folder - non-empty-string The folder that will be scanned.
• null or \FireHub\Core\Support\Enums\Order $order = null - [optional] Result order.

Throws

• \Error - If $folder is empty, or we could not list files and directories inside the specified folder.

Returns

• array - string[] An array of filenames.

# method: search

final public static FileSystem::search(string $pattern, bool $only_folders = false):array

Important

This method is marked as final.

Note

This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.> [!NOTE] This function isn't available on some systems (e.g., old Sun OS).

### Find path-names matching a pattern

This method searches for all the path-names matching patterns according to the rules used by the libc glob() function, which is similar to the rules used by common shells.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $pattern - _non-empty-string The pattern. No tilde expansion or parameter substitution is done.

• • • Matches zero or more characters.
• ? - Matches exactly one character (any character).
• [...] - Matches one character from a group of characters. If the first character is !, matches any character not in the group.
• \ - Escapes the following character._

• bool $only_folders = false - [optional] Return only directory entries which match the pattern.

Throws

• \Error - If there was an error while searching for a path.

Returns

• array - string[] An array containing the matched files/folders, an empty array if no file matched.

# method: symlink

final public static FileSystem::symlink(string $path, string $link):void

Important

This method is marked as final.

### Creates a symbolic link

Creates a symbolic link to the existing $path with the specified name $link.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the symlink.
• string $link - non-empty-string The link name.

Throws

• \Error - If we could not create symlink for a path with link.

Returns

• void

# method: symlinkTarget

final public static FileSystem::symlinkTarget(string $path):string

Important

This method is marked as final.

### Returns the target of a symbolic link

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the symlink.

Throws

• \Error - If we could not target for a path.

Returns

• string - The contents of the symbolic link path.

# method: symlinkGroup

final public static FileSystem::symlinkGroup(string $path, string|int $group):void

Important

This method is marked as final.

Note

This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.> [!NOTE] This function is not implemented on Windows platforms.> [!TIP] Use posix_getgrgid() to resolve it to a group name.

### Changes group ownership of symlink

Attempts to change the group of the symlink filenames to group. Only the superuser may change the group of a symlink arbitrarily. Other users may change the group of a symlink to any group of which that user is a member.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the symlink.
• string or int $group - non-empty-string|int The group specified by name or number.

Throws

• \Error - If we could not change a symlink group.

Returns

• void

# method: symlinkOwner

final public static FileSystem::symlinkOwner(string $path, string|int $user):void

Important

This method is marked as final.

Note

This function will not work on remote files as the file to be examined must be accessible via the server's filesystem.> [!NOTE] This function is not implemented on Windows platforms.> [!TIP] Use posix_getpwuid() to resolve it to a username.

### Changes user ownership of symlink

Attempts to change the owner of the symlink $path to user $user. Only the superuser may change the owner of a symlink.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the symlink.
• string or int $user - non-empty-string|int Username or number.

Throws

• \Error - If we could not change symlink ownership.

Returns

• void

# method: statistics

final public static FileSystem::statistics(string $path, bool $symlink = false):array

Important

This method is marked as final.

### Gives information about a file or folder

Gathers the statistics of the file named by filename. If filename is a symbolic link, statistics are from the file itself, not the symlink - use $symlink argument to change that behavior.

_{Source code:  view source code
Blame:  view blame}

Parameters

• string $path - non-empty-string Path to the file or folder.
• bool $symlink = false - [optional] If true, the method gives information about a file or symbolic link.

Throws

• \Error - If we could not get statistics for a path.

Returns

• array - array<0|1|2|3|4|5|6|7|8|9|10|11|12|'atime'|'blksize'|'blocks'|'ctime'|'dev'|'gid'|'ino'|'mode'|'mtime'|'nlink'|'rdev'|'size'|'uid', int> ]] Statistics about file or folder.

# method: clearCache

final public static FileSystem::clearCache(bool $clear_realpath_cache = false, string $path = ''):void

Important

This method is marked as final.

Note

This function caches information about specific filenames, so you only need to call clearCache() if you are performing multiple operations on the same filename and require the information about that particular file to not be cached.

### Clears file status cache

When you use FileSystem#statistics() or any of the other functions listed in the affected functions list (below), PHP caches the information those functions return to provide faster performance. However, in certain cases, you may want to clear the cached information. For instance, if the same file is being checked multiple times within a single script, and that file is in danger of being removed or changed during that script's operation, you may elect to clear the status cache. In these cases, you can use the FileSystem#clearCache() function to clear the information that PHP caches about a file. You should also note that PHP doesn't cache information about non-existent files. So, if you call FileSystem#exist() on a file which doesn't exist, it will return false until you create the file. If you create the file, it will return true even if you then delete the file. However, File#delete() clears the cache automatically.

_{Source code:  view source code
Blame:  view blame}

Parameters

• bool $clear_realpath_cache = false - [optional] Whether to also clear the realpath cache.
• string $path = '' - [optional] Clear the realpath cache for a specific filename only. Only used if $clear_realpath_cache is true.

Returns

• void