← Назад к справке

Модули

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

Рабочая справка по настройкам локального модуля Bitrix: default_option.php, options.php, Option::get, Option::set и удаление настроек.

Настройки модуля лучше хранить через Bitrix\Main\Config\Option, а не в своих файлах. Так они будут доступны из админки и из кода.

Общее понимание

У модуля обычно есть значения по умолчанию и страница настроек в админке.

Где хранятся настройки

Настройки модуля хранятся в базе и читаются через Option::get(). Если значение не задано, можно передать значение по умолчанию.

default_option.php

Файл содержит значения по умолчанию. Название массива строится от ID модуля, где точка заменяется на подчёркивание. 

<?php

$test_example_default_option = [
    'is_enabled' => 'Y',
    'log_file' => '/local/logs/test_example.log',
    'default_limit' => '100',
];

options.php

options.php подключается в административной странице настроек модуля. В нём можно отрисовать форму и сохранить значения.

Чтение и запись

Для чтения и записи используется Bitrix\Main\Config\Option.

Получить настройку

<?php

use Bitrix\Main\Config\Option;

const MODULE_ID = 'test.example';

/**
 * Получает строковую настройку модуля.
 */
function fetchModuleOption(string $option_name, string $default_value = ''): string
{
    return (string) Option::get(
        MODULE_ID,
        $option_name,
        $default_value
    );
}

$log_file = fetchModuleOption('log_file', '/local/logs/test_example.log');

Сохранить настройку

<?php

use Bitrix\Main\Config\Option;

const MODULE_ID = 'test.example';

/**
 * Сохраняет настройку модуля.
 */
function saveModuleOption(string $option_name, string $option_value): void
{
    Option::set(
        MODULE_ID,
        $option_name,
        $option_value
    );
}

saveModuleOption('is_enabled', 'Y');

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

Чтобы не дублировать MODULE_ID и названия настроек по проекту, удобно сделать маленький сервис. 

<?php

namespace test\Example\Service;

use Bitrix\Main\Config\Option;

class OptionService
{
    public const MODULE_ID = 'test.example';
    public const OPTION_IS_ENABLED = 'is_enabled';
    public const OPTION_LOG_FILE = 'log_file';

    /**
     * Проверяет, включён ли модуль.
     */
    public function isEnabled(): bool
    {
        return Option::get(self::MODULE_ID, self::OPTION_IS_ENABLED, 'Y') === 'Y';
    }

    /**
     * Получает путь к лог-файлу.
     */
    public function getLogFile(): string
    {
        return (string) Option::get(
            self::MODULE_ID,
            self::OPTION_LOG_FILE,
            '/local/logs/test_example.log'
        );
    }

    /**
     * Сохраняет путь к лог-файлу.
     */
    public function saveLogFile(string $log_file): void
    {
        Option::set(self::MODULE_ID, self::OPTION_LOG_FILE, $log_file);
    }
}

Страница настроек

Пример простой страницы настроек для админки.

Пример options.php

<?php

use Bitrix\Main\Config\Option;
use Bitrix\Main\Context;
use Bitrix\Main\Localization\Loc;

defined('B_PROLOG_INCLUDED') || die();

const MODULE_ID = 'test.example';

$request = Context::getCurrent()->getRequest();

if (
    $request->isPost()
    && check_bitrix_sessid()
    && (string) $request->getPost('save') !== ''
) {
    Option::set(MODULE_ID, 'is_enabled', $request->getPost('is_enabled') === 'Y' ? 'Y' : 'N');
    Option::set(MODULE_ID, 'log_file', trim((string) $request->getPost('log_file')));
}

$is_enabled = Option::get(MODULE_ID, 'is_enabled', 'Y');
$log_file = Option::get(MODULE_ID, 'log_file', '/local/logs/test_example.log');

$aTabs = [
    [
        'DIV' => 'settings',
        'TAB' => 'Настройки',
        'TITLE' => 'Настройки модуля',
    ],
];

$tab_control = new CAdminTabControl('tabControl', $aTabs);
?>

<form method="post" action="<?= $APPLICATION->GetCurPage() ?>?mid=<?= urlencode(MODULE_ID) ?>&lang=<?= LANGUAGE_ID ?>">
    <?= bitrix_sessid_post() ?>

    <?php $tab_control->Begin(); ?>
    <?php $tab_control->BeginNextTab(); ?>

    <tr>
        <td width="40%">Модуль включён</td>
        <td width="60%">
            <input type="checkbox" name="is_enabled" value="Y" <?= $is_enabled === 'Y' ? 'checked' : '' ?>>
        </td>
    </tr>

    <tr>
        <td>Файл лога</td>
        <td>
            <input type="text" name="log_file" value="<?= htmlspecialcharsbx($log_file) ?>" size="50">
        </td>
    </tr>

    <?php $tab_control->Buttons(); ?>

    <input type="submit" name="save" value="Сохранить" class="adm-btn-save">

    <?php $tab_control->End(); ?>
</form>

Удаление настроек

При удалении модуля можно удалить его настройки. Но если модуль переустанавливают, иногда настройки полезно оставить. 

<?php

use Bitrix\Main\Config\Option;

const MODULE_ID = 'test.example';

/**
 * Удаляет все настройки модуля.
 */
function deleteModuleOptions(): void
{
    Option::delete(MODULE_ID);
}

deleteModuleOptions();

Источники