Luminova Framework

PHP Luminova: File System Management Utilities

Last updated: 2024-09-27 14:11:00

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:

ParameterTypeDescription
$permissionstringFile access permission (e.g: rw, r or w).
$filestring|nullFile name or file path to check permissions (default: writeable dir).
$quietboolIndicate whether to throws an exception if permission is not granted.

Return Value:

bool - Returns true if permission is granted otherwise false.

Throws:


setPermission

Set permissions for a file or directory.

public static setPermission(string $location, int $permission): bool

Parameters:

ParameterTypeDescription
$locationstringThe path to the file or directory.
$permissionintThe 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:

ParameterTypeDescription
$permissionintPermission code

Return Value:

string - Permission string representation.


toUnixPermission

Convert permission string to Unix integer permission.

public static toUnixPermission(string $permission): int|null

Parameters:

ParameterTypeDescription
$permissionstringThe 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:

ParameterTypeDescription
$filenamestring— Path to the file where to write the data.
$contentstring|resourceThe contents to write to the file, either as a string or a stream resource.
$flagsintFile flags, it can be combination flags joined with the binary OR (|) operator.
$contextresource[optional] A valid context resource created with stream_context_create.

Return Value:

bool - Return true if content was write successfully, otherwise false.

Throws:


stream

Write or append contents to a file.

public static stream(string $filename, resource $resource, int $flags, resource $context = null): bool

Parameters:

ParameterTypeDescription
$filenamestringPath to the file where to write the data.
$resourceresourceThe contents to write to the file as a stream resource.
$flagsint[optional] The value of flags can be any combination of the following flags (with some restrictions), joined with the binary OR (|) operator.
$contextresource[optional] A valid context resource created with stream_context_create.

Return Value:

bool - Return true if the operation was successful, false otherwise.

Throws:


mkdir

Attempts to create the directory, if it doesn't exist.

public static mkdir(string $path, int $permissions = 0777, bool $recursive = true): bool

Parameters:

ParameterTypeDescription
$pathstringDirectory path to create.
$permissionsintUnix file permissions
$recursiveboolAllows 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:


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:

ParameterTypeDescription
$originstringThe source directory.
$deststringThe destination directory.
$copiedintReference 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:

ParameterTypeDescription
$originstringThe source directory or file path.
$deststringThe destination directory path.
$movedintReference 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:

ParameterTypeDescription
$pathresourceThe 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:

ParameterTypeDescription
$handlerresourceThe file handler.
$filesizeintThe size of the file.
$mimestringThe MIME type of the file.
$lengthintThe 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:

ParameterTypeDescription
$handlerresourceThe file handler.
$lengthintThe 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:

ParameterTypeDescription
$handlerresourceThe file handler.
$filesizeintThe size of the file.
$lengthintThe 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:

ParameterTypeDescription
$resourcemixedThe resource to check.
$typestringThe 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.


isAccessible

Validate if the provided file path is safe, exists, and is readable.This method checks if the file path is valid, whether it is accessible, and ensures it's readable unless it's a UNC path.

public static isAccessible(string $path): bool

Parameters:

ParameterTypeDescription
$pathstringThe file path to validate (relative or absolute).

Return Value:

bool - Returns true if the file is accessible and readable.


isPathPermitted

Verify if the file path follows the allowed format and is not a URL or PHP Archive (Phar).This method ensures that the file path does not use a URL scheme or a phar path, restricting access to local files only.

public static isPathPermitted(string $path): bool

Parameters:

ParameterTypeDescription
$pathstringThe file path to check (relative or absolute).

Return Value:

bool - Returns true if the path is a valid local file path.


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:

ParameterTypeDescription
$filestringThe full file path or content to to download.
$namestring|nullThe filename as it will be shown in the download.
$headersarrayOptional passed headers for download.
$deleteboolWhether 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:

ParameterTypeDescription
$locationstringDirectory or file to delete.
$delete_baseboolRemove the base directory once done (default is false).
$deletedintReference 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:

ParameterTypeDescription
$targetstringThe targe file or directory to link from.
$linkstringThe location of the link.

Return Value:

bool - Return true if the link was successfully created false otherwise.