DEV Community

Cover image for File Upload Wrapper Library
diar.dev
diar.dev

Posted on • Updated on

File Upload Wrapper Library

The File Upload Wrapper is a PHP library that simplifies file uploads by providing a set of easy-to-use classes that handle common validation and processing tasks.
With this library, you can:

  • Validate uploaded files with ease
  • Process uploaded files with targeted validations for specific fields
  • Simplify the file upload process with a set of easy-to-use classes

Getting Started

To use the library, follow these steps:

  1. Install the library using Composer:
composer require didslm/file-upload-wrapper
Enter fullscreen mode Exit fullscreen mode
  1. Import the classes you need:
use Didslm\FileUpload\Uploader;
use Didslm\FileUpload\File;
use Didslm\FileUpload\Validation\FileSize;
use Didslm\FileUpload\Validation\FileType;
use Didslm\FileUpload\Validation\Dimension;
use Didslm\FileUpload\FieldValidation;
use Didslm\FileUpload\Attributes\Image;
use Didslm\FileUpload\Attributes\Document;
use Didslm\FileUpload\Exceptions\FileUploadException;
Enter fullscreen mode Exit fullscreen mode
  1. Use the upload() method to handle file uploads for your entity:
class Product {
    #[Image(requestField: "request_field", dir: "/public")]
    private string $image;

    #[Image(requestField: "profile_field", dir: "/public", required: false)]
    private string $profile;

    // ...
}

$product = new Product();

Uploader::upload($product, [
    new FileType([File::JPEG]),
    new FileSize(2, File::MB)
]);

Enter fullscreen mode Exit fullscreen mode

Examples

Handling File Uploads for an Entity

The following code shows an example of how to use the library to handle file uploads for an entity:

class Product {
    //...
    #[Image(requestField: "request_field", dir: "/public")]
    private string $image;

    #[Image(requestField: "profile_field", dir: "/public", required: false)]
    private string $profile;

    public function getImageFilename(): string
    {
        return $this->image;
    }

    public function getProfileFilename(): string
    {
        return $this->profile;
    }
}

Enter fullscreen mode Exit fullscreen mode

In this example, the Product class has two properties image and profile that are decorated with the Image attribute.

Types

In the following example you will see a list of available Attribute types:

#[new Image(requestName: 'file_upload_field', dir: '/upload/dir')]
#[new Document(requestName: 'cv_file', dir: '/upload/dir')]
#[new Video(requestName: 'video_file', dir: '/upload/dir')]
Enter fullscreen mode Exit fullscreen mode

The Image attribute provides metadata to the library to process the files correctly during the upload.

The Document attribute provides metadata to the library to process the files correctly during the upload.

The Video attribute provides metadata to the library to process the files correctly during the upload.

The upload() method is then called on the Uploader class with the Product object and an array of validation rules as its parameters.

$product = new Product();

Uploader::upload($product, [
    new FileType([File::JPEG]),
    new FileSize(2, File::MB)
]);

echo $product->getImageFilename();

Enter fullscreen mode Exit fullscreen mode

Handling Exceptions

The library provides a FileUploadException class that all exceptions thrown by the library extend. This means that you can catch all exceptions using FileUploadException in a try-catch block, as shown below:

try {
    Uploader::upload($product, [
        new FileType([File::PNG]),
        new FileSize(2, File::MB)
    ]);
} catch (FileUploadException $e) {
    // handle exception
}
Enter fullscreen mode Exit fullscreen mode

Validation

The library provides several validation classes that you can use to validate uploaded files. These classes can be passed as parameters to the upload() method to specify the validation rules for the files being uploaded.

Type

The FileType class is used to check the file type. You can specify the types of files allowed by passing an array of file types to the constructor. For example:

new FileType([File::PNG, File::JPEG, File::GIF])
Enter fullscreen mode Exit fullscreen mode

Size

The FileSize class is used to validate the file size. You can specify the maximum file size allowed by passing the size in bytes to the constructor. Alternatively, you can use the Size class to specify the size in a more readable format. For example:

new FileSize(2, File::MB)
new FileSize(200, File::KB)

Enter fullscreen mode Exit fullscreen mode

Dimension

The Dimension class is used to validate the dimensions of images. You can specify the maximum width and height of the image by passing them as parameters to the constructor. For example:

new Dimension(200, 200)
Enter fullscreen mode Exit fullscreen mode

Targeted Validations

You can also target specific fields in your entity with a set of validations.
To do this, you can use the FieldValidations class, which takes the request field name as it's first parameter and an array of validation rules as its second parameter. Here's an example:

$profileValidations = new FieldValidations("profile_field", [
    new Dimension(200, 200),
    new FileSize(2, File::MB)
]);

Uploader::upload($product, [
    new FileType([File::PNG, File::JPEG, File::GIF]),
    $profileValidations,
]);
Enter fullscreen mode Exit fullscreen mode

In the example above, we are specifying a set of validation checks that apply to the profile field in the Product entity. These checks will only be applied to the profile image uploaded by the user.


Handling file uploads can be a complicated and error-prone task, but with this library, you can simplify the process and focus on building the features that matter. If you have any questions or feedback, feel free to reach out to the author on Twitter or LinkedIn.

Top comments (2)

Collapse
 
didslm profile image
diar.dev

new release

Image description

Collapse
 
didslm profile image
diar.dev

We are looking for contributors who want to make this library more solid and improove the experience.

github.com/didslm/file-upload-wrapper