Magento 2 system configuration

Magento 2 system configuration

System configuration is a simple way to store single values required for application functionality in both Magento 1 and 2. In this post we will show you how to add custom system configuration settings in Magento 2.

System configuration values in Magento 2 are stored in the core_config_data database table, which is exactly the same as in Magento 1. But the xml config files differ.

First of all, we will need to declare ACL for the config in our extension:

<?xml version="1.0"?>
<!--
/**
 * Location: magento2_root/app/code/Vendorname/Extensionname/etc/acl.xml
 */
-->
<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="Vendorname_Extensionname::config" title="Extension config example" sortOrder="50" />
                        </resource>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

After that we are ready to add our extension config file:

<?xml version="1.0"?>
<!--
/**
 * Location: magento2_root/app/code/Vendorname/Extensionname/etc/adminhtml/system.xml
 */
-->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Config:etc/system_file.xsd">
    <system>
        <tab id="example_tab" translate="label" sortOrder="1000">
            <label>Example tab config</label>
        </tab>
        <section id="example_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Example config section</label>
            <tab>example_tab</tab>
            <resource>Vendorname_Extensionname::config</resource>
            <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                <label>General</label>
                <field id="dropdown_example" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Dropdown with custom source model example</label>
                    <source_model>Vendorname\Extensionname\Model\Config\Source\Custom</source_model>
                </field>
                <field id="text_example" translate="label" type="text" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Text example</label>
                </field>
                <field id="logo" translate="label" type="image" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Image example (with a comment)</label>
                    <backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
                    <upload_dir config="system/filesystem/media" scope_info="1">logo</upload_dir>
                    <base_url type="media" scope_info="1">logo</base_url>
                    <comment><![CDATA[Allowed file types: jpeg, gif, png.]]></comment>
                </field>
                <field id="depends_example" translate="label" type="text" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Dependant text field example with validation</label>
                    <depends>
                        <field id="*/*/dropdown_example">1</field>
                    </depends>
                    <validate>validate-no-empty</validate>
                </field>
                <field id="textarea_example" translate="label" type="textarea" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Textarea example</label>
                </field>
            </group>
        </section>
    </system>
</config>

With system.xml file we will add custom config tab “Example tab config” and one group of config fields within. Let’s check this file closer.

This is how we declare our tab:

<tab id="example_tab" translate="label" sortOrder="1000">
    <label>Example tab config</label>
</tab>

And our config section that belongs to this tab (with “<tab>” tag) has only one group of fields (<group id=”general”>) and acl relation (“<resource>” tag):

<section id="example_section" translate="label" type="text" sortOrder="100" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Example config section</label>
    <tab>example_tab</tab>
    <resource>Vendorname_Extensionname::config</resource>
    <group id="general" translate="label" type="text" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
        <label>General</label>
        ......................
    </group>
</section>

First of our fields is a dropdown with a custom source model:

<field id="dropdown_example" translate="label" type="select" sortOrder="10" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Dropdown with custom source model example</label>
    <source_model>Vendorname\Extensionname\Model\Config\Source\Custom</source_model>
</field>

So, we will need to create that source model:

<?php

//Location: magento2_root/app/code/Vendorname/Extensionname/Model/Config/Source/Custom.php
namespace Vendorname\Extensionname\Model\Config\Source;

class Custom implements \Magento\Framework\Option\ArrayInterface
{
    /**
     * @return array
     */
    public function toOptionArray()
    {

        return [
            ['value' => 0, 'label' => __('Zero')],
            ['value' => 1, 'label' => __('One')],
            ['value' => 2, 'label' => __('Two')],
        ];
    }
}

The second example config is a simple text field:

<field id="text_example" translate="label" type="text" sortOrder="20" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Text example</label>
</field>

Next field is far more interesting – a ready image file upload field. It is using a built-in backend model, and accepts an upload_dir param for file saving. It also has a comment example:

<field id="logo" translate="label" type="image" sortOrder="30" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Image example (with a comment)</label>
    <backend_model>Magento\Config\Model\Config\Backend\Image</backend_model>
    <upload_dir config="system/filesystem/media" scope_info="1">logo</upload_dir>
    <base_url type="media" scope_info="1">logo</base_url>
    <comment><![CDATA[Allowed file types: jpeg, gif, png.]]></comment>
</field>

Next config will appear only if value 1 (with label “One”) is selected in our example drowpdown. That behaviour was made possible with “<depends>” tag. Also, this dropdown has a validation class, specified in the “<validation>” tag:

<field id="depends_example" translate="label" type="text" sortOrder="40" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Dependant text field example with validation</label>
    <depends>
        <field id="*/*/dropdown_example">1</field>
    </depends>
    <validate>validate-no-empty</validate>
</field>

The last one is a simple textarea example:

<field id="textarea_example" translate="label" type="textarea" sortOrder="50" showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Textarea example</label>
</field>

Putting together everything mentioned above will give us this view (Admin Panel > Stores > Configuration):

2016-03-22_1937

Most of the source models are located in magento2_root/app/code/Magento/Config/Model/Config/Source and backend models are located in magento2_root/app/code/Magento/Config/Model/Config/Backend.

It would also be useful to check possible validation classes in magento2_root/lib/web/mage/validation.js under the rule variable (e.g. alphanumeric, zip-range, validate-email etc.)

We hope, this information will save you some time in your everyday growing Magento 2 development effort. Thanks for reading!

You may also want to read:

Clients

Smart Brands Choose Us.

From Mark Cuban and Sir Richard Branson backed startups, to Inc 500 US Fastest Growing Companies and Global Brands choose us to deliver and support unparalleled eСommerce experience for their customers.