Craft 2 Class Reference

Class IOHelper

Package
craft.app.helpers
Namespace
Craft
Inheritance
class IOHelper
Since
1.0
Source Code
craft/app/helpers/IOHelper.php

Class IOHelper

Public Methods
Method Description Defined By
changeGroup() Will attempt to change the group of the given file system path (*nix only) IOHelper
changeOwner() Will attempt to change the owner of the given file system path (*nix only) IOHelper
changePermissions() Will attempt to change the permission of the given file system path (*nix only). IOHelper
cleanFilename() Cleans a filename. IOHelper
cleanPath() Cleans a path. IOHelper
clearFile() Purges the contents of a file. IOHelper
clearFolder() Purges the contents of a folder while leaving the folder itself. IOHelper
copyFile() Will copy a file from one path to another and create folders if necessary. IOHelper
copyFolder() Will copy the contents of one folder to another. IOHelper
createFile() Will create a file on the file system at the given path and return a File object or false if we don't have write permissions. IOHelper
createFolder() Will create a folder on the file system at the given path and return a Folder object or false if we don't have write permissions. IOHelper
deleteFile() Deletes a file from the file system. IOHelper
deleteFolder() Deletes a folder from the file system. IOHelper
ensureFolderExists() Makes sure a folder exists. If it does not - creates one with write permissions IOHelper
fileExists() Tests whether the given file path exists on the file system. IOHelper
folderExists() Tests whether the given folder path exists on the file system. IOHelper
getAllowedFileExtensions() Get a list of allowed file extensions. IOHelper
getDefaultFolderPermissions() Gets the default folder permissions from the config service. IOHelper
getExtension() Returns the file extension for the given path. If there is not one, then $default is returned instead. IOHelper
getFile() If the file exists on the file system will return a new File instance, otherwise, false. IOHelper
getFileContents() Will return the contents of the file as a string or an array if it exists and is readable, otherwise false. IOHelper
getFileKind() Return a file's kind by extension. IOHelper
getFileKindLabel() Returns the label of a given file kind. IOHelper
getFileKinds() Returns a list of file kinds. IOHelper
getFileMD5() Calculates the MD5 hash for a given file path or false if one could not be calculated or the file does not exist. IOHelper
getFileName() Will return the file name of the given path with or without the extension. IOHelper
getFileSize() Returns the file size in bytes for the given path or false if the file does not exist. IOHelper
getFiles() If the path exists on the file system, will return the paths of any files that are contained within it. IOHelper
getFolder() If the folder exists on the file system, will return a new Folder instance, otherwise, false. IOHelper
getFolderContents() Returns the contents of a folder as an array of file and folder paths, or false if the folder does not exist or is not readable. IOHelper
getFolderName() Will return the folder name of the given path either as the full path or only the single top level folder. IOHelper
getFolderSize() Returns the folder size in bytes for the given path or false if the folder does not exist. IOHelper
getFolders() If the path exists on the file system, will return the paths of any folders that are contained within it. IOHelper
getGroup() Returns group of current filesystem object (UNIX systems). Returned value depends upon $getName parameter value. IOHelper
getLastModifiedFiles() Returns the last $number of modified files from a given folder ordered by the last modified date descending. IOHelper
getLastTimeModified() Returns the last modified time for the given path in DateTime format or false if the file or folder does not exist. IOHelper
getMimeType() If the path points to a real file, we call FileHelper::getMimeType(), otherwise FileHelper::getMimeTypeByExtension() IOHelper
getMimeTypeByExtension() A wrapper for FileHelper::getMimeTypeByExtension(). IOHelper
getOwner() Returns owner of current filesystem object (UNIX systems). Returned value depends upon $getName parameter value. IOHelper
getParentFolderPath() Returns a parent folder's path for a given path. IOHelper
getPermissions() Returns permissions of current filesystem object (UNIX systems). IOHelper
getRealPath() Returns the real filesystem path of the given path. IOHelper
getWritableFilePermissions() Gets the writable file permissions from the config service. IOHelper
getWritableFolderPermissions() Gets the writable folder permissions from the config service. IOHelper
handleError() Custom error handler used in IOHelper used for detecting if the file system supports exclusive locks when writing. IOHelper
isExtensionAllowed() Returns whether the extension is allowed. IOHelper
isFileEmpty() Will take a path, make sure the file exists and if the size of the file is 0 bytes, return true. Otherwise false. IOHelper
isFolderEmpty() Will take a path, make sure the folder exists and if the size of the folder is 0 bytes, return true. Otherwise false. IOHelper
isReadable() Tests whether the give filesystem path is readable. IOHelper
isWritable() Tests file and folder write-ability by attempting to create a temp file on the filesystem. PHP's is_writable has problems (especially on Windows). {@see https://bugs.php.net/bug.php?id=27609} and {@see https://bugs.php.net/bug.php?id=30931}. IOHelper
move() Moves a file from one location on disk to another. IOHelper
normalizePathSeparators() Will take a given path and normalize it to use single forward slashes for path separators. If it is a folder, it will append a trailing forward slash to the end of the path. IOHelper
rename() Renames a given file or folder to a new name. IOHelper
touch() Will set the access and modification times of the given file to the given time, or the current time if it is not supplied. IOHelper
writeToFile() Will write $contents to a file. IOHelper

Method Details

changeGroup() public static method #

Will attempt to change the group of the given file system path (*nix only)

public static bool changeGroup(string $path, string $group, bool $recursive = false, bool $suppressErrors = false)
$path string The path to change the group of.
$group string The new group name.
$recursive bool If the path is a directory, whether to recursively change the group of the child files and folders.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if successful, 'false' if not, or the given path does not exist.

changeOwner() public static method #

Will attempt to change the owner of the given file system path (*nix only)

public static bool changeOwner(string $path, string $owner, bool $recursive = false, bool $suppressErrors = false)
$path string The path to change the owner of.
$owner string The new owner's name.
$recursive bool If the path is a folder, whether to change the owner of all of the folder's children.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if successful, 'false' if not or the given path does not exist.

changePermissions() public static method #

Will attempt to change the permission of the given file system path (*nix only).

public static bool changePermissions(string $path, int $permissions, bool $suppressErrors = false)
$path string The path to change the permissions of.
$permissions int The new permissions.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if successful, 'false' if not or the path does not exist.

cleanFilename() public static method #

Cleans a filename.

public static string cleanFilename(string $fileName, bool $onlyAscii = false, string $separator = '-')
$fileName string The filename to clean.
$onlyAscii bool Whether to only allow ASCII characters in the filename.
$separator string The separator to use for any whitespace. Defaults to '-'.
Returns string The cleansed filename.

cleanPath() public static method #

Cleans a path.

public static string cleanPath(string $path, bool $onlyAscii = false, string $separator = '-')
$path string The path to clean.
$onlyAscii bool Whether to only allow ASCII characters in the path.
$separator string The separator to use for any whitespace. Defaults to '-'.
Returns string The cleansed path.

clearFile() public static method #

Purges the contents of a file.

public static bool clearFile(string $path, bool $suppressErrors = false)
$path string The path of the file to clear.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if the file was successfully cleared, 'false' if it wasn't, if the file is not writable or the file does not exist.

clearFolder() public static method #

Purges the contents of a folder while leaving the folder itself.

public static bool clearFolder(string $path, bool $suppressErrors = false)
$path string The path of the folder to clear.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if is successfully purges the folder, 'false' if the folder does not exist.

copyFile() public static method #

Will copy a file from one path to another and create folders if necessary.

public static bool copyFile(string $path, string $destination, bool $suppressErrors = false)
$path string The source path of the file.
$destination string The destination path to copy the file to.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if the copy was successful, 'false' if it was not, the source file is not readable or does not exist.

copyFolder() public static method #

Will copy the contents of one folder to another.

public static bool copyFolder(string $path, string $destination, bool $validate = false, bool $suppressErrors = false)
$path string The source path to copy.
$destination string The destination path to copy to.
$validate bool Whether to compare the size of the folders after the copy is complete.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if the copy was successful, 'false' if it was not, or $validate is true and the size of the folders do not match after the copy.

createFile() public static method #

Will create a file on the file system at the given path and return a File object or false if we don't have write permissions.

public static File|bool createFile(string $path, bool $suppressErrors = false)
$path string The path of the file to create.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns File / bool The newly created file as a File object or false if we don't have write permissions.

createFolder() public static method #

Will create a folder on the file system at the given path and return a Folder object or false if we don't have write permissions.

public static Folder|bool createFolder(string $path, int $permissions = null, bool $suppressErrors = false)
$path string The path of the file to create.
$permissions int The permissions to set the folder to.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns Folder / bool The newly created folder as a Folder object or false if we don't have write permissions.

deleteFile() public static method #

Deletes a file from the file system.

public static bool deleteFile(string $path, bool $suppressErrors = false)
$path string The path of the file to delete.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if successful, 'false' if it cannot be deleted, it does not exist or it is not writable.

deleteFolder() public static method #

Deletes a folder from the file system.

public static bool deleteFolder(string $path, bool $suppressErrors = false)
$path string The path of the folder to delete.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if successful, 'false' if it cannot be deleted, it does not exist or it is not writable.

ensureFolderExists() public static method #

Makes sure a folder exists. If it does not - creates one with write permissions

public static null ensureFolderExists(string $folderPath, bool $suppressErrors = false)
$folderPath string The path to the folder.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).

fileExists() public static method #

Tests whether the given file path exists on the file system.

public static string fileExists(string $path, bool $caseInsensitive = false, bool $suppressErrors = false)
$path string The path to test.
$caseInsensitive bool Whether to perform a case insensitive check or not.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns string The resolved path of the file if it exists.

folderExists() public static method #

Tests whether the given folder path exists on the file system.

public static bool folderExists(string $path, bool $caseInsensitive = false, bool $suppressErrors = false)
$path string The path to test.
$caseInsensitive bool Whether to perform a case insensitive check or not.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if the folder exists, otherwise 'false'.

getAllowedFileExtensions() public static method #

Get a list of allowed file extensions.

public static array getAllowedFileExtensions()
Returns array

getDefaultFolderPermissions() public static method #

Gets the default folder permissions from the config service.

Deprecated in 2.2. Use craft()->config->get('defaultFolderPermissions') instead.

public static mixed getDefaultFolderPermissions()
Returns mixed

getExtension() public static method #

Returns the file extension for the given path. If there is not one, then $default is returned instead.

public static string getExtension(string $path, null|string $default = null, bool $suppressErrors = false)
$path string The path to test.
$default null / string If the file has no extension, this one will be returned by default.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns string The file extension.

getFile() public static method #

If the file exists on the file system will return a new File instance, otherwise, false.

public static File|bool getFile(string $path, bool $suppressErrors = false)
$path string The path to the file.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns File / bool

getFileContents() public static method #

Will return the contents of the file as a string or an array if it exists and is readable, otherwise false.

public static bool|string|array getFileContents(string $path, bool $array = false, bool $suppressErrors = false)
$path string The path of the file.
$array bool Whether to return the contents of the file as an array or not.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool / string / array The contents of the file as a string, an array, or false if the file does not exist or is not readable.

getFileKind() public static method #

Return a file's kind by extension.

public static int|string getFileKind(string $extension)
$extension string
Returns int / string

getFileKindLabel() public static method #

Returns the label of a given file kind.

public static array getFileKindLabel(string $kind)
$kind string
Returns array

getFileKinds() public static method #

Returns a list of file kinds.

public static array getFileKinds()
Returns array

getFileMD5() public static method #

Calculates the MD5 hash for a given file path or false if one could not be calculated or the file does not exist.

public static bool|string getFileMD5(string $path, bool $suppressErrors = false)
$path string The path of the file to calculate.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool / string The MD5 hash or false if it does not exist, isn't readable or could not be calculated.

getFileName() public static method #

Will return the file name of the given path with or without the extension.

public static string getFileName(string $path, bool $includeExtension = true, bool $suppressErrors = false)
$path string The path to test.
$includeExtension bool Whether to include the extension in the file name.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns string The file name with or without the extension.

getFileSize() public static method #

Returns the file size in bytes for the given path or false if the file does not exist.

public static bool|string getFileSize(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool / string The file size in bytes or false if the file does not exist.

getFiles() public static method #

If the path exists on the file system, will return the paths of any files that are contained within it.

public static array|bool getFiles(string $path, bool $suppressErrors = false)
$path string The folder path to check
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns array / bool

getFolder() public static method #

If the folder exists on the file system, will return a new Folder instance, otherwise, false.

public static Folder|bool getFolder(string $path, bool $suppressErrors = false)
$path string The path to the folder.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns Folder / bool

getFolderContents() public static method #

Returns the contents of a folder as an array of file and folder paths, or false if the folder does not exist or is not readable.

public static array|bool getFolderContents(string $path, bool $recursive = true, bool $filter = null, bool $includeHiddenFiles = false, bool $suppressErrors = false)
$path string The path to test.
$recursive bool Whether to do a recursive folder search.
$filter bool The filter to use when performing the search.
$includeHiddenFiles bool Whether to include hidden files (that start with a .) in the results.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns array / bool An array of file and folder paths, or false if the folder does not exist or is not readable.

getFolderName() public static method #

Will return the folder name of the given path either as the full path or only the single top level folder.

public static string getFolderName(string $path, bool $fullPath = true, bool $suppressErrors = false)
$path string The path to test.
$fullPath bool Whether to include the full path in the return results or the top level folder only.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns string The folder name.

getFolderSize() public static method #

Returns the folder size in bytes for the given path or false if the folder does not exist.

public static bool|string getFolderSize(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool / string The folder size in bytes or false if the folder does not exist.

getFolders() public static method #

If the path exists on the file system, will return the paths of any folders that are contained within it.

public static array|bool getFolders(string $path, bool $suppressErrors = false)
$path string The folder path to check
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns array / bool

getGroup() public static method #

Returns group of current filesystem object (UNIX systems). Returned value depends upon $getName parameter value.

public static mixed getGroup(string $path, bool $getName = true, bool $suppressErrors = false)
$path string The path to check.
$getName bool Defaults to 'true', meaning that group name instead of ID should be returned.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns mixed Group name, or ID if $getName set to 'false' or false if the file or folder does not exist.

getLastModifiedFiles() public static method #

Returns the last $number of modified files from a given folder ordered by the last modified date descending.

public static array getLastModifiedFiles(string $folder, int $number = null, bool $suppressErrors = false)
$folder string The folder to get the files from.
$number int The number of files to return. If null is given, all files will be returned.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns array

getLastTimeModified() public static method #

Returns the last modified time for the given path in DateTime format or false if the file or folder does not exist.

public static int|bool getLastTimeModified(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns int / bool The last modified timestamp or false if the file or folder does not exist.

getMimeType() public static method #

If the path points to a real file, we call FileHelper::getMimeType(), otherwise FileHelper::getMimeTypeByExtension()

public static string getMimeType(string $path)
$path string The path to test.
Returns string The mime type.

getMimeTypeByExtension() public static method #

A wrapper for FileHelper::getMimeTypeByExtension().

public static string getMimeTypeByExtension(string $path)
$path string The path to test.
Returns string The mime type.

getOwner() public static method #

Returns owner of current filesystem object (UNIX systems). Returned value depends upon $getName parameter value.

public static mixed getOwner(string $path, bool $getName = true, bool $suppressErrors = false)
$path string The path to check.
$getName bool Defaults to 'true', meaning that owner name instead of ID should be returned.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns mixed Owner name, or ID if $getName set to 'false' or false if the file or folder does not exist.

getParentFolderPath() public static method #

Returns a parent folder's path for a given path.

public static string getParentFolderPath(string $fullPath)
$fullPath string The path to get the parent folder path for.
Returns string

getPermissions() public static method #

Returns permissions of current filesystem object (UNIX systems).

public static string getPermissions(string $path, bool $suppressErrors = false)
$path string The path to check
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns string Filesystem object permissions in octal format (i.e. '0755'), false if the file or folder doesn't exist

getRealPath() public static method #

Returns the real filesystem path of the given path.

public static string|false getRealPath(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns string / false The real file or folder path, or falseif the file doesn’t exist.

getWritableFilePermissions() public static method #

Gets the writable file permissions from the config service.

Deprecated in 2.2. Use craft()->config->get('defaultFilePermissions') instead.

public static mixed getWritableFilePermissions()
Returns mixed

getWritableFolderPermissions() public static method #

Gets the writable folder permissions from the config service.

Deprecated in 2.2. Use craft()->config->get('defaultFolderPermissions') instead.

public static mixed getWritableFolderPermissions()
Returns mixed

handleError() public method #

Custom error handler used in IOHelper used for detecting if the file system supports exclusive locks when writing.

public bool handleError($errNo $errNo, $errStr $errStr, $errFile $errFile, $errLine $errLine, array $errContext)
$errNo $errNo
$errStr $errStr
$errFile $errFile
$errLine $errLine
$errContext array
Returns bool

isExtensionAllowed() public static method #

Returns whether the extension is allowed.

public static bool isExtensionAllowed($extension $extension)
$extension $extension
Returns bool

isFileEmpty() public static method #

Will take a path, make sure the file exists and if the size of the file is 0 bytes, return true. Otherwise false.

public static bool isFileEmpty(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool Whether the file is empty or not.

isFolderEmpty() public static method #

Will take a path, make sure the folder exists and if the size of the folder is 0 bytes, return true. Otherwise false.

public static bool isFolderEmpty(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool Whether the folder is empty or not.

isReadable() public static method #

Tests whether the give filesystem path is readable.

public static bool isReadable(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if filesystem path is readable, otherwise 'false'.

isWritable() public static method #

Tests file and folder write-ability by attempting to create a temp file on the filesystem. PHP's is_writable has problems (especially on Windows). {@see https://bugs.php.net/bug.php?id=27609} and {@see https://bugs.php.net/bug.php?id=30931}.

public static bool isWritable(string $path, bool $suppressErrors = false)
$path string The path to test.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if filesystem object is writable, otherwise 'false'.

move() public static method #

Moves a file from one location on disk to another.

public static bool move(string $path, string $newPath, bool $suppressErrors = false)
$path string The original path of the file/folder to move.
$newPath string The new path the file/folder should be moved to.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if the file was successfully moved, 'false', otherwise.

normalizePathSeparators() public static method #

Will take a given path and normalize it to use single forward slashes for path separators. If it is a folder, it will append a trailing forward slash to the end of the path.

public static string normalizePathSeparators(string $path)
$path string The path to normalize.
Returns string The normalized path.

rename() public static method #

Renames a given file or folder to a new name.

public static bool rename(string $path, string $newName, bool $suppressErrors = false)
$path string The original path of the file or folder.
$newName string The new name of the file or folder.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' if successful, 'false' if not or the source file or folder does not exist.

touch() public static method #

Will set the access and modification times of the given file to the given time, or the current time if it is not supplied.

public static bool touch(string $fileName, null $time = null, bool $suppressErrors = false)
$fileName string The path to the file/folder to touch.
$time null The time to set on the file/folder. If none is provided, will default to the current time.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool

writeToFile() public static method #

Will write $contents to a file.

public static bool writeToFile(string $path, string $contents, bool $autoCreate = true, bool $append = false, bool|null $noFileLock = null, bool $suppressErrors = false)
$path string The path of the file to write to.
$contents string The contents to be written to the file.
$autoCreate bool Whether or not to auto-create the file if it does not exist.
$append bool If true, will append the data to the contents of the file, otherwise it will overwrite the contents.
$noFileLock bool / null Whether to use file locking when writing to the file.
$suppressErrors bool Whether to suppress any PHP Notices/Warnings/Errors (usually permissions related).
Returns bool 'true' upon successful writing to the file, otherwise false.