Steps to ADD Custom File Upload Control in Magento 2

Working with Magento sometimes require various file uploads to store and use in the extension. While using backend, you may need uploading for example CSV, to add data and use somewhere or validate data from frontend. And from frontend, you need file upload option to let users upload screenshots, images or any other input files you need to store and further use or process.

By defualt, Magento 2 accepts all kind of input types such as text, radio button, check box etc. and allows to extend default interface to add fields without any hassle. Here, I will share the custom code to add file upload control both the backend and frontend of Magento 2.

Backend:
Go to Stores > Configuration > Sales, create a new section custom_section, create a new group of fields custom_group, and create a file upload custom_file_upload with following code.

<section id="[vendor]_[modulename]_section" translate="label" type="text" sortOrder="301" showInDefault="1" showInWebsite="1" showInStore="0">
    <label>Sales</label>
    <tab>sales</tab>
    <resource>Magento_Sales::config_sales</resource> / <!-- for ACL - only administrators can access this section.-->
    <group id="custom_group" translate="label" type="text" sortOrder="6" showInDefault="1" showInWebsite="1" >
        <label>Custom group</label>
        <field id="custom_file_upload" translate="label" type="Magento\Config\Block\System\Config\Form\Field\File" sortOrder="6" showInDefault="1" showInWebsite="1" >
            <label>Upload custom file</label>
        </field>
    </group>
</section>

Here, Group in the code include the fields that permit you to upload the files as need. ID attribute points to the certain custom file upload and it is unique per group. And type attribute is set for the file type, if you want to allow uploading image, it should be replaced with image.
Even if you have got upload file option but it will still not work. to make them work,

• You need to set the upload folder, check allowed extensions, validate file size and save the file path to database. Default backend model for file upload is Magento\Config\Model\Config\Backend\File. Add upload_dir – upload directory to run the file.

<backend_model>Magento\Config\Model\Config\Backend\File</backend_model>
<upload_dir>pub/media/myupload</upload_dir>

• Magento 2 allows many types of files to upload but if you want to restrict some file types, to do the same go to system.xml file to be \[Vendor]\[ModuleName]\Model\Config\Backend\CustomFileType and put below code which allows only csv and xls file types. change the code as per your requirements.

<?php
 
namespace [Vendor]\[ModuleName]\Model\Config\Backend;
 
class CustomFileType extends \Magento\Config\Model\Config\Backend\File
{
    /**
     * @return string[]
     */
    public function getAllowedExtensions() {
        return ['csv', 'xls'];
    }
}

Frontend:
just as backend, same technique can be used to add file upload control in frontend.
Take a look at sample code to add a field to a form of type file:

<?php
 
$fieldset->addField(
    'title',
    'file',
    [
        'name' => 'file', // to add reference later in controller. 
        'label' => __('File label'),
        'required' => true
    ]
)

Implementing this code will have a form with an input type=”file” box from which you can select the file you want to upload and press “save”.
Now we will need to create a controller to handle the request in app/code/[Vendor]/[ModuleName]/Controller/[ControllerName].php

<?php
 
namespace [Vendor]\[ModuleName]\Controller;
 
use Magento\Backend\App\Action;
use Magento\Framework\App\Filesystem\DirectoryList;
use Magento\Framework\Exception\LocalizedException;
use Magento\Framework\Filesystem;
use Magento\MediaStorage\Model\File\UploaderFactory;
 
class [ControllerName] extends Action
{
    protected $fileSystem;
 
    protected $uploaderFactory;
 
    protected $allowedExtensions = ['csv']; // to allow file upload types 
 
    protected $fileId = 'file'; // name of the input file box  
 
    public function __construct(
        Action\Context $context,
        Filesystem $fileSystem,
        UploaderFactory $uploaderFactory
    ) {
        $this->fileSystem = $fileSystem;
        $this->uploaderFactory = $uploaderFactory;
        parent::__construct($context);
    }
 
    public function execute()
    {
        $destinationPath = $this->getDestinationPath();
 
        try {
            $uploader = $this->uploaderFactory->create(['fileId' => $this->fileId])
                ->setAllowCreateFolders(true)
                ->setAllowedExtensions($this->allowedExtensions)
                ->addValidateCallback('validate', $this, 'validateFile');
            if (!$uploader->save($destinationPath)) {
                throw new LocalizedException(
                    __('File cannot be saved to path: $1', $destinationPath)
                );
            }
 
            // @todo
            // process the uploaded file
        } catch (\Exception $e) {
            $this->messageManager->addError(
                __($e->getMessage())
            );
        }
    }
    
    public function validateFile($filePath)
    {
        // @todo
        // your custom validation code here
    }
 
    public function getDestinationPath()
    {
        return $this->fileSystem
            ->getDirectoryWrite(DirectoryList::TMP)
            ->getAbsolutePath('/');
    }
}

In the above code, Magento\Framework\File\Uploader model handles upload, validation and file saving.

File Uploads in System Configuration

While adding file upload control to the system configuration area of Magento, you just need to specify some configuration to give Magento a clue as to where the file should be uploaded.

<field id="file" translate="label comment" type="file" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>File</label>
    <upload_dir config="config/path">pub/media/myupload</upload_dir>
</field>

That’s it. Simply by adding few lines of code both in backend and frontend, you can easily create file upload control. Let me know where you have used this code and how it helped. Even feel free to ask if you have any questions in comment section, I would be glad to help.