File Uploader #

This Dart package provides a file upload functionality that is implementation-agnostic.

Features #

This library provides the capability to:

• ☑ upload a complete file;
• ☑ upload a file in chunks;
• ☑ upload a file in chunks with the ability to pause and resume the upload from where it left off (restorable chunks file upload).

File uploader can be used with various libraries for making HTTP requests, such as http, dio, or others, offering a consistent and straightforward interface for uploading files without needing to change the code based on the underlying library used.

This library also supports the web platform.

Plugins #

• http_file_uploader This plugin allows you to implement file uploads using the http library.

• dio_file_uploader This plugin allows you to implement file uploads using the http library.

UI #

This package uses en_file_uploader and provides widgets for displaying and managing file uploads.

Extensions #

If a plugin is not yet available or the existing plugins do not meet your needs, you can create your own implementation of file upload.

File Uploader APIs #

Upload implementations #

It is possible to extend:

• FileUploadHandler to implement the upload of an entire file;
• ChunkedFileUploadHandler to implement chunked file upload;
• RestorableChunkedFileUploadHandler to implement a restorable chunked upload.

The plugins already do this, so before creating your own implementation, check if a plugin already meets your needs.

Support restorable chunked file upload #

To implement a restorable file server, the following functionalities need to be supported:

• An API to present the file; before uploading the chunks, the file is presented and needs an id. This id will be used as a reference for chunk uploads;
• An API that, given the presentation id, allows requesting the file's state. The file's state will return the offset of the next chunk to be sent. This is needed to support retrying from the last unsent chunk.

Configuration #

A global configuration is available to set default values for the entire system.

Currently, it is possible to set a default chunk size.

setDefaultChunkSize(1024)

Logger #

It is possible to implement the FileUploaderLogger class to manage the logs generated by the library.

// It's just an example, not a production-ready version.
// Every log is printed
class PrinterLogger implements FileUploaderLogger {
  @override
  void error(String message, error, stackTrace) {
    print(error);
  }

  @override
  void info(String message) {
    print(message);
  }

  @override
  void warning(String message) {
    print(message);
  }
}

If you're looking for a library to handle logging in your project, you can check out another library I created: en_logger.

File #

File are handled with the XFile class from the cross_file package. This abstraction allow the library to be used across multiple platforms.

How to use #

Create a FileUploadController by passing a concrete implementation of FileUploadHandler, ChunkedFileUploadHandler, or RestorableChunkedFileUploadHandler as the handler.

class MyFileUploadHandler extends FileUploadHandler {
  MyFileUploadHandler({required super.file});

  @override
  Future<void> upload({ProgressCallback? onProgress}) {
    // TODO: implement upload
    // Ex. http.post(url, body: file);
  }
}

class MyChunkedFileUploadHandler extends ChunkedFileUploadHandler {
  MyChunkedFileUploadHandler({required super.file});

  @override
  Future<void> uploadChunk(FileChunk chunk, {ProgressCallback? onProgress}) {
    // TODO: implement uploadChunk
    // Ex. http.post(url, body: chunk);
  }
}

class MyRestorableChunkedFileUploadHandler extends RestorableChunkedFileUploadHandler {
  MyRestorableChunkedFileUploadHandler({required super.file});

  @override
  Future<void> uploadChunk(FileChunk chunk, {ProgressCallback? onProgress}) {
    // TODO: implement uploadChunk
    // Ex. http.post(url, body: chunk);
  }

  @override
  Future<FileUploadPresentationResponse> present() {
    // TODO: implement present
    // Ex. http.post(url, body: file);
  }

  @override
  Future<FileUploadStatusResponse> status(FileUploadPresentationResponse presentation) {
    // TODO: implement status
    // Ex. http.get(url, body: presentation);
  }
}

The controller will have the capabilities to upload a file and retry the upload.

final handler = getHandler();
final controller = FileUploadController(handler);

controller.upload(); // upload the file
controller.retry(); // retry the upload
controller.uploaded // check if the file is uploaded

Tip #

Implement your own specific handler as an internal, private component and configure your business logic around the FileUploadController. The controller should be the only interface used to manage and display upload state, while keeping the handler implementation hidden.

class MyBusinessLogic extends ChangeNotifier {
  MyBusinessLogic({required this.controller});

  factory MyBusinessLogic.handler(FileUploadHandler handler) {
    return MyBusinessLogic(controller: FileUploadController(handler));
  }

  final FileUploadController controller;
  bool _isUploading = false;
  bool get isUploading => _isUploading;

  void uploadFile() {
    _isUploading = true;
    notifyListeners();

    controller.upload(onProgress: (progress, total) {
      ...
    });

    ...
  }
}

Example #

In the example, there is an implementation of RestorableChunkedFileUploadHandler handler that sends chunks to a mock server (InMemoryBackend).

Other examples are provided in the tests to ensure the correct functionality of the library.