Magento 2 File Upload in System Configuration
Vinh Jacker | 12-18-2024

In Magento 2, uploading files through the system configuration is straightforward using the admin interface. The platform supports various input types, including text fields, radio buttons, dropdowns, and multi-selects, which can be plain, encrypted, or serialized. These inputs are displayed in different formats, such as grids, forms, fields, or images. Supported file types include XML, PHP, JPG, CSV, DOCX, and XLS. Additionally, Magento allows you to extend the default interface, enabling you to add custom fields as needed. Now, let’s read on for detailed instructions.
How to upload the file in Magento 2 store configuration
Step 1: Create system.xml file.
Follow the path Store > Configuration
, under Sales
section, you can create a new section custom_section
, create a new group of fields custom_group
, and create a file upload custom_file_upload
by adding the system.xml
file in your module
Apply the following code snippet. File path: app/code/Mageplaza/HelloWorld/etc/adminhtml/system.xml
<section id="mageplaza_helloworld_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>
<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>
In the above script, there are some of points you need to know what they are. Firstly, Section
fields are self-explanatory while tab is the exact place for the section, sales tab is set from Magento_Sales::etc/adminhtml/system.xml file
, and resource will be applied for ACL. However, remember that only administrators with Magento_Sales::config_sales
possibly access this section.
Next,Group
in the script code requires will include the fields that permit you to upload the files as need. The group contains id and type attributes. id points to a certain custom file upload, but it is surely unique per group. And type is set to Magento\Config\Block\System\Config\Form\Field\File
, but if you want to upload image, remember the type Magento\Config\Block\System\Config\Form\Field\Image
.
Finally, although you get an uploaded file, it still does not work. Two things are suggested for you as the below.
- In this backend module, you should set the upload directory, 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
. Then let’s add<upload_dir>
– upload directory to run the file.
<backend_model>Magento\Config\Model\Config\Backend\File</backend_model>
<upload_dir>upload</upload_dir>
From the application root, the file upload will be put in magento_root/upload/
. However, when you insert a scope_info=”1″ to the upload directory, the file upload will be saved into the place which is based on the scope. If you apply the default scope, the file will be in magento_root/upload/default
. Website 1 would give us magento_root/upload/websites/1/
etc. Run the configuration to clear all:
<section id="mageplaza_helloworld_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>
<group id="custom_group" translate="label" type="text" sortOrder="6" showInDefault="1" showInWebsite="1" >
<label>Security</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>
<backend_model>Magento\Config\Model\Config\Backend\File</backend_model>
<upload_dir config="system" scope_info="1">test</upload_dir>
</field>
</group>
</section>
- Apart from the backend model, you can refer to other options like frontend_model (e.g. for a custom “drag and drop” file upload ), comment, tooltip, hint, validations, etc.
When uploading the file in the Magento 2 store configuration, many types of files are accepted. But it is unallowed if you want to limit it. In order to do, in system.xml
file to be \Mageplaza\HelloWorld\Model\Config\Backend\CustomFileType
, please take a look at the following example that only includes csv
and xls
thanks to the function getAllowedExtensions()
.
<?php
namespace Mageplaza\HelloWorld\Model\Config\Backend;
class CustomFileType extends \Magento\Config\Model\Config\Backend\File
{
/**
* @return string[]
*/
public function getAllowedExtensions() {
return ['csv', 'xls'];
}
}
Step 2: Flush Cache and check result
Flush Magento cache and check your result.
Manage file upload errors
- Use try-catch blocks to detect and handle exceptions.
- Check for common issues like file size limits and invalid file types.
- Display clear error messages when an upload fails.
- Log errors for admin review and troubleshooting.
Protect file uploads in Magento 2
Verify file type
- Utilize Magento’s built-in file validation mechanisms
- Develop a custom function to verify allowed file extensions
- Implement MIME-type validation for added security
- Use the Magento 2 Product Attachments extension for enhanced validation features
Restrict file access
- Store uploaded files in a private, non-public directory
- Set access controls to restrict file visibility
- Use Magento’s permission system to manage file access
- Develop a custom controller to securely serve files
Upload files faster with Mageplaza’s Product Attachment
Mageplaza offers you a more convenient and faster way to upload files with the Product Attachment extension. The Product Attachments module supports admins to upload many types of files and an unlimited number of attachments for each product. This is a great tool helping your store better than ever.
You can see detailed instructions for installing the extension and then easily upload files right here.
FAQs
How do I start to set up a file upload control in Magento 2?
To configure a file upload control in Magento 2, start by creating a new module. Set up the basic structure by adding the registration.php
and module.xml
files, which serve as the foundation for further configuration.
What file types can be uploaded in the default Magento setup?
By default, Magento allows uploading image files, PDFs, and other document types. You can customize the allowed file types by adjusting the uploader configuration.
How can I upload multiple files using Magento 2 extensions?
To upload multiple files, customize your module to support multiple file inputs. This requires modifying system.xml
and creating a custom form with multiple file input fields.
What code is required to enable file uploads in Magento 2?
To enable file uploads, use two key classes: Magento\Framework\FileSystem for managing file storage locations and Magento\MediaStorage\Model\File\UploaderFactory for handling the upload process.
How does the Mageplaza Product Attachment extension help improve SEO?
Product attachments enhance SEO by offering valuable content, such as user manuals and demo videos, which encourage visitors to stay longer and reduce bounce rates. Additionally, optimizing file names and descriptions with relevant keywords improves keyword relevance, boosting visibility in search results.
Final words
We hope this guide has helped you successfully implement file uploads in your Magento 2 system configuration. For further assistance, please consult our documentation, contact our support team, or simply use the comment section below!
Related Post