PHP Luminova: Integrating Third-Party Cloud Storage Services

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.

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:

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:

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:

Return Value:

self - Returns the instance of storage class.

Throws:

• Luminova\Exceptions\StorageException - If the path is invalid or the directory creation fails.

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:

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:

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:

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:

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:

Return Value:

self - Class instance.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the write operation.

upload

Upload file in working directory.

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

Parameters:

Return Value:

bool - Return true if upload was successful false otherwise.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the upload operation.

toLink

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:

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the write operation.

read

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

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

Parameters:

Return Value:

mixed - The file contents.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the read operation.

download

Download file from the current working directory.

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

Parameters:

Return Value:

mixed - The file contents.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the read operation.

delete

Deletes a file or directory in current working directory.

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

.

Parameters:

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the deletion operation.

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:

Return Value:

array - The list of files or directories.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the listing operation.

fileExist

Checks if a file exists in the current working directory.

public fileExist(string $filename): bool

Parameters:

Return Value:

bool - True if the file exists, false otherwise.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the existence check.

dirExist

Checks if a directory exists in current working directory.

public dirExist(string $path): bool

Parameters:

Return Value:

bool - True if the directory exists, false otherwise.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the existence check.

exist

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

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

Parameters:

Return Value:

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

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the existence check.

has

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

public has(string $filename): bool

Parameters:

Return Value:

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

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the existence check.

modified

Retrieves the last modified timestamp of a file.

public modified(string $filename): int

Parameters:

Return Value:

int - The UNIX timestamp of the last modification time.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the retrieval.

mime

Retrieves the MIME type of a file.

public mime(string $filename): string

Parameters:

Return Value:

string - The MIME type of the file.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the retrieval.

size

Retrieves the size of a file.

public size(string $filename): int

Parameters:

Return Value:

int - The size of the file in bytes.

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the retrieval.

visibility

Retrieves or sets the visibility of a file or directory.

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

Parameters:

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:

• Luminova\Exceptions\StorageException - If an error occurs during the operation.

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:

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the creation.

move

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

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

Parameters:

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the move operation.

copy

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

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

Parameters:

Throws:

• Luminova\Exceptions\StorageException - If an error occurs during the copy operation.