IOHelper

Type
Class
Namespace
Craft
Inherits
Craft\IOHelper
Since
1.0

Class IOHelper

See also http://craftcms.com

View source (opens new window)

# Public Methods

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

# changeGroup()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if successful, 'false' if not, or the given path does not exist.

Signature

public static boolean changeGroup ( $path, $group, $recursive = false, $suppressErrors = false )

# changeOwner()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if successful, 'false' if not or the given path does not exist.

Signature

public static boolean changeOwner ( $path, $owner, $recursive = false, $suppressErrors = false )

# changePermissions()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if successful, 'false' if not or the path does not exist.

Signature

public static boolean changePermissions ( $path, $permissions, $suppressErrors = false )

# cleanFilename()

Cleans a filename.

View source (opens new window)

Arguments

Returns

string (opens new window) – The cleansed filename.

Signature

public static string cleanFilename ( $fileName, $onlyAscii = false, $separator = '-' )

# cleanPath()

Cleans a path.

View source (opens new window)

Arguments

Returns

string (opens new window) – The cleansed path.

Signature

public static string cleanPath ( $path, $onlyAscii = false, $separator = '-' )

# clearFile()

Purges the contents of a file.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if the file was successfully cleared, 'false' if it wasn't, if the file is not writable or the file does not exist.

Signature

public static boolean clearFile ( $path, $suppressErrors = false )

# clearFolder()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if is successfully purges the folder, 'false' if the folder does not exist.

Signature

public static boolean clearFolder ( $path, $suppressErrors = false )

# copyFile()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if the copy was successful, 'false' if it was not, the source file is not readable or does not exist.

Signature

public static boolean copyFile ( $path, $destination, $suppressErrors = false )

# copyFolder()

Will copy the contents of one folder to another.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – '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.

Signature

public static boolean copyFolder ( $path, $destination, $validate = false, $suppressErrors = false )

# createFile()

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

View source (opens new window)

Arguments

Returns

Craft\File, boolean (opens new window) – The newly created file as a {@link File} object or false if we don't have write permissions.

Signature

public static Craft\File, boolean createFile ( $path, $suppressErrors = false )

# createFolder()

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

View source (opens new window)

Arguments

Returns

Craft\Folder, boolean (opens new window) – The newly created folder as a {@link Folder} object or false if we don't have write permissions.

Signature

public static Craft\Folder, boolean createFolder ( $path, $permissions = null, $suppressErrors = false )

# deleteFile()

Deletes a file from the file system.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if successful, 'false' if it cannot be deleted, it does not exist or it is not writable.

Signature

public static boolean deleteFile ( $path, $suppressErrors = false )

# deleteFolder()

Deletes a folder from the file system.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if successful, 'false' if it cannot be deleted, it does not exist or it is not writable.

Signature

public static boolean deleteFolder ( $path, $suppressErrors = false )

# ensureFolderExists()

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

View source (opens new window)

Arguments

Returns

null (opens new window)

Signature

public static null ensureFolderExists ( $folderPath, $suppressErrors = false )

# fileExists()

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

View source (opens new window)

Arguments

Returns

string (opens new window) – The resolved path of the file if it exists.

Signature

public static string fileExists ( $path, $caseInsensitive = false, $suppressErrors = false )

# folderExists()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if the folder exists, otherwise 'false'.

Signature

public static boolean folderExists ( $path, $caseInsensitive = false, $suppressErrors = false )

# getAllowedFileExtensions()

Get a list of allowed file extensions.

View source (opens new window)

Returns

array (opens new window)

Signature

public static array getAllowedFileExtensions ( )

# getDefaultFolderPermissions()

DEPRECATED

Deprecated Deprecated in 2.2. Use {@link ConfigService::get() craft()->config->get('defaultFolderPermissions')} instead.

Gets the default folder permissions from the config service.

View source (opens new window)

Returns

mixed

Signature

public static mixed getDefaultFolderPermissions ( )

# getExtension()

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

View source (opens new window)

Arguments

Returns

string (opens new window) – The file extension.

Signature

public static string getExtension ( $path, $default = null, $suppressErrors = false )

# getFile()

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

View source (opens new window)

Arguments

Returns

Craft\File, boolean (opens new window)

Signature

public static Craft\File, boolean getFile ( $path, $suppressErrors = false )

# getFileContents()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window), string (opens new window), array (opens new window) – The contents of the file as a string, an array, or false if the file does not exist or is not readable.

Signature

public static boolean, string, array getFileContents ( $path, $array = false, $suppressErrors = false )

# getFileKind()

Signature

public static integer, string getFileKind ( $extension )

# getFileKindLabel()

Returns the label of a given file kind.

View source (opens new window)

Arguments

Returns

array (opens new window)

Signature

public static array getFileKindLabel ( $kind )

# getFileKinds()

Returns a list of file kinds.

View source (opens new window)

Returns

array (opens new window)

Signature

public static array getFileKinds ( )

# getFileMD5()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window), string (opens new window) – The MD5 hash or false if it does not exist, isn't readable or could not be calculated.

Signature

public static boolean, string getFileMD5 ( $path, $suppressErrors = false )

# getFileName()

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

View source (opens new window)

Arguments

Returns

string (opens new window) – The file name with or without the extension.

Signature

public static string getFileName ( $path, $includeExtension = true, $suppressErrors = false )

# getFileSize()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window), string (opens new window) – The file size in bytes or false if the file does not exist.

Signature

public static boolean, string getFileSize ( $path, $suppressErrors = false )

# getFiles()

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

View source (opens new window)

Arguments

Returns

array (opens new window), boolean (opens new window)

Signature

public static array, boolean getFiles ( $path, $suppressErrors = false )

# getFolder()

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

View source (opens new window)

Arguments

Returns

Craft\Folder, boolean (opens new window)

Signature

public static Craft\Folder, boolean getFolder ( $path, $suppressErrors = false )

# 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.

View source (opens new window)

Arguments

Returns

array (opens new window), boolean (opens new window) – An array of file and folder paths, or false if the folder does not exist or is not readable.

Signature

public static array, boolean getFolderContents ( $path, $recursive = true, $filter = null, $includeHiddenFiles = false, $suppressErrors = false )

# getFolderName()

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

View source (opens new window)

Arguments

Returns

string (opens new window) – The folder name.

Signature

public static string getFolderName ( $path, $fullPath = true, $suppressErrors = false )

# getFolderSize()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window), string (opens new window) – The folder size in bytes or false if the folder does not exist.

Signature

public static boolean, string getFolderSize ( $path, $suppressErrors = false )

# getFolders()

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

View source (opens new window)

Arguments

Returns

array (opens new window), boolean (opens new window)

Signature

public static array, boolean getFolders ( $path, $suppressErrors = false )

# getGroup()

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

View source (opens new window)

Arguments

Returns

mixed – Group name, or ID if $getName set to 'false' or false if the file or folder does not exist.

Signature

public static mixed getGroup ( $path, $getName = true, $suppressErrors = false )

# getLastModifiedFiles()

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

View source (opens new window)

Arguments

Returns

array (opens new window)

Signature

public static array getLastModifiedFiles ( $folder, $number = null, $suppressErrors = false )

# getLastTimeModified()

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

View source (opens new window)

Arguments

Returns

integer (opens new window), boolean (opens new window) – The last modified timestamp or false if the file or folder does not exist.

Signature

public static integer, boolean getLastTimeModified ( $path, $suppressErrors = false )

# getMimeType()

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

View source (opens new window)

Arguments

Returns

string (opens new window) – The mime type.

Signature

public static string getMimeType ( $path )

# getMimeTypeByExtension()

A wrapper for {@link FileHelper::getMimeTypeByExtension()}.

View source (opens new window)

Arguments

Returns

string (opens new window) – The mime type.

Signature

public static string getMimeTypeByExtension ( $path )

# getOwner()

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

View source (opens new window)

Arguments

Returns

mixed – Owner name, or ID if $getName set to 'false' or false if the file or folder does not exist.

Signature

public static mixed getOwner ( $path, $getName = true, $suppressErrors = false )

# getParentFolderPath()

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

View source (opens new window)

Arguments

Returns

string (opens new window)

Signature

public static string getParentFolderPath ( $fullPath )

# getPermissions()

Returns permissions of current filesystem object (UNIX systems).

View source (opens new window)

Arguments

Returns

string (opens new window) – Filesystem object permissions in octal format (i.e. '0755'), false if the file or folder doesn't exist

Signature

public static string getPermissions ( $path, $suppressErrors = false )

# getRealPath()

Returns the real filesystem path of the given path.

View source (opens new window)

Arguments

Returns

string (opens new window), false (opens new window) – The real file or folder path, or falseif the file doesn’t exist.

Signature

public static string, false getRealPath ( $path, $suppressErrors = false )

# getWritableFilePermissions()

DEPRECATED

Deprecated Deprecated in 2.2. Use {@link ConfigService::get() craft()->config->get('defaultFilePermissions')} instead.

Gets the writable file permissions from the config service.

View source (opens new window)

Returns

mixed

Signature

public static mixed getWritableFilePermissions ( )

# getWritableFolderPermissions()

DEPRECATED

Deprecated Deprecated in 2.2. Use {@link ConfigService::get() craft()->config->get('defaultFolderPermissions')} instead.

Gets the writable folder permissions from the config service.

View source (opens new window)

Returns

mixed

Signature

public static mixed getWritableFolderPermissions ( )

# handleError()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window)

Throws

Signature

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

# isExtensionAllowed()

Returns whether the extension is allowed.

View source (opens new window)

Arguments

  • $extension

Returns

boolean (opens new window)

Signature

public static boolean isExtensionAllowed ( $extension )

# isFileEmpty()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the file is empty or not.

Signature

public static boolean isFileEmpty ( $path, $suppressErrors = false )

# isFolderEmpty()

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

View source (opens new window)

Arguments

Returns

boolean (opens new window) – Whether the folder is empty or not.

Signature

public static boolean isFolderEmpty ( $path, $suppressErrors = false )

# isReadable()

Tests whether the give filesystem path is readable.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if filesystem path is readable, otherwise 'false'.

Signature

public static boolean isReadable ( $path, $suppressErrors = false )

# 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}.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if filesystem object is writable, otherwise 'false'.

Signature

public static boolean isWritable ( $path, $suppressErrors = false )

# move()

Moves a file from one location on disk to another.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if the file was successfully moved, 'false', otherwise.

Signature

public static boolean move ( $path, $newPath, $suppressErrors = false )

# 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.

View source (opens new window)

Arguments

Returns

string (opens new window) – The normalized path.

Signature

public static string normalizePathSeparators ( $path )

# rename()

Renames a given file or folder to a new name.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' if successful, 'false' if not or the source file or folder does not exist.

Signature

public static boolean rename ( $path, $newName, $suppressErrors = false )

# 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.

View source (opens new window)

Arguments

Returns

boolean (opens new window)

Signature

public static boolean touch ( $fileName, $time = null, $suppressErrors = false )

# writeToFile()

Will write $contents to a file.

View source (opens new window)

Arguments

Returns

boolean (opens new window) – 'true' upon successful writing to the file, otherwise false.

Signature

public static boolean writeToFile ( $path, $contents, $autoCreate = true, $append = false, $noFileLock = null, $suppressErrors = false )