Magento 2 System.xml Configuration: A Detailed Guide

Magento 2 offers extensive customization options, allowing developers to create custom configurations that can be managed via the admin panel. In this blog post, we’ll guide you through the process of creating system configurations in Magento 2 using system.xml and config.xml. Follow this step-by-step guide to add your own configuration fields in the Magento 2 admin panel.

Why Create Custom System Configurations?

1. Customization: Tailor the configuration settings to meet specific business needs.
2. Flexibility: Allow administrators to manage settings without modifying code.
3. Integration: Easily configure third-party integrations and custom modules.

Step-by-Step Guide to Creating System Configurations:

Step 1: Define System Configuration (system.xml)

Create the etc/adminhtml/system.xml file:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Config/etc/system_file.xsd">
    <system>
        <section id="custom_section" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Custom Configuration</label>
            <tab>general</tab>
            <resource>Vendor_Module::config</resource>
            <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>General Settings</label>
                <field id="enable" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Enable</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
                <field id="custom_text" translate="label" type="text" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Text</label>
                </field>
                <field id="custom_select" translate="label" type="select" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Select</label>
                    <source_model>Vendor\Module\Model\Config\Source\Options</source_model>
                </field>
                <field id="custom_multiselect" translate="label" type="multiselect" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Multi-Select</label>
                    <source_model>Vendor\Module\Model\Config\Source\Options</source_model>
                </field>
                <field id="custom_date" translate="label" type="date" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Date</label>
                </field>
                <field id="custom_file" translate="label" type="file" sortOrder="60" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom File</label>
                </field>
                <field id="custom_image" translate="label" type="image" sortOrder="70" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Image</label>
                </field>
                <field id="custom_password" translate="label" type="password" sortOrder="80" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Password</label>
                </field>
                <field id="custom_textarea" translate="label" type="textarea" sortOrder="90" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Custom Textarea</label>
                </field>
            </group>
        </section>
    </system>
</config>

Step 2: Define Default Configuration Values (config.xml)

Create the etc/config.xml file:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/config.xsd">
    <default>
        <custom_section>
            <general>
                <enable>1</enable>
                <custom_text>Default Text</custom_text>
                <custom_select>option1</custom_select>
                <custom_multiselect>option1,option2</custom_multiselect>
                <custom_date>2024-07-22</custom_date>
                <custom_file></custom_file>
                <custom_image></custom_image>
                <custom_password></custom_password>
                <custom_textarea>Default Text Area</custom_textarea>
            </general>
        </custom_section>
    </default>
</config>

Step 3: Create ACL Configuration (acl.xml)

To restrict access to your configuration section, create the etc/acl.xml file:

<?xml version="1.0"?>
<acl xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <resources>
        <resource id="Magento_Backend::admin">
            <resource id="Magento_Config::config">
                <resource id="Vendor_Module::config" title="Custom Configuration" sortOrder="50"/>
            </resource>
        </resource>
    </resources>
</acl>

Step 4: Create Source Model for Select Fields (Optional)

If you’re using custom source models for your select and multiselect fields, create the source model class. Here’s an example:

Create the Model/Config/Source/Options.php file:

<?php
namespace Vendor\Module\Model\Config\Source;

use Magento\Framework\Option\ArrayInterface;

class Options implements ArrayInterface
{
    public function toOptionArray()
    {
        return [
            ['value' => 'option1', 'label' => __('Option 1')],
            ['value' => 'option2', 'label' => __('Option 2')],
            ['value' => 'option3', 'label' => __('Option 3')],
        ];
    }

    public function toArray()
    {
        return [
            'option1' => __('Option 1'),
            'option2' => __('Option 2'),
            'option3' => __('Option 3'),
        ];
    }
}

Step 5: Verify and Test

Clear the cache and log in to the Magento admin panel. Navigate to:

Stores > Configuration > General > Custom Configuration

You should see your custom configuration fields under the “General Settings” group. Test by updating the values and verifying they are saved correctly.

Conclusion: Creating custom system configurations in Magento 2 allows you to provide administrators with the flexibility to manage settings directly from the admin panel. By following this step-by-step guide, you can easily add various types of configuration fields, making your Magento 2 module more versatile and user-friendly.