system.xml Deep Dive

system.xml follows a three-level hierarchy: Section → Group → Field.

Complete section example:

<?xml version="1.0"?>
<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_shipping" type="text" sortOrder="300"
                 showInDefault="1" showInWebsite="1" showInStore="0">
            <label>Vendor Shipping</label>
            <tab>sales</tab>
            
            <group id="general" type="text" sortOrder="10"
                    showInDefault="1" showInWebsite="1" showInStore="0">
                <label>General Settings</label>
                
                <field id="enabled" type="select" sortOrder="10"
                       showInDefault="1" showInWebsite="1" showInStore="0">
                    <label>Enable Module</label>
                    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
                </field>
            </group>
            
            <group id="rates" type="text" sortOrder="20"
                    showInDefault="1" showInWebsite="0" showInStore="0">
                <label>Shipping Rates</label>
                
                <field id="flat_rate" type="price" sortOrder="10"
                       showInDefault="1" showInWebsite="0" showInStore="0">
                    <label>Flat Rate Fee</label>
                    <backend_model>Magento\Config\Model\Config\Backend\Price</backend_model>
                </field>
            </group>
        </section>
    </system>
</config>

Hierarchy levels:

Section (id="vendor_shipping")
├── Group (id="general")
│   ├── Field (id="enabled")
│   └── Field (id="title")
└── Group (id="rates")
    ├── Field (id="flat_rate")
    └── Field (id="free_threshold")

system.xml supports various field types for different input needs.

Text field:

<field id="api_key" type="text" sortOrder="10" showInDefault="1">
    <label>API Key</label>
    <validate>required-entry</validate>
</field>

Boolean (Yes/No):

<field id="enabled" type="select" sortOrder="10" showInDefault="1">
    <label>Enable Module</label>
    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
</field>

Select (dropdown):

<field id="shipping_method" type="select" sortOrder="20" showInDefault="1">
    <label>Default Method</label>
    <source_model>Vendor\Module\Model\Config\Source\ShippingMethods</source_model>
</field>

Multiselect:

<field id="allowed_countries" type="multiselect" sortOrder="30" showInDefault="1">
    <label>Allowed Countries</label>
    <source_model>Magento\Directory\Model\Config\Source\Country</source_model>
    <backend_model>Magento\Config\Model\Config\Backend\Serialized\ArraySerialized</backend_model>
</field>

Textarea:

<field id="custom_css" type="textarea" sortOrder="40" showInDefault="1">
    <label>Custom CSS</label>
    <backend_model>Magento\Config\Model\Config\Backend\Textarea</backend_model>
</field>

Image upload:

<field id="logo_image" type="image" sortOrder="50" showInDefault="1">
    <label>Logo Image</label>
    <backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
    <upload_dir>vendor/logo</upload_dir>
</field>

Obscure (password-like):

<field id="secret_key" type="obscure" sortOrder="60" showInDefault="1">
    <label>Secret Key</label>
    <backend_model>Magento\Config\Model\Config\Backend\Encrypted</backend_model>
</field>

Price:

<field id="handling_fee" type="price" sortOrder="70" showInDefault="1">
    <label>Handling Fee</label>
    <backend_model>Magento\Config\Model\Config\Backend\Price</backend_model>
</field>

Backend models handle save logic, validation, and data processing for configuration values.

Custom backend model:

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

class ApiKey extends \Magento\Config\Model\Config\Backend\AbstractBackend
{
    public function afterSave(): void
    {
        $value = $this->getValue();
        
        // Validate API key format
        if (!preg_match('/^[A-Za-z0-9]{32}$/', $value)) {
            throw new \Magento\Framework\Exception\LocalizedException(
                __('API Key must be 32 alphanumeric characters')
            );
        }
        
        // Process after save
        $this->cacheClean();
    }
    
    public function beforeSave(): void
    {
        $value = $this->getValue();
        
        // Trim whitespace
        $this->setValue(trim($value));
    }
    
    private function cacheClean(): void
    {
        // Clear relevant cache
    }
}

Backend model in system.xml:

<field id="api_key" type="obscure" sortOrder="20" showInDefault="1">
    <label>API Key</label>
    <backend_model>Vendor\Module\Model\Config\Backend\ApiKey</backend_model>
</field>

Built-in backend models:

Backend model lifecycle:

1. User submits config form
2. beforeSave() called
3. Value validated
4. afterSave() called
5. Value stored in core_config_data

Source models provide options for select and multiselect fields.

Custom source model:

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

class ShippingMethods implements \Magento\Framework\Option\ArrayInterface
{
    public function toOptionArray(): array
    {
        return [
            ['value' => 'flat', 'label' => __('Flat Rate')],
            ['value' => 'free', 'label' => __('Free Shipping')],
            ['value' => 'table', 'label' => __('Table Rates')],
        ];
    }
}

Source model in system.xml:

<field id="shipping_method" type="select" sortOrder="20" showInDefault="1">
    <label>Default Method</label>
    <source_model>Vendor\Module\Model\Config\Source\ShippingMethods</source_model>
</field>

Dynamic source model (from database):

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

class Countries implements \Magento\Framework\Option\ArrayInterface
{
    public function __construct(
        private \Magento\Directory\Model\ResourceModel\Country\CollectionFactory $countryCollection
    ) {}
    
    public function toOptionArray(): array
    {
        $countries = $this->countryCollection->create()->loadByStore();
        $options = [];
        
        foreach ($countries as $country) {
            $options[] = [
                'value' => $country->getId(),
                'label' => $country->getName()
            ];
        }
        
        return $options;
    }
}

Built-in source models:

Validation rules:

<!-- required-entry: Must have value -->
<validate>required-entry</validate>

<!-- validate-email: Must be valid email -->
<validate>validate-email</validate>

<!-- validate-url: Must be valid URL -->
<validate>validate-url</validate>

<!-- validate-number: Must be numeric -->
<validate>validate-number</validate>

<!-- Multiple validations -->
<validate>required-entry validate-number validate-digits</validate>