PHP Luminova: Handling File Uploads with the Uploader Class

The Uploader class is built into the Luminova Framework as a lightweight alternative to the Luminova\Storages\Storage class. It is designed for handling local file uploads efficiently, offering methods like:

• upload – for standard file uploads,
• chunk – for large files using client-side chunking,
• write – for saving content directly from a string.

This class works well with the File Upload Object (Luminova\Http\File), enabling customizable upload handling and clear, detailed feedback for each upload process.

Usage Examples

Using Upload with File Object

Upload file to server, you can optionally pass the upload_path in second parameter or set in file configuration using setConfig method.

use Luminova\Storages\Uploader;

$file = $request->getFile('file');

$upload = Uploader::upload($file, root(__DIR__, 'writeable/storages/foo/'));
if($upload){
    echo 'Upload was successful';
}

// Get message from file object
echo $file->getMessage();

Using Write with String Content

To write a content to file.

use Luminova\Storages\Uploader;

$upload = Uploader::write(root('writeable/storages/foo/'), 'Hello world');

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

Using Chunk with File Object

This example demonstrates how you can upload large file using chunk method and browser-side chunking like Plupload.

// /app/Controller/Http/UploadController.php

namespace App\Controllers\Http;

use Luminova\Base\BaseController;
use Luminova\Attributes\Route;
use Luminova\Attributes\Prefix;
use Luminova\Storages\Uploader;

#[Prefix(pattern: '/api/v1/(:root)')]
class UploadController extends BaseController 
{
    #[Route('/api/v1/upload', method: ['POST'])]
    public function upload(): int
    {
        $file = $this->request->getFile('file');

        if (!$file) {
            return response(400)->json(['message' => 'No file uploaded or invalid file.']);
        }

        // Set upload configurations
        $file->setConfig([
            'upload_path' => root('writeable/storages/foo/'),
            'chunk_length' => 5242880 /* The length of each chunk in bytes (default is 5MB) */
        ]);

        if (!$file->valid()) {
            return response(400)->json(['message' => 'File validation failed: ' . $file->getError()]);
        }

        // Get the current chunk and total chunks from the request
        $chunk = (int) strict($this->request->getPost('chunk', 0), 'int');
        $chunks = (int) strict($this->request->getPost('chunks', 0), 'int');

        $status = Uploader::chunk($file, null, $chunk, $chunks);

        if ($status === true) {
            return response(201)->json(['message' => 'File uploaded successfully.']);
        }

        if (is_int($status)) {
            return response(206)->json(['message' => 'File partially uploaded.', 'remaining' => $status]);
        }

        return response(500)->json(['message' => 'File upload failed.']);
    }
}

Each request to backend should contain total number of chunk parts, and the current index of current chunk uploading.

Class Definition

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

Methods

upload

Uploads a file to the server by transferring data from a temporary source or string contentof file-object to a specified destination. Supports chunked writing for resource management.

public static upload(
    File $file, 
    ?string $path = null, 
    int $delay = 0, 
    ?string &$destination = null
): bool

Parameters:

Return Value:

bool - Return true if the upload is successful, false otherwise.

Throws:

• \Luminova\Exceptions\StorageException - Throws if the upload path is not configured or permission to create it was denied.

move

Moves an uploaded file from a temporary location to a permanent destination on server.

This method uses traditional PHP move_uploaded_file.

public static move(File $file, ?string $path = null, ?string &$destination = null): bool

Parameters:

Return Value:

bool - Return true if the move is successful, false otherwise.

Throws:

• \Luminova\Exceptions\StorageException - Throws if the upload path is not configured or permission to create it was denied.

chunk

Uploads a file in chunks to a specified destination.

This method supports large file uploads by splitting the file into smaller, manageable parts. The chunk splitting is typically done from client side e.g, JavaScript, using libraries like Plupload or similar to handles chunking before sending data.

public static chunk(
    File $file, 
    ?string $path = null, 
    int $chunkIndex = 0, 
    int $totalChunks = 0,
    int $uploadDelay = 0,
    ?string &$destination = null
): bool|int

Parameters:

Return Value:

bool|int - Returns true if the upload is complete, false on failure. If the upload is still in progress, returns the remaining chunk count.

Throws:

• \Luminova\Exceptions\StorageException - Throws if the upload path is not configured or lacks proper permissions.

write

Writes content to a file at the specified path.

This method can handle either a string or resource (e.g., a stream), using stream_get_contents to read the entire stream into a string before writing it.

public static write(string $filename, resource|string $contents, string $mode = 'w'): bool

Parameters:

Return Value:

bool - Return true if the file is written successfully, false otherwise.