Craft 3 Class Reference

Class craft\helpers\FileHelper

Inheritance
craft\helpers\FileHelper » yii\helpers\FileHelper » yii\helpers\BaseFileHelper
Available since version
3.0
Source Code
https://github.com/craftcms/cms/blob/master/src/helpers/FileHelper.php

Class FileHelper

Public Properties
Property Type Description Defined By
$mimeAliasesFile string The path (or alias) of a PHP file containing MIME aliases. yii\helpers\BaseFileHelper
$mimeMagicFile string The path (or alias) of a PHP file containing MIME type information. craft\helpers\FileHelper
Public Methods
Method Description Defined By
clearDirectory() Removes all of a directory’s contents recursively. craft\helpers\FileHelper
copyDirectory() Copies a whole directory as another one. craft\helpers\FileHelper
createDirectory() Creates a new directory. craft\helpers\FileHelper
filterPath() Checks if the given file path satisfies the filtering options. yii\helpers\BaseFileHelper
findDirectories() Returns the directories found under the specified directory and subdirectories. yii\helpers\BaseFileHelper
findFiles() Returns the files found under the specified directory and subdirectories. yii\helpers\BaseFileHelper
getExtensionsByMimeType() Determines the extensions by given MIME type. yii\helpers\BaseFileHelper
getMimeType() Determines the MIME type of the specified file. craft\helpers\FileHelper
getMimeTypeByExtension() Determines the MIME type based on the extension name of the specified file. yii\helpers\BaseFileHelper
hasAnythingChanged() Returns whether any files in a source directory have changed, compared to another directory. craft\helpers\FileHelper
isDirectoryEmpty() Returns whether a given directory is empty (has no files) recursively. craft\helpers\FileHelper
isSvg() Returns whether the given file path is an SVG image. craft\helpers\FileHelper
isWritable() Tests whether a file/directory is writable. craft\helpers\FileHelper
lastModifiedTime() Returns the last modification time for the given path. craft\helpers\FileHelper
localize() Returns the localized version of a specified file. yii\helpers\BaseFileHelper
normalizePath() Normalizes a file/directory path. craft\helpers\FileHelper
removeDirectory() Removes a directory (and all its content) recursively. craft\helpers\FileHelper
removeFile() Removes a file or symlink in a cross-platform way craft\helpers\FileHelper
sanitizeFilename() Sanitizes a filename. craft\helpers\FileHelper
unlink() Removes a file or symlink in a cross-platform way yii\helpers\BaseFileHelper
useFileLocks() Returns whether file locks can be used when writing to files. craft\helpers\FileHelper
writeToFile() Writes contents to a file. craft\helpers\FileHelper
Protected Methods
Method Description Defined By
loadMimeAliases() Loads MIME aliases from the specified file. yii\helpers\BaseFileHelper
loadMimeTypes() Loads MIME types from the specified file. yii\helpers\BaseFileHelper
normalizeOptions() yii\helpers\BaseFileHelper
Constants
Constant Value Description Defined By
PATTERN_CASE_INSENSITIVE 32 yii\helpers\BaseFileHelper
PATTERN_ENDSWITH 4 yii\helpers\BaseFileHelper
PATTERN_MUSTBEDIR 8 yii\helpers\BaseFileHelper
PATTERN_NEGATIVE 16 yii\helpers\BaseFileHelper
PATTERN_NODIR 1 yii\helpers\BaseFileHelper

Property Details

$mimeMagicFile public static property #

The path (or alias) of a PHP file containing MIME type information.

public static string $mimeMagicFile = '@app/config/mimeTypes.php'

Method Details

clearDirectory() public static method #

Removes all of a directory’s contents recursively.

public static void clearDirectory ( \craft\helpers\string $dir, array $options = [] )
$dir string The directory to be deleted recursively.
$options array Options for directory remove. Valid options are: traverseSymlinks: bool, whether symlinks to the directories should be traversed too. Defaults to false, meaning the content of the symlinked directory would not be deleted. Only symlink would be removed in that default case. filter: callback (see findFiles()) except: array (see findFiles()) only: array (see findFiles())
throws yii\base\InvalidArgumentException if the dir is invalid
throws yii\base\ErrorException in case of failure

copyDirectory() public static method #

Copies a whole directory as another one.

The files and sub-directories will also be copied over.

public static void copyDirectory ( $src, $dst, $options = [] )
$src string The source directory
$dst string The destination directory
$options array Options for directory copy. Valid options are: dirMode: integer, the permission to be set for newly copied directories. Defaults to 0775. fileMode: integer, the permission to be set for newly copied files. Defaults to the current environment setting. filter: callback, a PHP callback that is called for each directory or file. The signature of the callback should be: function ($path), where $path refers the full path to be filtered. The callback can return one of the following values: true: the directory or file will be copied (the "only" and "except" options will be ignored) false: the directory or file will NOT be copied (the "only" and "except" options will be ignored) null: the "only" and "except" options will determine whether the directory or file should be copied only: array, list of patterns that the file paths should match if they want to be copied. A path matches a pattern if it contains the pattern string at its end. For example, '.php' matches all file paths ending with '.php'. Note, the '/' characters in a pattern matches both '/' and '\' in the paths. If a file path matches a pattern in both "only" and "except", it will NOT be copied. except: array, list of patterns that the files or directories should match if they want to be excluded from being copied. A path matches a pattern if it contains the pattern string at its end. Patterns ending with '/' apply to directory paths only, and patterns not ending with '/' apply to file paths only. For example, '/a/b' matches all file paths ending with '/a/b'; and '.svn/' matches directory paths ending with '.svn'. Note, the '/' characters in a pattern matches both '/' and '\' in the paths. caseSensitive: boolean, whether patterns specified at "only" or "except" should be case sensitive. Defaults to true. recursive: boolean, whether the files under the subdirectories should also be copied. Defaults to true. beforeCopy: callback, a PHP callback that is called before copying each sub-directory or file. If the callback returns false, the copy operation for the sub-directory or file will be cancelled. The signature of the callback should be: function ($from, $to), where $from is the sub-directory or file to be copied from, while $to is the copy target. afterCopy: callback, a PHP callback that is called after each sub-directory or file is successfully copied. The signature of the callback should be: function ($from, $to), where $from is the sub-directory or file copied from, while $to is the copy target. copyEmptyDirectories: boolean, whether to copy empty directories. Set this to false to avoid creating directories that do not contain files. This affects directories that do not contain files initially as well as directories that do not contain files at the target destination because files have been filtered via only or except. Defaults to true. This option is available since version 2.0.12. Before 2.0.12 empty directories are always copied.
throws yii\base\InvalidArgumentException if unable to open directory

createDirectory() public static method #

Creates a new directory.

This method is similar to the PHP mkdir() function except that it uses chmod() to set the permission of the created directory in order to avoid the impact of the umask setting.

public static boolean createDirectory ( $path, $mode = null, $recursive = true )
$path string Path of the directory to be created.
$mode integer The permission to be set for the created directory.
$recursive boolean Whether to create parent directories if they do not exist.
return boolean Whether the directory is created successfully
throws yii\base\Exception if the directory could not be created (i.e. php error due to parallel changes)

getMimeType() public static method #

Determines the MIME type of the specified file.

This method will first try to determine the MIME type based on finfo_open. If the fileinfo extension is not installed, it will fall back to getMimeTypeByExtension() when $checkExtension is true.

public static string getMimeType ( $file, $magicFile = null, $checkExtension = true )
$file string The file name.
$magicFile string Name of the optional magic database file (or alias), usually something like /path/to/magic.mime. This will be passed as the second parameter to finfo_open() when the fileinfo extension is installed. If the MIME type is being determined based via getMimeTypeByExtension() and this is null, it will use the file specified by $mimeMagicFile.
$checkExtension boolean Whether to use the file extension to determine the MIME type in case finfo_open() cannot determine it.
return string The MIME type (e.g. text/plain). Null is returned if the MIME type cannot be determined.
throws yii\base\InvalidConfigException when the fileinfo PHP extension is not installed and $checkExtension is false.

hasAnythingChanged() public static method #

Returns whether any files in a source directory have changed, compared to another directory.

public static boolean hasAnythingChanged ( \craft\helpers\string $dir, \craft\helpers\string $ref )
$dir string The source directory to check for changes in
$ref string The reference directory
throws yii\base\InvalidArgumentException if $dir or $ref isn't a directory
throws yii\base\ErrorException if we can't get a handle on $src

isDirectoryEmpty() public static method #

Returns whether a given directory is empty (has no files) recursively.

public static boolean isDirectoryEmpty ( \craft\helpers\string $dir )
$dir string The directory to be checked
return boolean Whether the directory is empty
throws yii\base\InvalidArgumentException if the dir is invalid
throws yii\base\ErrorException in case of failure

isSvg() public static method #

Returns whether the given file path is an SVG image.

public static boolean isSvg ( \craft\helpers\string $file, \craft\helpers\string $magicFile = null, \craft\helpers\bool $checkExtension = true )
$file string The file name.
$magicFile string Name of the optional magic database file (or alias), usually something like /path/to/magic.mime. This will be passed as the second parameter to finfo_open() when the fileinfo extension is installed. If the MIME type is being determined based via getMimeTypeByExtension() and this is null, it will use the file specified by $mimeMagicFile.
$checkExtension boolean Whether to use the file extension to determine the MIME type in case finfo_open() cannot determine it.

isWritable() public static method #

Tests whether a file/directory is writable.

public static boolean isWritable ( \craft\helpers\string $path )
$path string The file/directory path to test
return boolean Whether the path is writable
throws yii\base\ErrorException in case of failure

lastModifiedTime() public static method #

Returns the last modification time for the given path.

If the path is a directory, any nested files/directories will be checked as well.

public static integer lastModifiedTime ( $path )
$path string The directory to be checked
return integer Unix timestamp representing the last modification time

normalizePath() public static method #

Normalizes a file/directory path.

The normalization does the following work:

public static string normalizePath ( $path, $ds = DIRECTORY_SEPARATOR )
$path string The file/directory path to be normalized
$ds string The directory separator to be used in the normalized result. Defaults to DIRECTORY_SEPARATOR.
return string The normalized file/directory path

removeDirectory() public static method #

Removes a directory (and all its content) recursively.

public static void removeDirectory ( $dir, $options = [] )
$dir string The directory to be deleted recursively.
$options array Options for directory remove. Valid options are: traverseSymlinks: boolean, whether symlinks to the directories should be traversed too. Defaults to false, meaning the content of the symlinked directory would not be deleted. Only symlink would be removed in that default case.
throws yii\base\ErrorException in case of failure

removeFile() public static method #

Deprecated in 3.0.0-RC11. Use unlink() instead.

Removes a file or symlink in a cross-platform way

public static boolean removeFile ( \craft\helpers\string $path )
$path string The file to be deleted

sanitizeFilename() public static method #

Sanitizes a filename.

public static string sanitizeFilename ( \craft\helpers\string $filename, array $options = [] )
$filename string The filename to sanitize
$options array Options for sanitization. Valid options are: asciiOnly: bool, whether only ASCII characters should be allowed. Defaults to false. separator: string|null, the separator character to use in place of whitespace. defaults to '-'. If set to null, whitespace will be preserved.
return string The cleansed filename

useFileLocks() public static method #

Returns whether file locks can be used when writing to files.

public static boolean useFileLocks ( )

writeToFile() public static method #

Writes contents to a file.

public static void writeToFile ( \craft\helpers\string $file, \craft\helpers\string $contents, array $options = [] )
$file string The file path
$contents string The new file contents
$options array Options for file write. Valid options are: createDirs: bool, whether to create parent directories if they do not exist. Defaults to true. append: bool, whether the contents should be appended to the existing contents. Defaults to false. lock: bool, whether a file lock should be used. Defaults to the "useWriteFileLock" config setting.
throws yii\base\InvalidArgumentException if the parent directory doesn't exist and options[createDirs] is false
throws yii\base\ErrorException in case of failure