HumHub Documentation (unofficial)

FileHelper extends BaseFileHelper
in package

Application

File system helper.

Constants

PATTERN_CASE_INSENSITIVE = 32
PATTERN_ENDSWITH = 4
PATTERN_MUSTBEDIR = 8
PATTERN_NEGATIVE = 16
PATTERN_NODIR = 1

Properties

$mimeAliasesFile : string
$mimeExtensionsFile : string
$mimeMagicFile : string
$_mimeAliases : mixed
$_mimeExtensions : mixed
$_mimeTypes : mixed

Methods

changeOwnership() : mixed: Changes the Unix user and/or group ownership of a file or directory, and optionally the mode.
copyDirectory() : mixed: Copies a whole directory as another one.
createDirectory() : bool: Creates a new directory.
filterPath() : bool: Checks if the given file path satisfies the filtering options.
findDirectories() : array<string|int, mixed>: Returns the directories found under the specified directory and subdirectories.
findFiles() : array<string|int, mixed>: Returns the files found under the specified directory and subdirectories.
getExtensionByMimeType() : string|null: Determines the most common extension by given MIME type.
getExtensionsByMimeType() : array<string|int, mixed>: Determines the extensions by given MIME type.
getMimeType() : string|null: Determines the MIME type of the specified file.
getMimeTypeByExtension() : string|null: Determines the MIME type based on the extension name of the specified file.
localize() : string: Returns the localized version of a specified file.
normalizePath() : string: Normalizes a file/directory path.
removeDirectory() : mixed: Removes a directory (and all its content) recursively.
unlink() : bool: Removes a file or symlink in a cross-platform way
loadMimeAliases() : array<string|int, mixed>: Loads MIME aliases from the specified file.
loadMimeExtensions() : array<string|int, mixed>: Loads MIME extensions from the specified file.
loadMimeTypes() : array<string|int, mixed>: Loads MIME types from the specified file.
normalizeOptions() : array<string|int, mixed>
clearDir() : string
firstWildcardInPattern() : int|bool: Searches for the first wildcard character in the pattern.
lastExcludeMatchingFromList() : array<string|int, mixed>|null: Scan the given exclude list in reverse to see whether pathname should be ignored. The first match (i.e. the last on the list), if any, determines the fate. Returns the element which matched, or null for undecided.
matchBasename() : bool: Performs a simple comparison of file or directory names.
matchPathname() : bool: Compares a path part against a pattern with optional wildcards.
openDir() : resource
parseExcludePattern() : array<string|int, mixed>: Processes the pattern, stripping special characters like / and ! from the beginning and settings flags instead.
setBasePath() : array<string|int, mixed>

PATTERN_CASE_INSENSITIVE


    public
        mixed
    PATTERN_CASE_INSENSITIVE
    = 32

PATTERN_ENDSWITH


    public
        mixed
    PATTERN_ENDSWITH
    = 4

PATTERN_MUSTBEDIR


    public
        mixed
    PATTERN_MUSTBEDIR
    = 8

PATTERN_NEGATIVE


    public
        mixed
    PATTERN_NEGATIVE
    = 16

PATTERN_NODIR


    public
        mixed
    PATTERN_NODIR
    = 1

$mimeAliasesFile


    public
    static    string
    $mimeAliasesFile
     = '@yii/helpers/mimeAliases.php'

the path (or alias) of a PHP file containing MIME aliases.

$mimeExtensionsFile


    public
    static    string
    $mimeExtensionsFile
     = '@yii/helpers/mimeExtensions.php'

the path (or alias) of a PHP file containing extensions per MIME type.

$mimeMagicFile


    public
    static    string
    $mimeMagicFile
     = '@yii/helpers/mimeTypes.php'

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

$_mimeAliases


    private
    static    mixed
    $_mimeAliases
     = []

$_mimeExtensions


    private
    static    mixed
    $_mimeExtensions
     = []

$_mimeTypes


    private
    static    mixed
    $_mimeTypes
     = []

changeOwnership()

Changes the Unix user and/or group ownership of a file or directory, and optionally the mode.


    public
            static        changeOwnership(string $path, string|array<string|int, mixed>|int|null $ownership[, int|null $mode = null ]) : mixed

Note: This function will not work on remote files as the file to be examined must be accessible via the server's filesystem. Note: On Windows, this function fails silently when applied on a regular file.

Parameters

$path : string: the path to the file or directory.
$ownership : string|array<string|int, mixed>|int|null: the user and/or group ownership for the file or directory. When $ownership is a string, the format is 'user:group' where both are optional. E.g. 'user' or 'user:' will only change the user, ':group' will only change the group, 'user:group' will change both. When $owners is an index array the format is [0 => user, 1 => group], e.g. [$myUser, $myGroup]. It is also possible to pass an associative array, e.g. ['user' => $myUser, 'group' => $myGroup]. In case $owners is an integer it will be used as user id. If null, an empty array or an empty string is passed, the ownership will not be changed.
$mode : int|null = null: the permission to be set for the file or directory. If null is passed, the mode will not be changed.

copyDirectory()

Copies a whole directory as another one.


    public
            static        copyDirectory(string $src, string $dst[, array<string|int, mixed> $options = [] ]) : mixed

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

Parameters

$src : string

the source directory

$dst : string

the destination directory

$options : array<string|int, mixed> = []

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.

createDirectory()

Creates a new directory.


    public
            static        createDirectory(string $path[, int $mode = 0775 ][, bool $recursive = true ]) : bool

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.

Parameters

$path : string: path of the directory to be created.
$mode : int = 0775: the permission to be set for the created directory.
$recursive : bool = true: whether to create parent directories if they do not exist.

Return values

bool —

whether the directory is created successfully

filterPath()

Checks if the given file path satisfies the filtering options.


    public
            static        filterPath(string $path, array<string|int, mixed> $options) : bool

Parameters

$path : string: the path of the file or directory to be checked
$options : array<string|int, mixed>: the filtering options. See [[findFiles()]] for explanations of the supported options.

Return values

bool —

whether the file or directory satisfies the filtering options.

findDirectories()

Returns the directories found under the specified directory and subdirectories.


    public
            static        findDirectories(string $dir[, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>

Parameters

$dir : string

the directory under which the files will be looked for.

$options : array<string|int, mixed> = []

options for directory searching. Valid options are:

filter: callback, a PHP callback that is called for each directory or file. The signature of the callback should be: function (string $path): bool, where $path refers the full path to be filtered. The callback can return one of the following values:
- - true: the directory will be returned
- - false: the directory will NOT be returned
recursive: boolean, whether the files under the subdirectories should also be looked for. Defaults to true. See [[findFiles()]] for more options.

Return values

array<string|int, mixed> —

directories found under the directory, in no particular order. Ordering depends on the files system used.

findFiles()

Returns the files found under the specified directory and subdirectories.


    public
            static        findFiles(string $dir[, array<string|int, mixed> $options = [] ]) : array<string|int, mixed>

Parameters

$dir : string

the directory under which the files will be looked for.

$options : array<string|int, mixed> = []

options for file searching. Valid options are:

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 returned (the only and except options will be ignored)
- - false: the directory or file will NOT be returned (the only and except options will be ignored)
- - null: the only and except options will determine whether the directory or file should be returned
except: array, list of patterns excluding from the results matching file or directory paths. Patterns ending with slash ('/') 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. If the pattern does not contain a slash (/), it is treated as a shell glob pattern and checked for a match against the pathname relative to $dir. Otherwise, the pattern is treated as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. For example, views/*.php matches views/index.php but not views/controller/index.php. A leading slash matches the beginning of the pathname. For example, /*.php matches index.php but not views/start/index.php. An optional prefix ! which negates the pattern; any matching file excluded by a previous pattern will become included again. If a negated pattern matches, this will override lower precedence patterns sources. Put a backslash (\) in front of the first ! for patterns that begin with a literal !, for example, \!important!.txt. Note, the '/' characters in a pattern matches both '/' and '' in the paths. You can find more details about the gitignore pattern format here.
only: array, list of patterns that the file paths should match if they are to be returned. Directory paths are not checked against them. Same pattern matching rules as in the except option are used. If a file path matches a pattern in both only and except, it will NOT be returned.
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 looked for. Defaults to true.

Return values

array<string|int, mixed> —

files found under the directory, in no particular order. Ordering depends on the files system used.

getExtensionByMimeType()

Determines the most common extension by given MIME type.


    public
            static        getExtensionByMimeType(string $mimeType[, bool $preferShort = false ][, string|null $magicFile = null ]) : string|null

This method will use a local map between MIME types and extension names.

Parameters

$mimeType : string: file MIME type.
$preferShort : bool = false: return an extension with a maximum of 3 characters.
$magicFile : string|null = null: the path (or alias) of the file that contains all available MIME type information. If this is not set, the file specified by [[mimeMagicFile]] will be used.

Return values

string|null —

the extensions corresponding to the specified MIME type

getExtensionsByMimeType()

Determines the extensions by given MIME type.


    public
            static        getExtensionsByMimeType(string $mimeType[, string|null $magicFile = null ]) : array<string|int, mixed>

This method will use a local map between extension names and MIME types.

Parameters

$mimeType : string: file MIME type.
$magicFile : string|null = null: the path (or alias) of the file that contains all available MIME type information. If this is not set, the file specified by [[mimeMagicFile]] will be used.

Return values

array<string|int, mixed> —

the extensions corresponding to the specified MIME type

getMimeType()

Determines the MIME type of the specified file.


    public
            static        getMimeType(string $file[, string|null $magicFile = null ][, bool $checkExtension = true ]) : string|null

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.

Parameters

$file : string: the file name.
$magicFile : string|null = null: 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 : bool = true: whether to use the file extension to determine the MIME type in case finfo_open() cannot determine it.

Return values

string|null —

the MIME type (e.g. text/plain). Null is returned if the MIME type cannot be determined.

getMimeTypeByExtension()

Determines the MIME type based on the extension name of the specified file.


    public
            static        getMimeTypeByExtension(string $file[, string|null $magicFile = null ]) : string|null

This method will use a local map between extension names and MIME types.

Parameters

$file : string: the file name.
$magicFile : string|null = null: the path (or alias) of the file that contains all available MIME type information. If this is not set, the file specified by [[mimeMagicFile]] will be used.

Return values

string|null —

the MIME type. Null is returned if the MIME type cannot be determined.

localize()

Returns the localized version of a specified file.


    public
            static        localize(string $file[, string|null $language = null ][, string|null $sourceLanguage = null ]) : string

The searching is based on the specified language code. In particular, a file with the same name will be looked for under the subdirectory whose name is the same as the language code. For example, given the file "path/to/view.php" and language code "zh-CN", the localized file will be looked for as "path/to/zh-CN/view.php". If the file is not found, it will try a fallback with just a language code that is "zh" i.e. "path/to/zh/view.php". If it is not found as well the original file will be returned.

If the target and the source language codes are the same, the original file will be returned.

Parameters

$file : string: the original file
$language : string|null = null: the target language that the file should be localized to. If not set, the value of [[\yii\base\Application::language]] will be used.
$sourceLanguage : string|null = null: the language that the original file is in. If not set, the value of [[\yii\base\Application::sourceLanguage]] will be used.

Return values

string —

the matching localized file, or the original file if the localized version is not found. If the target and the source language codes are the same, the original file will be returned.

normalizePath()

Normalizes a file/directory path.


    public
            static        normalizePath(string $path[, string $ds = DIRECTORY_SEPARATOR ]) : string

The normalization does the following work:

Convert all directory separators into DIRECTORY_SEPARATOR (e.g. "\a/b\c" becomes "/a/b/c")
Remove trailing directory separators (e.g. "/a/b/c/" becomes "/a/b/c")
Turn multiple consecutive slashes into a single one (e.g. "/a///b/c" becomes "/a/b/c")
Remove ".." and "." based on their meanings (e.g. "/a/./b/../c" becomes "/a/c")

Note: For registered stream wrappers, the consecutive slashes rule and ".."/"." translations are skipped.

Parameters

$path : string: the file/directory path to be normalized
$ds : string = DIRECTORY_SEPARATOR: the directory separator to be used in the normalized result. Defaults to DIRECTORY_SEPARATOR.

Return values

string —

the normalized file/directory path

removeDirectory()

Removes a directory (and all its content) recursively.


    public
            static        removeDirectory(string $dir[, array<string|int, mixed> $options = [] ]) : mixed

Parameters

$dir : string

the directory to be deleted recursively.

$options : array<string|int, mixed> = []

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.

unlink()

Removes a file or symlink in a cross-platform way


    public
            static        unlink(string $path) : bool

Parameters

$path : string

Return values

bool

loadMimeAliases()

Loads MIME aliases from the specified file.


    protected
            static        loadMimeAliases(string|null $aliasesFile) : array<string|int, mixed>

Parameters

$aliasesFile : string|null: the path (or alias) of the file that contains MIME type aliases. If this is not set, the file specified by [[mimeAliasesFile]] will be used.

Return values

array<string|int, mixed> —

the mapping from file extensions to MIME types

loadMimeExtensions()

Loads MIME extensions from the specified file.


    protected
            static        loadMimeExtensions(string|null $extensionsFile) : array<string|int, mixed>

Parameters

$extensionsFile : string|null: the path (or alias) of the file that contains MIME type aliases. If this is not set, the file specified by [[mimeAliasesFile]] will be used.

Return values

array<string|int, mixed> —

the mapping from file extensions to MIME types

loadMimeTypes()

Loads MIME types from the specified file.


    protected
            static        loadMimeTypes(string|null $magicFile) : array<string|int, mixed>

Parameters

$magicFile : string|null: the path (or alias) of the file that contains all available MIME type information. If this is not set, the file specified by [[mimeMagicFile]] will be used.

Return values

array<string|int, mixed> —

the mapping from file extensions to MIME types

normalizeOptions()


    protected
            static        normalizeOptions(array<string|int, mixed> $options) : array<string|int, mixed>

Parameters

$options : array<string|int, mixed>: raw options

Return values

array<string|int, mixed> —

normalized options

clearDir()


    private
            static        clearDir(string $dir) : string

Parameters

$dir : string

Return values

string

firstWildcardInPattern()

Searches for the first wildcard character in the pattern.


    private
            static        firstWildcardInPattern(string $pattern) : int|bool

Parameters

$pattern : string: the pattern to search in

Return values

int|bool —

position of first wildcard character or false if not found

lastExcludeMatchingFromList()

Scan the given exclude list in reverse to see whether pathname should be ignored. The first match (i.e. the last on the list), if any, determines the fate. Returns the element which matched, or null for undecided.


    private
            static        lastExcludeMatchingFromList(string $basePath, string $path, array<string|int, mixed> $excludes) : array<string|int, mixed>|null

Based on last_exclude_matching_from_list() from dir.c of git 1.8.5.3 sources.

Parameters

$basePath : string
$path : string
$excludes : array<string|int, mixed>: list of patterns to match $path against

Return values

array<string|int, mixed>|null —

null or one of $excludes item as an array with keys: 'pattern', 'flags'

matchBasename()

Performs a simple comparison of file or directory names.


    private
            static        matchBasename(string $baseName, string $pattern, int|bool $firstWildcard, int $flags) : bool

Based on match_basename() from dir.c of git 1.8.5.3 sources.

Parameters

$baseName : string: file or directory name to compare with the pattern
$pattern : string: the pattern that $baseName will be compared against
$firstWildcard : int|bool: location of first wildcard character in the $pattern
$flags : int: pattern flags

Return values

bool —

whether the name matches against pattern

matchPathname()

Compares a path part against a pattern with optional wildcards.


    private
            static        matchPathname(string $path, string $basePath, string $pattern, int|bool $firstWildcard, int $flags) : bool

Based on match_pathname() from dir.c of git 1.8.5.3 sources.

Parameters

$path : string: full path to compare
$basePath : string: base of path that will not be compared
$pattern : string: the pattern that path part will be compared against
$firstWildcard : int|bool: location of first wildcard character in the $pattern
$flags : int: pattern flags

Return values

bool —

whether the path part matches against pattern

openDir()


    private
            static        openDir(string $dir) : resource

Parameters

$dir : string

Return values

resource

parseExcludePattern()

Processes the pattern, stripping special characters like / and ! from the beginning and settings flags instead.


    private
            static        parseExcludePattern(string $pattern, bool $caseSensitive) : array<string|int, mixed>

Parameters

$pattern : string
$caseSensitive : bool

Return values

array<string|int, mixed> —

with keys: (string) pattern, (int) flags, (int|bool) firstWildcard

setBasePath()


    private
            static        setBasePath(string $dir, array<string|int, mixed> $options) : array<string|int, mixed>

Parameters

$dir : string
$options : array<string|int, mixed>

Return values

array<string|int, mixed>

FileHelper extends BaseFileHelper in package Application

Tags

Table of Contents

Constants

Properties

Methods

Constants

PATTERN_CASE_INSENSITIVE

PATTERN_ENDSWITH

PATTERN_MUSTBEDIR

PATTERN_NEGATIVE

PATTERN_NODIR

Properties

$mimeAliasesFile

Tags

$mimeExtensionsFile

Tags

$mimeMagicFile

$_mimeAliases

$_mimeExtensions

$_mimeTypes

Methods

changeOwnership()

Parameters

Tags

copyDirectory()

Parameters

Tags

createDirectory()

Parameters

Tags

Return values

filterPath()

Parameters

Return values

findDirectories()

Parameters

Tags

Return values

findFiles()

Parameters

Tags

Return values

getExtensionByMimeType()

Parameters

Tags

Return values

getExtensionsByMimeType()

Parameters

Return values

getMimeType()

Parameters

Tags

Return values

getMimeTypeByExtension()

Parameters

Return values

localize()

Parameters

Return values

normalizePath()

Parameters

Return values

removeDirectory()

Parameters

Tags

unlink()

Parameters

Tags

Return values

loadMimeAliases()

Parameters

Tags

FileHelper extends BaseFileHelper
in package

Application