How to add Magento 2 system configuration fields

To add custom Magento 2 system configuration fields to the backend, enabling store administrators to adjust specific module settings, you’ll need to use a system.xml file in your module’s etc/adminhtml directory. This setup is somewhat similar to Magento 1, but there are key differences.

When This is Useful

Adding custom system configuration fields is especially relevant if:

You are developing a Magento 2 module
You want to allow administrators to configure module-specific options in the backend

These configuration values are stored in the core_config_data table, similar to Magento 1.

Example: FTP Connection Fields
To illustrate, consider adding fields that allow administrators to input FTP details. You might create fields for:

Server: a domain or IP address for the FTP server
User: the FTP username
Password: the password, stored in a secure format
Path: the directory path for file import

These fields are necessary to enable the module to retrieve files from an external FTP server.

Step 1: Access Control List (ACL)
To control access, create an acl.xml file in the etc folder of your module and add a role resource for your module’s system configuration. Here’s an example structure:

				
					<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Magento_Backend::stores">
                    <resource id="Magento_Backend::stores_settings">
                        <resource id="Magento_Config::config">
                            <resource id="Abbas_Acl::config" title="Custom Title" sortOrder="50" />
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>

Step 2: Define System Configuration Fields in system.xml
In the system.xml file, create a new tab, section, and group for your fields. Here’s an example structure:

				
					<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="acl_tab" translate="label" sortOrder="1000">
            <label>Custom Label</label>
        </tab>
        <section id="module_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Module Settings</label>
            <tab>custom_tab</tab>
            <resource>Abbas_Acl::config</resource>
            <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>General Settings</label>
                <field id="ftp_server" translate="label" type="text" sortOrder="20" showInDefault="1">
                    <label>Server</label>
                </field>
                <field id="ftp_user" translate="label" type="text" sortOrder="20" showInDefault="1">
                    <label>User</label>
                </field>
                <field id="ftp_password" translate="label" type="password" sortOrder="20" showInDefault="1">
                    <label>Password</label>
                </field>
                <field id="ftp_path" translate="label" type="text" sortOrder="20" showInDefault="1">
                    <label>Directory</label>
                </field>
            </group>
        </section>
    </system>
</config>

Key Attributes

Each field requires a label and several attributes:

id: a unique identifier to access this field’s value
type: field type (text for standard input, password for secure entries)
showInDefault, showInWebsite, showInStore: determines if the field appears in the specified configuration scope

By setting up system configuration fields in this way, you enable easy configuration management for administrators and modular control over your Magento 2 setup.

Mohamed Abbas

Technical Lead | Magento Architect