PHP Luminova: File System Management Utilities
File Manager is a helper class shipped with Luminova Framework to handle file-related operations like downloading, reading or writing files, all methods are defined as static making it easier to call.
The Luminova FileSystem
is a core component of the Luminova framework designed for managing file-related operations. It handles tasks such as retrieving system paths, downloading, reading, and writing files. With its static
methods, FileSystem
offers convenient and efficient file management within both the framework and your application.
- Class namespace:
\Luminova\Storages\FileManager
Helper Function
Using helper functions to access class object and properties.
<?php
echo path('system');
echo factory('files', true)->system;
Outputs
Windows: /system/
Unix: \\system\\
Properties
system
Path to the system framework codes.
protected string $system
plugins
Path to the system third-party plugins.
protected string $plugins
library
Path to the libraries and third-party modules.
protected string $library
services
Path to the serialized shared services.
protected string $services
controllers
Path to the application controllers.
protected string $controllers
writeable
Path to the writeable files.
protected string $writeable
logs
Path to the error logs.
protected string $logs
caches
Path to the application caches.
protected string $caches
public
Path to the public controller document root.
protected string $public
assets
Path to the public assets directory.
protected string $assets
views
Path to the template views files.
protected string $views
routes
Path to the application routes.
protected string $routes
languages
Path to the languages modules.
protected string $languages
Methods
permission
Check if file has read, write or read+write permission is granted.
public static permission(string $permission = 'rw', string|null $file = null, bool $quiet = false): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$permission | string | File access permission (e.g: rw , r or w ). |
$file | string|null | File name or file path to check permissions (default: writeable dir). |
$quiet | bool | Indicate whether to throws an exception if permission is not granted. |
Return Value:
bool
- Returns true if permission is granted otherwise false.
Throws:
- \Luminova\Exceptions\FileException - If permission is not granted and quiet is not passed true.
setPermission
Set permissions for a file or directory.
public static setPermission(string $location, int $permission): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$location | string | The path to the file or directory. |
$permission | int | The permission to set (Unix file permissions). |
Return Value:
bool
- True on success, false on failure.
permissions
Converts file permission code to its string representation
public static permissions(int $permission): string
Parameters:
Parameter | Type | Description |
---|---|---|
$permission | int | Permission code |
Return Value:
string
- Permission string representation.
toUnixPermission
Convert permission string to Unix integer permission.
public static toUnixPermission(string $permission): int|null
Parameters:
Parameter | Type | Description |
---|---|---|
$permission | string | The permission string (e.g., 'rw-r--r--'). |
Return Value:
int|null
- The Unix integer permission, or null if the conversion failed.
write
Write or append contents to a file.
public static write(string $filename, string|resource $content, int $flags, resource $context = null): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$filename | string | — Path to the file where to write the data. |
$content | string|resource | The contents to write to the file, either as a string or a stream resource. |
$flags | int | File flags, it can be combination flags joined with the binary OR (|) operator. |
$context | resource | [optional] A valid context resource created with stream_context_create. |
Return Value:
bool
- Return true if content was write successfully, otherwise false.
Throws:
- \Luminova\Exceptions\FileException - If unable to write file.
stream
Write or append contents to a file.
public static stream(string $filename, resource $resource, int $flags, resource $context = null): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$filename | string | Path to the file where to write the data. |
$resource | resource | The contents to write to the file as a stream resource. |
$flags | int | [optional] The value of flags can be any combination of the following flags (with some restrictions), joined with the binary OR (|) operator. |
$context | resource | [optional] A valid context resource created with stream_context_create. |
Return Value:
bool
- Return true if the operation was successful, false otherwise.
Throws:
- \Luminova\Exceptions\FileException - If unable to write file or invalid resource.
mkdir
Attempts to create the directory, if it doesn't exist.
public static mkdir(string $path, int $permissions = 0777, bool $recursive = true): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$path | string | Directory path to create. |
$permissions | int | Unix file permissions |
$recursive | bool | Allows the creation of nested directories specified in the pathname (default: true). |
Return Value:
bool
- Return true if directory already existed or was created successfully, otherwise false.
Throws:
- \Luminova\Exceptions\RuntimeException - If path is not readable.
- \Luminova\Exceptions\FileException - If unable to create directory
copy
Copy files and folders from the source directory to the destination directory.
public static copy(string $origin, string $dest, int& $copied = 0): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$origin | string | The source directory. |
$dest | string | The destination directory. |
$copied | int | Reference to a variable to store the number of copied items. |
Return Value:
bool
- Return true if the copy operation is successful, false otherwise.
move
Move files and folders from one location to another recursively.
public static move(string $origin, string $dest, int& $moved = 0): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$origin | string | The source directory or file path. |
$dest | string | The destination directory path. |
$moved | int | Reference to a variable to store the number of moved items. |
Return Value:
bool
- Return true if the operation is successful, false otherwise.
size
To calculate the size of a given file or an entire directory.If a directory is specified, it calculates the size of a given path recursively to determine total size of all files within the directory.
public static size(string $path): int
Parameters:
Parameter | Type | Description |
---|---|---|
$path | resource | The path to the file or directory.. |
Return Value:
int
- Return the size in bytes.
Throws:
\Luminova\Exceptions\FileException - Throws If the path does not exist.
read
The read
method is a combination of readBinary
and readText
, with an additional check for type-specific handling.It was optimized for efficiency in reading a large file in chunks or smaller files using fpassthru
public static read($handler, int $filesize, string $mime, int $length = (1 << 21)): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$handler | resource | The file handler. |
$filesize | int | The size of the file. |
$mime | string | The MIME type of the file. |
$length | int | The length of each chunk (default: 2MB). |
Return Value:
bool
- Return true if the file was successfully read, false otherwise.
Example
<?php
$filename = 'large-file.pdf';
if ($handler = fopen($filename, 'rb')) {
$filesize = filesize($filename);
$mime = get_mime($filename);
FileManager::read($handler, $filesize, $mime);
}
readBinary
Reads binary files in chunks, this method is suitable for reading PDF
, AUDIO
, IMAGES
and other types of files that preserving lines ending isn't necessary.
public static readBinary($handler, int $length = (1 << 21)): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$handler | resource | The file handler. |
$length | int | The length of each chunk (default: 2MB). |
Return Value:
bool
- Return true if the file was successfully read, false otherwise.
readText
Reads a text-based files in chunks while preserving line endings, suitable for handling TEXT
, MD
, LOG
and more.
public static readText($handler, int $filesize, int $length = (1 << 21)): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$handler | resource | The file handler. |
$filesize | int | The size of the file. |
$length | int | The length of each chunk (default: 2MB). |
Return Value:
bool
- Return true if the file was successfully read, false otherwise.
isResource
Checks if a variable is a valid resource of the specified type.
public static isResource(mixed $resource, ?string $type = null): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$resource | mixed | The resource to check. |
$type | string | The expected resource type. Possible values are: 'stream-context', 'stream', etc. |
Return Value:
bool
- Returns true if the variable is a resource and matches the expected resource type, otherwise returns false.
download
Download a file to the user's browser.
public static download(string $file, string|null $name = null, array $headers = [], bool $delete = false): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$file | string | The full file path or content to to download. |
$name | string|null | The filename as it will be shown in the download. |
$headers | array | Optional passed headers for download. |
$delete | bool | Whether to delete the file after download (default: false). |
Return Value:
bool
- Return true on success, false on failure.
remove
Deletes files and folders recursively.
public static remove(string $location, bool $delete_base = false, int& $deleted = 0): int
Parameters:
Parameter | Type | Description |
---|---|---|
$location | string | Directory or file to delete. |
$delete_base | bool | Remove the base directory once done (default is false). |
$deleted | int | Reference to a variable to store the number of deleted items. |
Return Value:
int
- Returns count of deleted files.
symbolic
Create a symlink to a target file or directory.
public static symbolic(string $target, string $link): bool
Parameters:
Parameter | Type | Description |
---|---|---|
$target | string | The targe file or directory to link from. |
$link | string | The location of the link. |
Return Value:
bool
- Return true if the link was successfully created false otherwise.