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

Outputs any file content in the browser, with appropriate headers.

public output(string $basename, int $expiry, array<string,mixed> $headers = []): 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

Displays image content in the browser with appropriate headers. Using the external package 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) - New output width.
• height (int) - New output height.
• ratio (bool) - Use aspect ratio while resizing image.
• quality (int) - Image quality.

Return Value:

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

Throws:

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

To use this method you need to install NanoImage first by running command composer require peterujah/nano-image

temporal

To processes and output a temporal file URL based on URL hash to determine the expiration.

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

Parameters:

Return Value:bool - True if file output is successful, false otherwise.

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

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.