Luminova Framework

PHP Luminova: Integrating Third-Party Cloud Storage Services

Last updated: 2025-05-22 10:24:03

File Storage allows you to seamlessly integrate various storages like AWS S3, Azure Blob, into your PHP application, providing flexibility and convenience in handling file and directory operations.

The Storage class provides an interface for interacting with various storage adapters such as local file storage, FTP servers, in-memory storage, and cloud storage services like AWS S3, Azure Blob, and Google Cloud Storage. This class serves as an extension of the powerful PHP library League Filesystem, which offers convenient methods for common file and directory operations.

To get started with the Storage class, ensure that you have installed the filesystem package by running the Composer command.

composer require league/flysystem:^3.0

Additionally, make sure to install the required dependencies for the chosen storage driver. You can refer to the configuration for the required drivers depending on the storage you want in the League Storage Filesystem Configuration documentation.


Examples

Base usage, write to local storage.

use Luminova\Storages\Storage;

Storage::context(Storage::LOCAL)
    ->write('example.txt', 'Hello, World!');

To save file and generate a symbolic public URL on the go, use toLink method.

use Luminova\Storages\Storage;

echo Storage::context(Storage::LOCAL)
    ->write('example.txt', 'Hello, World!')
    ->toLink();

Note: This method is only for local storage context, for other cloud storage use url method.


To change directory, create the folder and write file to it.

use Luminova\Storages\Storage;

echo Storage::context(Storage::LOCAL)
    ->disk('foo')
    ->write('example.txt', 'Hello, World!');

Use the disk method to change directory and create a new directory.


If you want to change directory without creating the folder use chdir method.

use Luminova\Storages\Storage;

$dir = Storage::context(Storage::LOCAL)
    ->chdir('foo/bar/baz')
    ->mkdir(null); /* Pass null since we already prepare the dir */

Note: The chdir method doesn't change your directory remotely, it only prepare the directory for next execution.


Upload file to server, you can optionally set file configuration using setConfig method.

$file = $request->getFile('file');
$file->setConfig([
    'max_size' =>  1024,
    'min_size' =>  500,
]);

$uploaded = Storage::context(Storage::LOCAL)->upload($file);

if($uploaded){
    echo 'Upload was successful';
}

Class Definition

  • Class namespace: Luminova\Storages\Storage
  • Parent class: Luminova\Storages\Adapters\Adapters

Constants

Available storage contexts.

NameValueDescription
LOCAL'local'Local filesystem storage. Used for reading and writing files on the server's disk.
FTP'ftp'FTP-based storage for remote file access via File Transfer Protocol.
MEMORY'memory'In-memory temporary storage. Files are lost when the process ends. Ideal for caching or testing.
AWS_S3'aws-s3'Amazon S3 cloud storage using synchronous operations.
AWS_ASYNC_S3'aws-async-s3'Amazon S3 storage with asynchronous support for background uploads.
AZURE_BLOB'azure-blob'Microsoft Azure Blob Storage for scalable cloud file storage.
GOOGLE_CLOUD'google-cloud'Google Cloud Storage (GCS) for storing and managing data in the Google Cloud ecosystem.
SFTP_V3'sftp-v3'Secure File Transfer Protocol version 3. Provides encrypted SSH file transfers.
WEB_DEV'web-dev'WebDAV protocol-based storage. Useful for web-based file access and management.
ZIP_ARCHIVE'zip-archive'ZIP archive storage for writing and managing files inside compressed .zip files.

Methods

constructor

Constructs a new Storage instance using the specified storage adapter.

This initializes the storage system with the given adapter and its configuration.

Supported Adapters:

  • local
  • ftp
  • memory
  • aws-s3
  • aws-async-s3
  • azure-blob
  • google-cloud
  • sftp-v3
  • web-dev
  • zip-archive
public __construct(string $adapter): mixed

Parameters:

ParameterTypeDescription
$adapterstringThe name of the storage adapter to use.

context

Creates a new Storage instance for the given adapter context.

Provides a convenient way to instantiate the Storage class with a specific storage.

public static context(string $adapter = Storage::LOCAL): self

Parameters:

ParameterTypeDescription
$adapterstringThe storage adapter context. Defaults to local.

Return Value:

self - Return a new instance of the Storage class.


getClient

Get the storage client instance.

public getClient(): ?object

Return Value:

object<\T>|null - Return instance of storage client.


disk

Sets the working directory and creates it if it doesn't exist.

This method changes the current working directory to the specified $location. If the directory does not exist, it will be automatically created.

public disk(string $location): self

Parameters:

ParameterTypeDescription
$locationstringThe target disk path or directory name.

Return Value:

self - Returns the instance of storage class.

Throws:

Note: $location must not be blank or a relative symbol (., ./).


chdir

Changes the current working storage directory.

If the provided $directory is an empty string, . or ./, it resets back to the main storage root.

public chdir(string $directory = './'): self

Parameters:

ParameterTypeDescription
$directorystringThe new relative directory path.

Return Value:

self - Returns the instance of storage class.

Use an empty string, . or ./ to return to root.


url

Get remote file symbolic url.

public url(string $file): ?string

Parameters:

ParameterTypeDescription
$filestringThe file name and path to remove file.

Return Value:

string|null - Return remote url to file otherwise null.


tempUrl

Get a temporal remote url.

public tempUrl(string $file, int $minutes = 1): ?string

Parameters:

ParameterTypeDescription
$filestringThe file name and path to remove file.
$minutesintExpiry duration in minutes.

Return Value:

string|null - Return remote url to file otherwise null.


symbolic

Create a symlink to a target file or directory.

public symbolic(string $target, string $link): ?bool

Parameters:

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

Return Value:

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


write

Writes contents to a file in current working directory.

public write(string $filename, string|resource $contents, bool $steam = false): self

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file.
$contentsstring|resourceThe contents to write string or resource for stream large uploads.
$steamboolThe type of write operation (default: false).
- Passed true when writing using stream.

Return Value:

self - Class instance.

Throws:


upload

Upload file in working directory.

public upload(\Luminova\Http\File $file): bool

Parameters:

ParameterTypeDescription
$file\Luminova\Http\FileInstance of file being uploaded.

Return Value:

bool - Return true if upload was successful false otherwise.

Throws:


Create a symbolic link after writing file to disk.

public toLink(): string|false

Return Value:

string|false - The symbolic link location or false on failure.

This method is only available on local filesystem.

Also it should only be called after method write has been called otherwise it will return false.


checksum

Get the checksum for a file.

public checksum(string $path, array $options = []): string|false

Parameters:

ParameterTypeDescription
$pathstring
$optionsarray

Throws:


read

Reads the contents of a file from the current working directory.

public read(string $filename, bool $steam = false): mixed

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file.
$steamboolThe type of read operation (default: false).
- Passed true when reading large files.

Return Value:

mixed - The file contents.

Throws:


download

Download file from the current working directory.

public download(string $filename, ?string $name = null, bool $steam = false, array $headers = []): mixed

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file.
$namestring|nullDownload file name.
$steamboolThe type of read operation (default: false).
- Passed true when downloading large files.
$headersarrayOptional download headers.

Return Value:

mixed - The file contents.

Throws:


delete

Deletes a file or directory in current working directory.

public delete(string $filename, string $type = 'file'): void

.

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file or directory.
$typestringThe type of deletion operation (file or dir).

Throws:


list

Lists the contents of a directory in the current working directory.

public list(?string $directory = null, string $return = 'files', bool $recursive = false): array

Parameters:

ParameterTypeDescription
$directorystringOptional directory path or it will list all in current directory.
$returnstringThe type of result to return (files, dirs, or all).
$recursiveboolWhether to list recursively.

Return Value:

array - The list of files or directories.

Throws:


fileExist

Checks if a file exists in the current working directory.

public fileExist(string $filename): bool

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file.

Return Value:

bool - True if the file exists, false otherwise.

Throws:


dirExist

Checks if a directory exists in current working directory.

public dirExist(string $path): bool

Parameters:

ParameterTypeDescription
$pathstringThe directory path.

Return Value:

bool - True if the directory exists, false otherwise.

Throws:


exist

Checks if a file or directory exists based on the provided type.

public exist(string $filename, string $type = 'file'): bool

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file or directory.
$typestringThe type of entity to check (file or dir).

Return Value:

bool - True if the file or directory exists, false otherwise.

Throws:


has

Checks if a file or directory exists based on the provided URL or path.

public has(string $filename): bool

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file or directory, which can also be a URL.

Return Value:

bool - True if the file or directory exists, false otherwise.

Throws:


modified

Retrieves the last modified timestamp of a file.

public modified(string $filename): int

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file.

Return Value:

int - The UNIX timestamp of the last modification time.

Throws:


mime

Retrieves the MIME type of a file.

public mime(string $filename): string

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file.

Return Value:

string - The MIME type of the file.

Throws:


size

Retrieves the size of a file.

public size(string $filename): int

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file.

Return Value:

int - The size of the file in bytes.

Throws:


visibility

Retrieves or sets the visibility of a file or directory.

public visibility(string $filename, ?string $visibility = null): false|string

Parameters:

ParameterTypeDescription
$filenamestringThe name of the file or directory.
$visibilitystring|nullOptional. The visibility to set ('public', 'private', or null to retrieve). Default is null.

Return Value:

false|string - If $visibility is null, returns the current visibility as a string ('public' or 'private').If $visibility is provided update visibility and returns the visibility that was set.Otherwise returns false if operation failed.

Throws:


mkdir

Create a directory in the current working path.

If no path is provided, the method will use the value set via chdir().

public mkdir(?string $path = null): void

Parameters:

ParameterTypeDescription
$pathstring|nullOptional directory path to create.
If null, the previously set working path is used.

Throws:


move

Moves a file or directory from the current working directory to a new location.

public move(string $source, string $destination): void

Parameters:

ParameterTypeDescription
$sourcestringThe current path of the file or directory.
$destinationstringThe new path for the file or directory.

Throws:


copy

Copies a file or directory from the current working directory to a new location.

public copy(string $source, string $destination): void

Parameters:

ParameterTypeDescription
$sourcestringThe path of the original file or directory.
$destinationstringThe path of the destination file or directory.

Throws: