Luminova Framework

PHP Luminova: Cloud Storags Module

Last updated: 2024-08-28 22:18:47

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

<?php 
use Luminova\Storages\Storage;

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

To save file and generate a symbolic public URL on the go, use toLink method.This method is only for local storage context, for other cloud storage use url method.


<?php 
use Luminova\Storages\Storage;

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

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

<?php 
use Luminova\Storages\Storage;

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

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

<?php 
use Luminova\Storages\Storage;

$dir = Storage::context('local')->chdir('foo/bar/baz');

$dir->mkdir(null); //pass null since we already prepare the dir.

Note this method doesn't change your directory remotely, it only prepare the directory for next executions.


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

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

if(Storage::context('local')->upload($file)){
    echo 'Upload was successful';
}


Methods

constructor

Constructs a new Storage instance with the specified adapter.

public __construct(string $adapter): mixed

Parameters:

ParameterTypeDescription
$adapterstringThe storage adapter to use.

You can either initialize a class instance or use the static context method for easy usage.


context

Creates a new Storage instance for the specified adapter context.

public static context(string $adapter = 'local'): self

Parameters:

ParameterTypeDescription
$adapterstringThe storage adapter context.

Return Value:

self - The New Storage instance.


disk

Creates a new storage disk / directory.

public disk(string $location): self

Parameters:

ParameterTypeDescription
$locationstringThe disk path or name.

Return Value:

self - Return class instance.

Throws:


chdir

Change to another storage directory.

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

Parameters:

ParameterTypeDescription
$directorystringThe new current directory

Return Value:

self - Return class instance.

Shortcut to return to the main storage directory are blank string, . or ./.


url

Get remote file symbolic url.

public url(string $file): string|null

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|null

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|null

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|null $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|null $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

Creates a new directory in the current working directory.

public mkdir(string $path): void

Parameters:

ParameterTypeDescription
$pathstringThe path of the directory to create.

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:


getClient

Get the storage client instance.

public getClient(): mixed

Return Value:

mixed - The client instance.