GitHub
Luminova Framework
Toggle Theme
Version

File Upload Integration with Uploader Module

Last updated: 2024-10-03 20:45:15

File Uploader class is a simple PHP class shipped with Luminova Framework to handle file uploads as an alternative to the Storage class.

The File Uploader class is included with the Luminova's Framework. It serves as an alternative to the Storage class and is designed to handle local file uploads using methods like upload for uploading a file to the server, and chunk for large file uploads using client-side chunking or write for Uploading content from string.

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.

<?php 
use Luminova\Storages\Uploader;

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

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

Using Write with String Content

To write a content to file.

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

Upload an entire file to server, by first reading the file from temp, and slowing writing to destination in chunk.

public static upload(\Luminova\Http\File $file, string|null $path = null): bool

Parameters:

ParameterTypeDescription
$file\Luminova\Http\FileInstance of file being uploaded.
$pathstring|nullUpload file location if not already set in file setConfig method.

Return Value:

bool - Return true if upload was successful false otherwise.

Throws:

move

Moves an uploaded file from temp to it new location using traditional PHP move_uploaded_file.

public static move(\Luminova\Http\File $file, string|null $path = null): bool

Parameters:

ParameterTypeDescription
$file\Luminova\Http\FileInstance of file being uploaded.
$pathstring|nullUpload file location if not already set in file setConfig method.

Return Value:

bool - Return true if upload was successful false otherwise.

Throws:

chunk

Uploads a file to the server using stream file upload, allowing large files to be uploaded in chunks.This can be implemented with client side JavaScript like Plupload or other that support chunk uploads.

public static chunk(\Luminova\Http\File $file, string|null $path = null, int $chunk = 0, int $chunks = 0): bool|int

Parameters:

ParameterTypeDescription
$file\Luminova\Http\FileInstance of file being uploaded.
$pathstring|nullThe directory path where the file will be stored.
$chunkintThe current chunk part index (start: 0).
$chunksintThe total number of chunks parts the server will be expecting (start: 0).

Return Value:

bool|int - Return true if upload was successful, false otherwise. If chunks are being uploaded, returns remaining chunks count.

Throws:

write

Wite contents to a file, this can be either a string or resource (e.g., a stream), use stream_get_contents to read the entire stream into a string before writing it.

public static write(string $filename, string|resource $contents): bool

Parameters:

ParameterTypeDescription
$filenamestringThe file path and and name the to put content.
$contentsstring|resourceThe contents to be written to the file.

Return Value:

bool - Returns true if the file was successfully written, false otherwise.

« Previous Secure Files Access
Next » File Streaming
On this page