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 !
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 ; it does not use safe lock checks
@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
@param: {BOOL} $dont_read_if_overSized: DEFAULT is FALSE ; if set to TRUE and a Max length is Set the file will not be read if size is more than max length
FAST READ A STATIC FILE CONTENTS ONLY. 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 ; it does not use safe lock checks
@return: {BOOL} TRUE if success, FALSE if fail
@param: {STRING} $file_relative_path: The relative path of file to be written (can be a symlink to a file)
@param: {STRING} $contents: The file contents
@param: {BOOL} $skip_check_if_exists: default is FALSE ; if set to TRUE if file exists will don't check if the content is identical
FAST WRITE A STATIC FILE WITH CONTENTS. ONLY WRITES IF THE FILE CONTENT DIFFERS OR DOES NOT EXISTS. WORKS ONLY WITH RELATIVE PATHS (Ex: path/to/a/file.ext).
It should be used just with static files which does not changes too often between executions ; it does not use safe lock checks
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 staticfunctionprefixedUidPath (
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 / 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 and spectrum 2 will return: 8i/Az/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 2 characters (sub-folders per folder, max: 62 * 62 = 3844 ; min: 10 * 10 = 100).
The minimum length of UID is 8 chars, the max length is 72 chars.
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
@return: {ARRAY} Example: ARRAY [ 0 => 'text/plain' ; 1 => 'inline; filename="file.ext"' ; 2 => 'inline' ] OR [ 0 => 'application/octet-stream' ; 1 => 'attachment; filename="file.ext"' ; 2 => 'attachment' ]
@param: {STRING} $file_name_or_path: the filename or path (includding file extension) ; Ex: file.ext or path/to/file.ext
@param: {MIXED} $disposition: EMPTY STRING (leave as is) ; ENUM: attachment | inline - to force a disposition type
Get the File MimeType
class Properties
class Constants
Sample code: PHP
<?php
// Usage example:
SmartFileSysUtils::some_method_of_this_class(...);
//-----------------------------------------------------------------------------------------------------
// 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()
// To check compliancy may use: checkIfSafeFileOrDirName or checkIfSafePath
//-----------------------------------------------------------------------------------------------------
// #end php code
documentation generated on: 2026-01-14 01:50:49 +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 !