Настройки модуля

У модуля почти всегда есть настройки: включён ли он, какой текст показывать, сколько записей выводить. В Magento их не хранят в коде: поля описывают в файле XML, они появляются в панели управления, а администратор задаёт значения — при желании отдельно для каждой витрины.

Где лежат файлы

Файл	Что описывает
`etc/adminhtml/system.xml`	Поля в панели управления
`etc/config.xml`	Значения по умолчанию

Оба файла создают вручную.

app/code/Acme/Hello/
├── Model/
│   └── Config.php              новый файл
└── etc/
    ├── adminhtml/
    │   └── system.xml          новый файл
    ├── config.xml              новый файл
    └── module.xml

Поле настройки

<?xml version="1.0"?>
<!-- app/code/Acme/Hello/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>
        <section id="acme_hello" translate="label" sortOrder="900"
                 showInDefault="1" showInWebsite="1" showInStore="1">
            <label>Hello</label>
            <tab>general</tab>
            <resource>Magento_Config::config</resource>
 
            <group id="general" translate="label" sortOrder="10"
                   showInDefault="1" showInWebsite="1" showInStore="1">
                <label>Основные настройки</label>
 
                <field id="greeting" translate="label" type="text" sortOrder="10"
                       showInDefault="1" showInWebsite="1" showInStore="1">
                    <label>Текст приветствия</label>
                </field>
            </group>
        </section>
    </system>
</config>

Выполните bin/magento cache:clean и откройте в панели «Магазины → Конфигурация → Общие → Hello» (Stores → Configuration → General → Hello). Там появится группа с одним текстовым полем.

Настройки образуют три уровня: раздел (section), группа (group), поле (field). Из их идентификаторов складывается путь к значению: acme_hello/general/greeting. Тег resource называет право доступа; своё право появится в следующем уроке.

Значение по умолчанию

<?xml version="1.0"?>
<!-- app/code/Acme/Hello/etc/config.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Store:etc/config.xsd">
    <default>
        <acme_hello>
            <general>
                <greeting>Добро пожаловать!</greeting>
            </general>
        </acme_hello>
    </default>
</config>

Вложенность тегов повторяет путь настройки. Пока администратор не сохранил своё значение, действует это.

Чтение в коде

Настройки читает ScopeConfigInterface. Удобно собрать все обращения в одном классе:

// app/code/Acme/Hello/Model/Config.php
namespace Acme\Hello\Model;
 
use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Store\Model\ScopeInterface;
 
class Config
{
    public function __construct(private ScopeConfigInterface $scopeConfig) {}
 
    public function getGreeting(): string
    {
        return (string) $this->scopeConfig->getValue('acme_hello/general/greeting', ScopeInterface::SCOPE_STORE);
    }
}

Добавьте Config в конструктор модели представления Greeting и выведите getGreeting() в шаблоне: на странице /hello появится «Добро пожаловать!». Измените значение в панели, сохраните — текст на странице изменится.

Уровни настроек

Уровень	Для чего
Общий (`default`)	Значение для всей установки
Сайт (`website`)	Значение для одного сайта
Витрина (`store view`)	Значение для одного языка

Значение на нижнем уровне перекрывает верхнее. Константа SCOPE_STORE во втором аргументе означает «для текущей витрины»: Magento вернёт её значение, а если оно не задано — значение сайта или общее. Атрибуты showInDefault, showInWebsite, showInStore определяют, на каких уровнях поле видно в панели.

Выключатель и зависимые поля

<!-- app/code/Acme/Hello/etc/adminhtml/system.xml -->
<field id="enabled" translate="label" type="select" sortOrder="5"
       showInDefault="1" showInWebsite="1" showInStore="1">
    <label>Включено</label>
    <source_model>Magento\Config\Model\Config\Source\Yesno</source_model>
</field>

Поле типа select берёт варианты из класса source_model; здесь это «Да» и «Нет». В коде такой выключатель читают методом isSetFlag() с теми же аргументами — он возвращает true или false. Чтобы поле показывалось только при включённом модуле, в него добавляют тег depends с вложенным field id="enabled" и значением 1.

Настройки из консоли

bin/magento config:set acme_hello/general/greeting "Добрый день!"
bin/magento config:show acme_hello/general/greeting

Первая команда сохраняет значение, вторая печатает его.

Частая ошибка

Значение изменили, а страница показывает старое. Настройки кешируются: после правки config.xml, system.xml или прямого изменения таблицы core_config_data выполните bin/magento cache:clean config. При сохранении в панели Magento сам напомнит о кеше сообщением вверху страницы.

Спасибо, что читаете!