Class: SmartFileSysUtils - provides the File System Util functions.
This class enforces the use of RELATIVE PATHS to force using correct path access in a web environment application.
Relative paths must be relative to the web application folder as folder: `some-folder/` or file: `some-folder/my-file.txt`.
Absolute paths are denied by internal checks as they are NOT SAFE in a Web Application from the security point of view ...
Also the backward path access like `../some-file-or-folder` is denied from the above exposed reasons.
Files and Folders must contain ONLY safe characters as: `[a-z] [A-Z] [0-9] _ - . @ #` ; folders can also contain slashes `/` (as path separators); no spaces are allowed in paths !!
NOTICE: To use paths in a safe manner, never add manually a / at the end of a path variable, because if it is empty will result in accessing the root of the file system (/).
To handle this in an easy and safe manner, use the function SmartFileSysUtils::addPathTrailingSlash((string)$my_dir) so it will add the trailing slash ONLY if misses but NOT if the $my_dir is empty to avoid root access !
Language: PHP
Located at: lib/framework/lib_smart.php
Package: @Core:FileSystem
Namespace: \
Class Name: SmartFileSysUtils
Version: v.20231008
Depends: classes: Smart, SmartEnvironment
Usage: static object: Class::method() - This class provides only STATIC methods
class Methods
public staticfunctionstaticFileExists (
string$file_relative_path
) {} :: BOOL
@return: {BOOL} TRUE if file exists and path is safe ; FALSE otherwise
@param: {STRING} $file_relative_path: The relative path of file to be read (can be a symlink to a file)
FAST CHECK IF A STATIC FILE EXISTS AND IS READABLE. WORKS ONLY WITH RELATIVE PATHS (Ex: path/to/a/file.ext).
It should be used just with static files which does not changes between executions
@return: {STRING} The file contents or an empty string if file not found or cannot read file or other error cases
@param: {STRING} $file_relative_path: The relative path of file to be read (can be a symlink to a file)
@param: {INTEGER+} $length: DEFAULT is 0 (zero) ; If zero will read the entire file ; If > 0 (ex: 100) will read only the first 100 bytes fro the file or less if the file size is under 100 bytes
FAST READ A STATIC FILE CONTENTS. ALSO CHECKS IF THE FILE EXISTS AND IS READABLE. WORKS ONLY WITH RELATIVE PATHS (Ex: path/to/a/file.ext).
It should be used just with static files which does not changes between executions
public staticfunctionmaxUploadFileSize (
) {} :: INT
@return: {INTEGER} the Max Upload Size in Bytes
Return the MAXIMUM allowed Upload Size
public staticfunctioncheckIfSafeFileOrDirName (
string$y_fname
) {} :: INT
@return: {0/1} returns 1 if VALID ; 0 if INVALID
@param: {STRING} $y_fname: The dirname or filename, (not path containing /) to validate
Check a Name of a File or Directory (not a path containing /) if contain valid characters (to avoid filesystem path security injections)
Security: provides check if unsafe filenames or dirnames are accessed.
public staticfunctioncheckIfSafePath (
string$path,
bool$deny_absolute_path = true,
bool$allow_protected_relative_paths = false
) {} :: INT
@return: {0/1} returns 1 if VALID ; 0 if INVALID
@param: {STRING} $path: The path (dir or file) to validate
@param: {BOOL} $deny_absolute_path: *Optional* If TRUE will dissalow absolute paths
@param: {BOOL} $allow_protected_relative_paths: *Optional* ! This is for very special case usage only so don't set it to TRUE except if you know what you are really doing ! If set to TRUE will allow access to special protected paths of this framework which may have impact on security ... ; this parameter is intended just for relative paths only (not absolute paths) as: #dir/.../file.ext ; #file.ext ; for task area this is always hardcoded to TRUE and cannot be overrided
Check a Path (to a Directory or to a File) if contain valid characters (to avoid filesystem path security injections)
Security: provides check if unsafe paths are accessed.
Absolute paths on windows if checked as intended must be previous be converted using slash instead of backslash using Smart::fix_path_separator()
public staticfunctionaddPathTrailingSlash (
string$y_path
) {} :: STRING
@return: {STRING} The fixed path with a trailing
@param: {STRING} $y_path: The path to add the trailing slash to
Safe add a trailing slash to a path if not already have it, with safe detection and avoid root access.
Adding a trailing slash to a path is not a simple task as if path is empty, adding the trailing slash will result in accessing the root file system as will be: /.
Otherwise it have to detect if the trailing slash exists already to avoid double slash.
public staticfunctionextractPathDir (
string$y_path
) {} :: STRING
@return: {STRING} a directory path [FOLDER NAME]
@param: {STRING} $y_path: the path (dir or file)
Return the folder name from a path (except last trailing slash: /)
public staticfunctionextractPathFileName (
string$y_path
) {} :: STRING
@return: {STRING} [FILE NAME]
@param: {STRING} $y_path: path or file
Return the file name (includding extension) from path
WARNING: path_info('c:\\file.php') will not work correct on unix, but on windows will work correct both: path_info('c:\\file.php') and path_info('path/file.php'
public staticfunctionextractPathFileNoExtName (
string$y_path
) {} :: STRING
@return: {STRING} [FILE NAME]
@param: {STRING} $y_path: path or file
Return the file name (WITHOUT extension) from path
public staticfunctionextractPathFileExtension (
string$y_path
) {} :: STRING
@return: {STRING} [FILE EXTENSION]
@param: {STRING} $y_path: path or file
Return the file extension (without .) from path
public staticfunctionprefixedUidB62Path (
string$y_id,
int$y_spectrum
) {} :: STRING
@return: {STRING} Prefixed Path
@param: {STRING} $y_id: 8..72 chars id (uid)
@param: {INTEGER} $y_spectrum: 1..7 the expanding levels spectrum
Generate a prefixed dir from a base62 (also supports: base58 / base36 / base32 / base16 / base10) UID, 8..72 chars length : [a-zA-Z0-9].
It does include also the UID as final folder segment.
Example: for ID 8iAz0WtTuV72QZ72Re5X0PlIgB23M6 will return: 8/8iAz0WtTuV72QZ72Re5X0PlIgB23M6/ as the generated prefixed path.
This have to be used for large folder storage structure to avoid limitations on some filesystems (ext3 / ntfs) where max sub-dirs per dir is 32k.
The prefixed path will be grouped by each 1 character (max sub-folders per folder: 62).
If a shorther length than 8 chars is provided will pad with 0 on the left.
If a longer length than 72 or an invalid ID is provided will reset the ID to 00000000 (8 chars) for the given length, but also drop a warning.
public staticfunctionprefixedUuid10B36Path (
string$y_id
) {} :: STRING
Generate a prefixed dir from a base36 UUID, 10 chars length : [A-Z0-9].
It does include also the UUID as final folder segment.
Example: for ID ABCDEFGHIJ09 will return: 9T/5B/0B/9M/9T5B0B9M8M/ as the generated prefixed path.
This have to be used for large folder storage structure to avoid limitations on some filesystems (ext3 / ntfs) where max sub-dirs per dir is 32k.
The prefixed path will be grouped by each 2 characters (max sub-folders per folder: 36 x 36 = 1296).
If a shorther length than 10 chars is provided will pad with 0 on the left.
If a longer length or an invalid ID is provided will reset the ID to 000000..00 (10 chars) for the given length, but also drop a warning.
public staticfunctionprefixedUuid40B16Path (
string$y_id
) {} :: STRING
Generate a prefixed dir from a base16 UUID (sha1), 40 chars length : [a-f0-9].
It does NOT include the ID final folder.
Example: for ID df3a808b2bf20aaab4419c43d9f3a6143bd6b4bb will return: d/f3a/808/b2b/f20/aaa/b44/19c/43d/9f3/a61/43b/d6b/ as the generated prefixed path.
This have to be used for large folder storage structure to avoid limitations on some filesystems (ext3 / ntfs) where max sub-dirs per dir is 32k.
The prefixed folder will be grouped by each 3 characters (max sub-folders per folder: 16 x 16 x 16 = 4096).
If a shorther length than 40 chars is provided will pad with 0 on the left.
If a longer length than 40 chars or an invalid ID is provided will reset the ID to 000000..00 (40 chars) for the given length, but also drop a warning.
public staticfunctiongetMimeType (
string$file_name_or_path
) {} :: STRING
@return: {STRING} the mime type by extension (will also detect some standard files without extension: ex: readme)
@param: {STRING} $file_name_or_path: the filename or path (includding file extension) ; Ex: file.ext or path/to/file.ext
//----------------------------------------------------------------------------------------------------- //----------------------------------------------------------------------------------------------------- // SAFE REPLACEMENTS: // In order to supply a common framework for Unix / Linux but also on Windows, // because on Windows dir separator is \ instead of / the following functions must be used as replacements: //----------------------------------------------------------------------------------------------------- // Smart::real_path() instead of: realpath() // Smart::dir_name() instead of: dirname() // Smart::path_info() instead of: pathinfo() //----------------------------------------------------------------------------------------------------- // Also, when folders are get from external environments and are not certified if they have // been converted from \ to / on Windows, those paths have to be fixed using: Smart::fix_path_separator() //-----------------------------------------------------------------------------------------------------
// #end php code
documentation generated on: 2023-10-19 23:15:43 +0000
This class enforces the use of RELATIVE PATHS to force using correct path access in a web environment application.
Relative paths must be relative to the web application folder as folder: `some-folder/` or file: `some-folder/my-file.txt`.
Absolute paths are denied by internal checks as they are NOT SAFE in a Web Application from the security point of view ...
Also the backward path access like `../some-file-or-folder` is denied from the above exposed reasons.
Files and Folders must contain ONLY safe characters as: `[a-z] [A-Z] [0-9] _ - . @ #` ; folders can also contain slashes `/` (as path separators); no spaces are allowed in paths !!
NOTICE: To use paths in a safe manner, never add manually a / at the end of a path variable, because if it is empty will result in accessing the root of the file system (/).
To handle this in an easy and safe manner, use the function SmartFileSysUtils::addPathTrailingSlash((string)$my_dir) so it will add the trailing slash ONLY if misses but NOT if the $my_dir is empty to avoid root access !