# final class \SmartFileSysUtils
{ } ::

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.20240106
- Depends: classes: Smart, SmartEnvironment
- Usage: static object: Class::method() - This class provides only STATIC methods

## class Methods

public static function staticFileExists ( 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
public static function readStaticFile ( string $file_relative_path, int $length = null ) {} :: STRING
@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 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
public static function maxUploadFileSize ( ) {} :: INT
@return: {INTEGER} the Max Upload Size in Bytes
Return the MAXIMUM allowed Upload Size
public static function checkIfSafeFileOrDirName ( 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 static function checkIfSafePath ( 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 static function addPathTrailingSlash ( 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 static function extractPathDir ( 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 static function extractPathFileName ( 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 static function extractPathFileNoExtName ( string $y_path ) {} :: STRING
@return: {STRING} [FILE NAME]
@param: {STRING} $y_path: path or file
Return the file name (WITHOUT extension) from path
public static function extractPathFileExtension ( string $y_path ) {} :: STRING
@return: {STRING} [FILE EXTENSION]
@param: {STRING} $y_path: path or file
Return the file extension (without .) from path
public static function prefixedUidB62Path ( 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 static function prefixedUuid10B36Path ( string $y_id ) {} :: STRING
@return: {STRING} Prefixed Path
@param: {STRING} $y_id: 10 chars id (uuid10)
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 static function prefixedUuid40B16Path ( string $y_id ) {} :: STRING
@return: {STRING} Prefixed Path
@param: {STRING} $y_id: 40 chars id (sha1)
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 static function getMimeType ( 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
Get the File MimeType
public static function getArrMimeType ( string $file_name_or_path, string $disposition = "" ) {} :: ARRAY
@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: 2024-12-16 16:53:44 +0000

Smart.Framework © 2009-2024 unix-world.org