UploadFolderManager
in package
Manages upload folders in the filesystem Provides methods for creating, validating, and managing upload directories
Table of Contents
Properties
- $baseDir : string
- $dirPermissions : int
- $filePermissions : int
- $mainPath : string|null
- $meta : array<string|int, mixed>|null
- $prefix : string
- $relatedPaths : array<int, string>
- $schema : array<int, string>
- $tempJsonPath : string|null
- $tempStorageDir : string
- $tempTtlSeconds : int
Methods
- __construct() : mixed
- cleanupExpiredTemp() : bool
- Cleans up expired temporary directories and metadata files.
- countFiles() : int
- Counts files in specified folders.
- createStructure() : array<string|int, mixed>
- Creates a directory structure and saves JSON metadata.
- fileExists() : bool
- Checks if a file exists in the structure.
- filesByExtension() : array<string, array<int, array<string, mixed>>>
- Groups files by file extension.
- filesByMime() : array<string, array<int, array<string, mixed>>>
- Groups files by MIME type.
- folderExists() : bool
- Checks if a directory exists in the structure.
- getAbsoluteFilePath() : string
- Gets absolute path for a file.
- getAllFilesPaths() : array<int, string>
- Gets list of all files in specified folders.
- getAllPaths() : array<string, string>
- Gets paths of all directories in the structure.
- getCreatedAt() : DateTimeImmutable|null
- Gets creation date for a directory.
- getFileInfo() : array<string, mixed>
- Gets information about a specific file.
- getFilePermissions() : string|null
- Gets permissions for a file.
- getFolderInfo() : array<string, mixed>
- Gets information about a specific directory.
- getFolderPermissions() : string|null
- Gets permissions for directory.
- getLastAddedAt() : DateTimeImmutable|null
- Gets date of last file addition to a directory.
- getMainPath() : string
- Gets the path to the main directory.
- getModifiedAt() : DateTimeImmutable|null
- Gets last modified date for a directory.
- getRelatedFolderPath() : string|null
- Gets path of a specific related directory.
- getRelatedPaths() : array<int, string>
- Gets paths of all related directories.
- getRelatedSchemas() : array<int, array<int, string>|string>
- Gets all related schemas.
- getSchema() : array<int, string>
- Gets the directory schema.
- getStructureInfo() : array<string|int, mixed>
- Gets comprehensive information about the current structure.
- getTempJsonPath() : string|null
- Gets path to the temporary JSON metadata file.
- getTempMetadata() : array<string|int, mixed>|null
- Gets temporary metadata from JSON file.
- hasRelatedFolder() : bool
- Checks if a related directory exists.
- isExpired() : bool
- Checks if the temporary directory has expired.
- listFiles() : array<int, array<string, mixed>>
- Lists files in a directory sorted by specified criteria.
- listFilesAlphabetically() : array<int, array<string, mixed>>
- Lists files sorted alphabetically.
- listFilesByAddedDate() : array<int, array<string, mixed>>
- Lists files sorted by added date.
- listFilesReverseAlphabetically() : array<int, array<string, mixed>>
- Lists files sorted in reverse alphabetical order.
- loadFromTempJson() : array<string|int, mixed>
- Loads the structure from the JSON file generated for the temporary folder.
- refreshTempMetadata() : bool
- Refreshes metadata in temporary JSON file.
- saveFile() : string
- Saves a file to the structure.
- touchFolder() : bool
- Updates timestamp for a directory.
- assertCreated() : void
- Asserts that structure has been created.
- buildFileRecord() : array<string, mixed>
- Builds file record from SplFileInfo.
- buildSchemaPath() : string
- Builds directory path from schema.
- calculateFolderSize() : int
- Calculates the total size of a directory in bytes.
- collectFiles() : array<int, array<string, mixed>>
- Collects files from a directory.
- countSubfolders() : int
- Counts the number of subfolders within a given directory.
- deleteDirectoryRecursively() : void
- Deletes a directory and all its contents recursively.
- detectMimeType() : string
- Detects MIME type for a file.
- ensureDirectory() : void
- Ensures directory exists with specified permissions.
- generateId() : string
- Generates a unique identifier for temporary directories.
- generateTempJsonName() : string
- Generates a consistent temporary JSON filename for a given main path.
- normalizePath() : string
- Normalizes file system path.
- normalizeSchema() : array<int, string>
- Normalizes directory schema.
- replaceTokens() : string
- Replaces tokens in a path segment.
- resolveFolderPath() : string|null
- Resolves a folder path based on key.
- resolveSelectedFolders() : array<int, string>
- Resolves folder paths based on key.
- sanitizePathSegment() : string
- Sanitizes a path segment.
Properties
$baseDir
private
string
$baseDir
$dirPermissions
private
int
$dirPermissions
$filePermissions
private
int
$filePermissions
$mainPath
private
string|null
$mainPath
= null
$meta
private
array<string|int, mixed>|null
$meta
= null
$prefix
private
string
$prefix
$relatedPaths
private
array<int, string>
$relatedPaths
= []
$schema
private
array<int, string>
$schema
$tempJsonPath
private
string|null
$tempJsonPath
= null
$tempStorageDir
private
string
$tempStorageDir
$tempTtlSeconds
private
int
$tempTtlSeconds
Methods
__construct()
public
__construct(string $baseDir, array<int, string>|string $schema[, array{prefix?: string, temp_ttl_seconds?: int, temp_storage_dir?: string, dir_permissions?: int, file_permissions?: int, related_schemas?: array|string>} $options = [] ]) : mixed
Parameters
- $baseDir : string
-
Base directory, e.g. /var/www/storage/uploads
- $schema : array<int, string>|string
-
Directory schema, e.g. ['Y', 'm', 'd'] or 'Y/m/d/H' or ['prefix', 'Y', 'm', 'd']
-
$options
: array{prefix?: string, temp_ttl_seconds?: int, temp_storage_dir?: string, dir_permissions?: int, file_permissions?: int, related_schemas?: array
cleanupExpiredTemp()
Cleans up expired temporary directories and metadata files.
public
cleanupExpiredTemp() : bool
Return values
bool —True if cleanup was performed, false otherwise
countFiles()
Counts files in specified folders.
public
countFiles([bool $recursive = true ][, string|null $folderKey = null ]) : int
Parameters
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
int —Number of files found
createStructure()
Creates a directory structure and saves JSON metadata.
public
createStructure([bool $temporary = false ][, string|null $tempId = null ]) : array<string|int, mixed>
If $temporary=true, the base directory will have a unique ID, and the metadata will go to a JSON file in temp_storage_dir.
Parameters
- $temporary : bool = false
-
Whether to create a temporary directory with unique ID
- $tempId : string|null = null
-
Unique identifier for temporary directories
Return values
array<string|int, mixed> —Information about the created structure
fileExists()
Checks if a file exists in the structure.
public
fileExists(string $fileName[, string|null $folderKey = 'main' ]) : bool
Parameters
- $fileName : string
-
Name of the file to check
- $folderKey : string|null = 'main'
-
Identifier for the folder to search in
Return values
bool —True if file exists, false otherwise
filesByExtension()
Groups files by file extension.
public
filesByExtension([bool $recursive = true ][, string|null $folderKey = null ]) : array<string, array<int, array<string, mixed>>>
Parameters
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
array<string, array<int, array<string, mixed>>> —Files grouped by file extension
filesByMime()
Groups files by MIME type.
public
filesByMime([bool $recursive = true ][, string|null $folderKey = null ]) : array<string, array<int, array<string, mixed>>>
Parameters
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
array<string, array<int, array<string, mixed>>> —Files grouped by MIME type
folderExists()
Checks if a directory exists in the structure.
public
folderExists([string|null $folderKey = 'main' ]) : bool
Parameters
- $folderKey : string|null = 'main'
-
Identifier for the folder to check
Return values
bool —True if directory exists, false otherwise
getAbsoluteFilePath()
Gets absolute path for a file.
public
getAbsoluteFilePath(string $fileName[, string|null $folderKey = 'main' ]) : string
Parameters
- $fileName : string
-
Name of the file
- $folderKey : string|null = 'main'
-
Identifier for the folder to search in
Return values
string —Absolute path to the file
getAllFilesPaths()
Gets list of all files in specified folders.
public
getAllFilesPaths([bool $recursive = true ][, string|null $folderKey = null ]) : array<int, string>
Parameters
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
array<int, string> —Array of file paths
getAllPaths()
Gets paths of all directories in the structure.
public
getAllPaths() : array<string, string>
Return values
array<string, string> —Associative array with directory identifiers and their paths
getCreatedAt()
Gets creation date for a directory.
public
getCreatedAt([string|null $folderKey = 'main' ]) : DateTimeImmutable|null
Parameters
- $folderKey : string|null = 'main'
-
Identifier for the folder to check
Return values
DateTimeImmutable|null —Creation timestamp or null if not found
getFileInfo()
Gets information about a specific file.
public
getFileInfo(string $fileName[, string|null $folderKey = 'main' ]) : array<string, mixed>
Parameters
- $fileName : string
-
Name of the file
- $folderKey : string|null = 'main'
-
Identifier for the folder to check in
Return values
array<string, mixed> —File information
getFilePermissions()
Gets permissions for a file.
public
getFilePermissions(string $fileName[, string|null $folderKey = 'main' ]) : string|null
Parameters
- $fileName : string
-
Name of the file
- $folderKey : string|null = 'main'
-
Identifier for the folder to check in
Return values
string|null —String representation of permissions or null if not found
getFolderInfo()
Gets information about a specific directory.
public
getFolderInfo([string|null $folderKey = 'main' ]) : array<string, mixed>
Parameters
- $folderKey : string|null = 'main'
-
Identifier for the folder to check
Return values
array<string, mixed> —Directory information
getFolderPermissions()
Gets permissions for directory.
public
getFolderPermissions([string|null $folderKey = 'main' ]) : string|null
Parameters
- $folderKey : string|null = 'main'
-
Identifier for the folder to check
Return values
string|null —String representation of permissions or null if not found
getLastAddedAt()
Gets date of last file addition to a directory.
public
getLastAddedAt([string|null $folderKey = null ][, bool $recursive = true ]) : DateTimeImmutable|null
Parameters
- $folderKey : string|null = null
-
Identifier for the folder to check
- $recursive : bool = true
-
Whether to include subdirectories
Return values
DateTimeImmutable|null —Last added timestamp or null if not found
getMainPath()
Gets the path to the main directory.
public
getMainPath() : string
Return values
string —Main directory path
getModifiedAt()
Gets last modified date for a directory.
public
getModifiedAt([string|null $folderKey = 'main' ]) : DateTimeImmutable|null
Parameters
- $folderKey : string|null = 'main'
-
Identifier for the folder to check
Return values
DateTimeImmutable|null —Modification timestamp or null if not found
getRelatedFolderPath()
Gets path of a specific related directory.
public
getRelatedFolderPath(int $index) : string|null
Parameters
- $index : int
-
Index of the related directory to retrieve
Return values
string|null —Path to the directory or null if it doesn't exist
getRelatedPaths()
Gets paths of all related directories.
public
getRelatedPaths() : array<int, string>
Return values
array<int, string> —Array of directory paths
getRelatedSchemas()
Gets all related schemas.
public
getRelatedSchemas() : array<int, array<int, string>|string>
Return values
array<int, array<int, string>|string> —Related schemas
getSchema()
Gets the directory schema.
public
getSchema() : array<int, string>
Return values
array<int, string> —Directory schema components
getStructureInfo()
Gets comprehensive information about the current structure.
public
getStructureInfo() : array<string|int, mixed>
Return values
array<string|int, mixed> —Structure information
getTempJsonPath()
Gets path to the temporary JSON metadata file.
public
getTempJsonPath() : string|null
Return values
string|null —Path to JSON file or null if not applicable
getTempMetadata()
Gets temporary metadata from JSON file.
public
getTempMetadata() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null —Array of metadata or null if not found
hasRelatedFolder()
Checks if a related directory exists.
public
hasRelatedFolder(int $index) : bool
Parameters
- $index : int
-
Index of the related directory to check
Return values
bool —True if directory exists, false otherwise
isExpired()
Checks if the temporary directory has expired.
public
isExpired() : bool
Return values
bool —True if expired, false otherwise
listFiles()
Lists files in a directory sorted by specified criteria.
public
listFiles([string $sortBy = 'added_at' ][, bool $recursive = true ][, string|null $folderKey = null ]) : array<int, array<string, mixed>>
Parameters
- $sortBy : string = 'added_at'
-
Sorting criteria: added_at|alphabetical|reverse_alphabetical
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
array<int, array<string, mixed>> —Array of file information
listFilesAlphabetically()
Lists files sorted alphabetically.
public
listFilesAlphabetically([bool $desc = false ][, bool $recursive = true ][, string|null $folderKey = null ]) : array<int, array<string, mixed>>
Parameters
- $desc : bool = false
-
Whether to sort in descending order
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
array<int, array<string, mixed>> —Array of file information
listFilesByAddedDate()
Lists files sorted by added date.
public
listFilesByAddedDate([bool $desc = true ][, bool $recursive = true ][, string|null $folderKey = null ]) : array<int, array<string, mixed>>
Parameters
- $desc : bool = true
-
Whether to sort in descending order
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
array<int, array<string, mixed>> —Array of file information
listFilesReverseAlphabetically()
Lists files sorted in reverse alphabetical order.
public
listFilesReverseAlphabetically([bool $recursive = true ][, string|null $folderKey = null ]) : array<int, array<string, mixed>>
Parameters
- $recursive : bool = true
-
Whether to include subdirectories
- $folderKey : string|null = null
-
Identifier for the folder to search in
Return values
array<int, array<string, mixed>> —Array of file information
loadFromTempJson()
Loads the structure from the JSON file generated for the temporary folder.
public
loadFromTempJson(string $jsonPath) : array<string|int, mixed>
Parameters
- $jsonPath : string
-
Path to the JSON metadata file
Return values
array<string|int, mixed> —Information about the loaded structure
refreshTempMetadata()
Refreshes metadata in temporary JSON file.
public
refreshTempMetadata() : bool
Return values
bool —True if successful, false otherwise
saveFile()
Saves a file to the structure.
public
saveFile(string $relativeFileName, string $content[, string|null $folderKey = 'main' ]) : string
Parameters
- $relativeFileName : string
-
Name of the file to save
- $content : string
-
Content to write to the file
- $folderKey : string|null = 'main'
-
Identifier for the folder to save in
Return values
string —Path to the saved file
touchFolder()
Updates timestamp for a directory.
public
touchFolder([string|null $folderKey = 'main' ]) : bool
Parameters
- $folderKey : string|null = 'main'
-
Identifier for the folder to touch
Return values
bool —True if successful, false otherwise
assertCreated()
Asserts that structure has been created.
private
assertCreated() : void
Tags
buildFileRecord()
Builds file record from SplFileInfo.
private
buildFileRecord(SplFileInfo $file) : array<string, mixed>
Parameters
- $file : SplFileInfo
-
File information object
Return values
array<string, mixed> —Formatted file information
buildSchemaPath()
Builds directory path from schema.
private
buildSchemaPath(array<int, string> $schema, DateTimeInterface $date) : string
Parameters
- $schema : array<int, string>
-
Schema to use for building
- $date : DateTimeInterface
-
Date to use in path construction
Return values
string —Built directory path
calculateFolderSize()
Calculates the total size of a directory in bytes.
private
calculateFolderSize(string $dir) : int
Parameters
- $dir : string
-
The path to the directory.
Return values
int —The total size in bytes.
collectFiles()
Collects files from a directory.
private
collectFiles(string $folder, bool $recursive) : array<int, array<string, mixed>>
Parameters
- $folder : string
-
Path to the directory
- $recursive : bool
-
Whether to include subdirectories
Return values
array<int, array<string, mixed>> —Array of file information
countSubfolders()
Counts the number of subfolders within a given directory.
private
countSubfolders(string $dir) : int
This method recursively counts how many subdirectories are present in the specified directory, excluding '.' and '..' entries.
Parameters
- $dir : string
-
The directory path to count subfolders for.
Return values
int —Returns the number of subdirectories found.
deleteDirectoryRecursively()
Deletes a directory and all its contents recursively.
private
deleteDirectoryRecursively(string $dir) : void
This method removes files and subdirectories within the specified directory, then removes the directory itself. It handles nested directory structures by using RecursiveIteratorIterator to process each file/directory in order.
Parameters
- $dir : string
-
The path to the directory to delete.
detectMimeType()
Detects MIME type for a file.
private
detectMimeType(string $path) : string
Parameters
- $path : string
-
Path to the file
Return values
string —Detected MIME type or default type
ensureDirectory()
Ensures directory exists with specified permissions.
private
ensureDirectory(string $path, int $permissions) : void
Parameters
- $path : string
-
Path to the directory
- $permissions : int
-
Permissions to set
generateId()
Generates a unique identifier for temporary directories.
private
generateId() : string
This method creates a cryptographically secure random hexadecimal string that can be used as a unique identifier for files or folders.
Return values
string —A hexadecimal string representation of 16 bytes (32 characters long).
generateTempJsonName()
Generates a consistent temporary JSON filename for a given main path.
private
generateTempJsonName(string $mainPath) : string
This method creates a unique but deterministic name for the JSON metadata file associated with a temporary directory identified by its main path. The generated name incorporates a hash of the main path and timestamp to ensure uniqueness.
Parameters
- $mainPath : string
-
The absolute path of the main directory for which the JSON is being created.
Return values
string —A unique filename (without extension) for the temporary metadata file.
normalizePath()
Normalizes file system path.
private
normalizePath(string $path) : string
Parameters
- $path : string
-
Path to normalize
Return values
string —Normalized path
normalizeSchema()
Normalizes directory schema.
private
normalizeSchema(array<int, string>|string $schema) : array<int, string>
Parameters
- $schema : array<int, string>|string
-
Directory schema to normalize
Return values
array<int, string> —Normalized schema components
replaceTokens()
Replaces tokens in a path segment.
private
replaceTokens(string $part, DateTimeInterface $date) : string
Parameters
- $part : string
-
Path segment with potential placeholders
- $date : DateTimeInterface
-
Date to use for replacements
Return values
string —Processed path segment
resolveFolderPath()
Resolves a folder path based on key.
private
resolveFolderPath(string|null $folderKey) : string|null
Parameters
- $folderKey : string|null
-
Identifier for the folder to resolve
Return values
string|null —Resolved folder path or null if not found
resolveSelectedFolders()
Resolves folder paths based on key.
private
resolveSelectedFolders(string|null $folderKey) : array<int, string>
Parameters
- $folderKey : string|null
-
Identifier for the folder to resolve
Return values
array<int, string> —Array of resolved folder paths
sanitizePathSegment()
Sanitizes a path segment.
private
sanitizePathSegment(string $segment) : string
Parameters
- $segment : string
-
Segment to sanitize
Return values
string —Sanitized segment