PHP Luminova: Secure File Access and Browser Delivery with FileDelivery Module

The FileDelivery class offers essential methods for handling and delivering files from private storage to end-users via web requests. It can output files with appropriate headers, generate and handle temporary URLs for file access, and manage browser cache for faster loading when needed.

Additionally, it provides an option to resize output images using the external library NanoImage.

This class functions as a CDN helper, designed to create an efficient content delivery system for serving files anywhere.

Examples

This display image in browser, here is a simple example.

<?php
use \Luminova\Storages\FileDelivery;
use \Luminova\Base\BaseViewController;

class CdnController extends BaseViewController
{
    //...

    public function showImage(?string $image = null): int 
    {
        $image ??= 'default-image.png';
        FileDelivery::storage('images')->output($image);

        return STATUS_SUCCESS;
    }
}

To generate a temporary URL for an image that expires after a specified duration, use the following example.

<?php
use \Luminova\Storages\FileDelivery;

$temporalUrl = FileDelivery::storage('images')
    ->url('private-image.png', 3600);

// Output the complete URL for file preview
echo 'https://example.com/static/file/' . $temporalUrl; 

Note:The above code snippet will output only the hash for the selected image. You will need to append this hash to your site URL as required in your controller routing for capturing image previews.

Optionally, you can use an online URL shortener to shorten the URL if it appears too long due to the encryption used.

To preview the temporal image generated above see below example.

use \Luminova\Storages\FileDelivery;
use \Luminova\Base\BaseViewController;
class CdnController extends BaseViewController
{
    //...

    public function tempImagePreview(string $ImageHash): int 
    {
        if(FileDelivery::storage('images')->temporal($ImageHash)){
            return STATUS_SUCCESS;
        }

        return STATUS_ERROR;
    }
}

Class Definition

• Class namespace: \Luminova\Storages\FileDelivery
• This class is marked as final and can't be subclassed

Methods

constructor

Initialize the constructor to have full access to the path where your file is located without any limitation like using storage method.

public __construct(string $filepath, bool $etag): mixed

Parameters:

storage

To initialize the FileDelivery with a base path, ETag option and return static instance.

public static storage(string $basepath, bool $etag = true): static

Parameters:

Return Value:static - Return Instance of the FileDelivery class.

NoteYour files must be stored in the storage directory located in /writeable/storages/.Additionally, you don't need to specify the /writeable/storages/ in your $basepath parameter.

output

Read and outputs any file content in the browser, with appropriate headers.

public output(
    string $basename, 
    int $expiry = 0, 
    array $headers = [],
    int $length = (1 << 21),
    int $delay = 0
): bool

Parameters:

Return Value:

bool - Returns true if file output is successfully, false otherwise.

By default 304, 404 and 500 headers will be set based file status and cache control.

outputImage

Modify and output image with appropriate headers. Using the external package \Peterujah\NanoBlock\NanoImage, you can customize the image's width, height, quality, and resizing ratio.

public outputImage(string $basename, int $expiry = 0, array $options = [], array $headers = []): bool

Parameters:

Filter Options

• width (int) - Set new output width (default: 200).
• height (int) - Set new output height (default: 200).
• ratio (bool) - Specify weather to aspect ratio while resizing image (default: true).
• quality (int) - Set the output image quality (default: 100, 9 for PNG).

Return Value:

bool - Returns true if file output is successfully, false otherwise.

Throws:

\Luminova\Exceptions\RuntimeException - Throws if NanoImage image is not installed or if error occurred during image processing.

Note: This method relay on external image library to modify the width and height.To use this method you need to install Peter Ujah's NanoImage following the below instructions.

Composer Command:

If you don't already have it, run this command

composer require peterujah/nano-image

temporal

Temporally output file based on the URL hash key if valid and not expired.

public temporal(string $url_hash, array $headers = []): bool

Parameters:

Return Value:

bool - Return true if file output is successful, false otherwise.

Note: This method uses Encryption and Decryption class to encrypt and decrypt URL hash.

Throws:

\Luminova\Exceptions\EncryptionException - Throws if decryption failed or an error is encountered.

url

To generate a temporal URL with an expiration time for given filename.

public url(string $basename, int $expiry = 3600): string|false

Parameters:

Return Value:

string|false - Return based64 encrypted HASH, otherwise false.

Throws:

\Luminova\Exceptions\EncryptionException - Throws if encryption failed or an error occurred.