Magento 2 System Configuration

⚙️ Magento 2 System Configuration – Add Custom Admin Settings

Ever wanted to allow the admin to set API keys, enable features, or define values from the Magento backend? With System Configuration, you can easily create custom settings under Stores > Configuration.

🎯 What We’ll Build

We’ll add a new configuration section called “Vendor Settings” with a group called “General Settings” and fields for an API Key and Enable toggle.

📂 Folder Structure

app/code/Vendor/Module/
├── etc/adminhtml/system.xml
├── etc/config.xml
├── registration.php, module.xml

🔧 Step 1: Define system.xml

This defines what appears in the Stores > Configuration panel.


<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">

    <system>
        <section id="vendor_section" translate="label" sortOrder="300" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Vendor Settings</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 Feature</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>

                <field id="api_key" translate="label" type="text" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>API Key</label>
                </field>

            </group>
        </section>
    </system>

</config>

Try It Now

📦 Step 2: Set Default Values (config.xml)


<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:App/etc/config.xsd">

    <default>
        <vendor_section>
            <general>
                <enable>1</enable>
                <api_key>test1234</api_key>
            </general>
        </vendor_section>
    </default>

</config>

Try It Now

🧪 Step 3: Access Config Values in Code

You can retrieve saved values using the ScopeConfigInterface:

/* Get config values from Store Configuration */
$apiKey = $this->scopeConfig->getValue('vendor_section/general/api_key', \Magento\Store\Model\ScopeInterface::SCOPE_STORE);
$isEnabled = $this->scopeConfig->isSetFlag('vendor_section/general/enable', \Magento\Store\Model\ScopeInterface::SCOPE_STORE);

Try It Now

🔐 Step 4: Add ACL Resource (Optional)

In acl.xml (if using custom roles):

<resource id="Vendor_Module::config" title="Vendor Settings" sortOrder="10" />

Try It Now

✅ Summary

  • Add system.xml to define admin fields under Stores > Configuration
  • Use config.xml to set default values
  • Fetch values using ScopeConfigInterface
  • Add ACL for permission-based access (optional)

That’s it! You’ve now added a fully working system config section to Magento 2. Perfect for custom modules with configurable behavior!