Configuration Management API Cotonti — детальный обзор и справочник

Опубликовано в: Cotonti - чтиво. Документация.

Файл: system/configuration.php

Настоящий документ - свод анализа исходного кода файла configuration.php: объявлений констант, сигнатур функций, PHPDoc-комментариев, содержимого примеров внутри блоков <code> и фактической логики операторов. Никакие внешние предположения не используются.

Содержание

Часть I. Обзор файла

1.1. Назначение и место в системе

Файл объявлен как Configuration Management API. Сразу после PHPDoc-заголовка стоит проверка defined('COT_CODE') or die('Wrong URL'); — это означает, что файл подключается только из ядра Cotonti и не может быть запущен напрямую через браузер.

По составу файл решает три группы задач:

Объявление констант типов конфигурации. Девять констант с префиксом COT_CONFIG_TYPE_ задают допустимые способы отображения и обработки значений параметров.
Управление записями конфигурации в базе данных. Набор функций с префиксом cot_config_ выполняет полный CRUD-цикл: регистрация (add), чтение (load, list), изменение свойств (modify), изменение значений (set), удаление (remove), сброс (reset), синхронизация (update).
Вспомогательные операции. Импорт значений из формы (import), сохранение отфильтрованного списка (update_options), генерация HTML-поля (input), получение заголовков и подписей (titles, selecttitles).

Отдельно выделяются два специальных механизма:

имплантация — расширение-донор добавляет свои параметры в конфигурацию модуля-акцептора;
конфигурация на уровне категорий — параметр config_subcat позволяет хранить разные значения одного и того же параметра для разных категорий модуля; специальное значение __default используется как значение по умолчанию для всех категорий.

1.2. Структура файла

Файл состоит из последовательных блоков:

PHPDoc-заголовок и защита COT_CODE.
Девять констант COT_CONFIG_TYPE_*, каждая — с отдельным комментарием.
Функция cot_config_type_int() — пример генератора поля ввода для целого числа.
Функция cot_config_type_int_filter() — пример фильтра значения.
Функция cot_config_add() — регистрация опций.
Функция cot_config_implant() — имплантация опций.
Функция cot_config_implanted() — проверка наличия имплантации.
Функция cot_config_load() — чтение списка опций без скрытых.
Функция cot_config_modify() — обновление служебных свойств.
Функция cot_config_parse() — разбор setup-строк.
Функция cot_config_remove() — удаление опций.
Функция cot_config_set() — обновление значений.
Функция cot_config_update() — синхронизация карты конфигурации.
Функция cot_config_reset() — сброс значения к config_default.
Функция cot_config_list() — чтение конфигурации для отображения.
Функция cot_config_import() — импорт значений из внешнего источника.
Функция cot_config_update_options() — сохранение отфильтрованных значений.
Функция cot_config_input() — генерация HTML-поля по типу.
Функция cot_config_titles() — получение заголовка и подсказки.
Функция cot_config_selecttitles() — получение подписей для значений.

1.3. Константы типов конфигурации

Все константы объявлены через const (без модификатора видимости), имеют целочисленные значения и сопровождаются комментариями. Ниже приведены определения из файла.

COT_CONFIG_TYPE_TEXT = 0

Общий текст. Отображается как textarea. Используется по умолчанию, если тип не распознан при парсинге.

COT_CONFIG_TYPE_STRING = 1

Строка длиной до 255 символов. Отображается как однострочное поле. Список вариантов для этого типа игнорируется.

COT_CONFIG_TYPE_SELECT = 2

Выбор из списка возможных вариантов. Отображается как выпадающий список.

COT_CONFIG_TYPE_RADIO = 3

Переключатель «да/нет».

COT_CONFIG_TYPE_CALLBACK = 4

Тип, использующий callback-функцию для формирования списка значений.

COT_CONFIG_TYPE_HIDDEN = 5

Скрытая конфигурация. Фактически строка, но нигде не отображается.

COT_CONFIG_TYPE_SEPARATOR = 6

Визуальный разделитель / fieldset. Значения не имеет.

COT_CONFIG_TYPE_RANGE = 7

Целочисленный диапазон.

COT_CONFIG_TYPE_CUSTOM = 8

Пользовательский тип.

1.4. Основные понятия и термины

Конфигурационная запись (config)

Строка в таблице конфигурации, описывающая один параметр расширения. Хранит имя, тип, текущее значение, значение по умолчанию, список вариантов, порядок, текст, владельца, категорию и донора.

Владелец (owner)

Одно из значений: 'core', 'plug', 'module'. Соответствует полю config_owner.

Расширение (cat)

Код расширения — например, page, forums. Для core может обозначать подтип — menus, main, performance. Соответствует полю config_cat.

Категория (subcat)

Код категории структуры. Соответствует полю config_subcat. Позволяет хранить разные значения одного параметра для разных категорий.

__default

Специальное значение config_subcat: значение по умолчанию для всех категорий. Переопределяется значениями конкретных категорий.

Донор (donor)

Расширение, имплантировавшее свои параметры в конфигурацию другого расширения. Соответствует полю config_donor.

Акцептор (acceptor)

Расширение, в конфигурацию которого имплантируются параметры донора.

Имплантация (implant)

Однократное добавление параметров донора в конфигурацию акцептора. Повторный вызов не создаёт дублей.

Callback-параметры

Аргументы, передаваемые функции через поле config_variants в формате function_name(params). Кавычки (одинарные и двойные) удаляются перед вызовом.

Фильтр (filter)

Функция или встроенный тип, применяемый к значению при импорте. Встроенные: INT, BOL, PSW, ALP, TXT, NUM.

Скрытая конфигурация

Параметр типа COT_CONFIG_TYPE_HIDDEN. Не отображается в интерфейсе, но хранится в БД. Не удаляется при синхронизации cot_config_update().

Разделитель

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

1.5. Модель данных конфигурации

Из состава полей, записываемых функцией cot_config_add(), следует, что модель данных конфигурации включает следующие атрибуты:

config_owner — владелец (core, plug, module);
config_cat — код расширения;
config_subcat — код категории (__default для значений по умолчанию);
config_order — позиция параметра в списке;
config_name — имя параметра (латиница, цифры, подчёркивание);
config_type — одна из констант COT_CONFIG_TYPE_*;
config_value — текущее значение;
config_default — значение по умолчанию;
config_variants — список возможных значений (для SELECT) или выражение function_name(params) (для CUSTOM/CALLBACK/RANGE);
config_text — текстовое описание;
config_donor — имя расширения-донора (при имплантации).

Значения полей config_value и config_default при регистрации устанавливаются одинаково — из ключа default входного массива опций, либо пустой строкой.

Часть II. Механизмы и сценарии

2.1. Регистрация конфигурации

Регистрация выполняется функцией cot_config_add(). На вход подаётся имя расширения, массив опций, признак модуля/плагина и (опционально) категория и донор.

Пример из PHPDoc-комментария к cot_config_add():

$config_options = [
    [
        'name' => 'disable_test',
        'type' => COT_CONFIG_TYPE_RADIO,
        'default' => '0'
    ],
    [
        'name' => 'test_selection',
        'type' => COT_CONFIG_TYPE_SELECT,
        'default' => '20',
        'variants' => '5,10,15,20,25,30,35,40,50'
    ],
    [
        'name' => 'test_value',
        'type' => COT_CONFIG_TYPE_STRING,
        'default' => 'something'
    ],
    [
        'name' => 'not_visible',
        'type' => COT_CONFIG_TYPE_HIDDEN,
        'default' => 'test23'
    ]
];

cot_config_add('test', $config_options, 'module');

Из примера видно:

name — имя параметра, уникальное в пределах расширения;
type — одна из констант COT_CONFIG_TYPE_*;
default — значение по умолчанию, записываемое и в config_value, и в config_default;
variants — список значений для COT_CONFIG_TYPE_SELECT, разделённый запятыми без пробелов;
order — необязательный, при отсутствии присваивается автоматически;
text — необязательный, обычно хранится в языковых файлах.

Третий аргумент 'module' — строка. Функция определяет тип владельца так: если строка не входит в ['plug', 'core'], она трактуется как 'module'. Если бы был передан булев true, владельцем стал бы 'module'; булев false — 'plug'.

Возврат: true, если число фактически вставленных записей равно количеству переданных опций. Иначе — false.

2.2. Чтение конфигурации

Для чтения используются две функции:

cot_config_load() — возвращает список опций без скрытых, без объединения значений по умолчанию и категорий. Используется при внутренних операциях (например, при синхронизации).
cot_config_list() — возвращает список опций для отображения, исключая скрытые, и объединяет значения __default и конкретной категории. При заданной категории добавляет ключ config_subdefault со значением по умолчанию.

Пример чтения из PHPDoc cot_config_list() не приводится. Однако, судя по логике, вызов вида:

$options = cot_config_list('module', 'page', 'news');

вернёт все параметры модуля page, у которых тип не равен COT_CONFIG_TYPE_HIDDEN, с учётом переопределений для категории news. Для каждого параметра, значение которого отличается от __default, будет добавлен ключ config_subdefault.

2.3. Обновление значений

Значения обновляются функцией cot_config_set(). Пример из PHPDoc:

$config_values = [
    'disable_test' => '0',
    'hidden_test' => 'test45',
];

cot_config_set('test', $config_values, true);

Здесь true означает, что расширение — модуль. Функция пройдёт по массиву и обновит значения config_value для указанных параметров.

Логика функции включает «обходной путь» для обновления значений структуры: если параметр присутствует в списке __default модуля (полученном через cot_config_list($type, $name, '__default')), то обновление идёт по config_subcat = '__default', независимо от переданной категории.

2.4. Обновление свойств (modify)

Функция cot_config_modify() обновляет служебные свойства существующих записей — тип, порядок, варианты, текст. Значение config_value при этом не изменяется.

Массив опций, передаваемый в функцию, должен содержать ключ name (используется в WHERE), а все остальные ключи получат префикс config_. Например, ключ type в опции превратится в поле config_type для обновления.

2.5. Синхронизация (update)

Функция cot_config_update() — наиболее сложная из CRUD-операций. Она приводит карту конфигурации в соответствие с актуальным списком опций, выполняя три шага:

Удаление устаревших. Загружается текущий список через cot_config_load(). Для каждого старого параметра ищется соответствие в новом списке. Если параметра нет в новом списке и его тип не COT_CONFIG_TYPE_HIDDEN — он попадает в список на удаление.
Добавление новых. Для каждой опции нового списка ищется соответствие в старом. Если опции нет — она попадает в список на добавление.
Изменение модифицированных. Если опция есть в обоих списках, вычисляется разница через array_diff(). При наличии изменений опция попадает в список на модификацию. При этом есть особое правило: если одновременно изменились и тип, и значение по умолчанию, то значение принудительно ставится в default.

Возврат: суммарное количество затронутых записей (удаление + добавление + модификация).

2.6. Удаление и сброс

Удаление выполняет cot_config_remove(). Она принимает либо имя одного параметра, либо массив имён. Если массив из одного элемента, он преобразуется в строку. Если больше — формируется SQL-условие config_name IN (...). Если $option пуст, удаляются все записи по заданным фильтрам (владелец, расширение, категория, донор).

Сброс выполняет cot_config_reset(). Логика зависит от наличия категории:

если категория задана — выполняется DELETE для этой категории; тем самым снимается переопределение и вступает в силу значение __default;
если категория не задана — выполняется UPDATE ... SET config_value = config_default для строк с пустым, NULL или __default значением config_subcat.

2.7. Имплантация (donor / acceptor)

Имплантация позволяет одному расширению (донору) добавить свои параметры в конфигурацию другого расширения (акцептора). Используются две функции:

cot_config_implant() — добавляет отсутствующие параметры;
cot_config_implanted() — проверяет, была ли имплантация выполнена ранее.

Параметр $into_struct в cot_config_implant() определяет, куда добавлять параметры: в корневую конфигурацию модуля (false) или в __default-конфигурацию категорий (true). Проверка наличия идёт по $cfg[$module_name][$opt['name']] или $cfg[$module_name]['cat___default'][$opt['name']] соответственно.

Функция cot_config_implanted() возвращает true, если найдена хотя бы одна запись с config_owner = 'module', config_cat = $acceptor и config_donor = $donor.

2.8. Конфигурация на уровне категорий

Поле config_subcat позволяет хранить разные значения одного параметра для разных категорий. Специальное значение __default используется как значение по умолчанию для всех категорий. Переопределение действует для конкретной категории.

В cot_config_list() при заданном $subcat происходит следующее:

Выбираются все записи с config_subcat = '__default' — они попадают в массив $rowset_default.
Выбираются все записи с config_subcat = $subcat — они попадают в массив $rowset.
Для каждой строки из $rowset проверяется, есть ли соответствующая строка в $rowset_default. Если есть — в строку конкретной категории добавляется ключ config_subdefault со значением по умолчанию.
Итоговый результат — array_merge($rowset_default, $rowset) — переопределения имеют приоритет.

При пустом $subcat слияние выполняется оператором +: $rowset + $rowset_default. При этом приоритет у корневых значений, а __default добавляется только для тех параметров, которых нет в корне.

2.9. Парсинг setup-строк

Функция cot_config_parse() разбирает массив строк вида порядок:тип:варианты:default:текст. Пример строки:

01:string:::Category codes
02:text::en|English:Site locales
03:radio::1:Omit language parameter in the URL if pointing to main language
04:radio::0:Enable URL overwrite for language parameter
05:radio::0:Remember language selection in cookie

Внутри каждой строки:

line[0] — порядок;
line[1] — тип (после trim());
line[2] — варианты;
line[3] — значение по умолчанию;
line[4] — текст (через trim()).

Тип сопоставляется через switch с набором распознаваемых значений: string, select, radio, callback, hidden, separator, range, custom. Если тип не распознан, используется COT_CONFIG_TYPE_TEXT.

Возврат — массив опций с ключами name, order, type, variants, default, text. Если вход не массив — пустой массив.

2.10. Импорт значений из формы

Функция cot_config_import() применяет фильтр к значению из внешнего источника. Пример вызова для одного параметра:

$value = cot_config_import('my_param', 'POST', 'INT');

Для массива имён:

$values = cot_config_import(['param1', 'param2'], 'POST', ['INT', 'TXT']);

Возвращается одиночное значение или массив имя => значение. Если фильтр вернул NULL, формируется сообщение об ошибке через cot_rc('adm_invalid_input'); при заданном $defvalue — подставляется значение по умолчанию и дополняется сообщение.

2.11. Сохранение списка опций

Функция cot_config_update_options() сохраняет значения из списка, полученного через cot_config_list(). Пример:

$options = cot_config_list('module', 'my_module', '');
cot_config_update_options('my_module', $options, true);

Функция проходит по всем опциям, пропуская COT_CONFIG_TYPE_SEPARATOR, применяет фильтры и сохраняет изменённые значения. Переданный по ссылке массив $optionslist обновляется: значения config_value заменяются на отфильтрованные.

2.12. Генерация HTML-полей

Функция cot_config_input() возвращает HTML-код поля ввода в зависимости от типа. Для разных типов используются разные генераторы:

COT_CONFIG_TYPE_TEXT → cot_textarea($name, $value, 8, 56);
COT_CONFIG_TYPE_STRING → cot_inputbox('text', $name, $value);
COT_CONFIG_TYPE_SELECT → cot_selectbox() при непустых вариантах, иначе — cot_inputbox('text', ...);
COT_CONFIG_TYPE_RADIO → cot_radiobox() с подписями Yes/No, если варианты не заданы;
COT_CONFIG_TYPE_RANGE → cot_selectbox() с диапазоном значений;
COT_CONFIG_TYPE_CUSTOM → вызов пользовательской функции;
COT_CONFIG_TYPE_CALLBACK → cot_selectbox() со списком из callback-функции;
COT_CONFIG_TYPE_HIDDEN, COT_CONFIG_TYPE_SEPARATOR → пустая строка.

2.13. Локализация заголовков и подписей

Заголовок и подсказка формируются функцией cot_config_titles(). Правила такие:

Заголовок берётся из $L['cfg_' . $name], если ключ задан. Иначе — из $text (после htmlspecialchars), либо, если $text пуст, из самого $name.
Подсказка берётся из $L['cfg_' . $name . '_hint']. Если ключа нет — устанавливается пустая строка.
Если $L['cfg_' . $name] — массив, элемент 0 используется как заголовок, элемент 1 — как подсказка (если _hint не задан).

Подписи для значений формируются функцией cot_config_selecttitles(). Источник — $L['cfg_' . $name . '_params']. Поддерживаются:

обычный массив с числовыми ключами — используется как есть;
строка через запятую — разбивается через preg_split;
строка формата ключ:значение,ключ:значение — преобразуется в ассоциативный массив;
ассоциативный массив — значения сопоставляются с ключами.

2.14. Кастомные типы: CUSTOM и CALLBACK

Для типа COT_CONFIG_TYPE_CUSTOM в поле config_variants задаётся выражение function_name(params). При обработке значения ищется функция function_name_filter:

если она есть — вызывается через call_user_func_array() с массивом [&$raw_input, $cfg_var, ...callback_params]; кавычки в callback-параметрах удаляются;
если её нет — имя функции разбивается по символу _, последний сегмент переводится в верхний регистр и проверяется как встроенный фильтр: INT, BOL, PSW, ALP, TXT, NUM. Также проверяется наличие такого ключа в глобальном массиве $cot_import_filters.

Для типа COT_CONFIG_TYPE_CALLBACK выражение function_name(params) должно вернуть список вариантов для выпадающего списка. Поддерживаются:

нумерованный массив — значения используются и как значения, и как подписи;
ассоциативный массив — ключ используется как значение, значение — как подпись.

Ассоциативность определяется через сравнение range(0, count($params) - 1) и array_keys($params): если массивы не совпадают — массив считается ассоциативным.

2.15. Встроенные фильтры

В функции cot_config_update_options() перечислены встроенные фильтры, используемые как fallback для типа CUSTOM:

INT — целое число;
BOL — булево;
PSW — пароль;
ALP — буквенно-цифровое значение;
TXT — текст;
NUM — число.

Помимо этого проверяется наличие ключа $base_filter в $cot_import_filters — глобальном массиве пользовательских фильтров.

Часть III. Справочник по функциям

cot_config_type_int()

Категория: генерация HTML-поля.
Назначение: возвращает HTML-код текстового поля ввода для целого числа с placeholder-подсказкой о диапазоне.

Сигнатура:
cot_config_type_int(array $cfg_var, string $min = '', string $max = ''): string

Параметры:

$cfg_var — массив переменной конфигурации. Используются ключи config_name и config_value.
$min — минимально допустимое значение.
$max — максимально допустимое значение.

Возврат: строка HTML — результат вызова cot_inputbox('text', $name, $value, ['placeholder' => $placeholder]).

Формирование placeholder:

если заданы $min и $max — строка вида "$min - $max";
если задан только $min — cot_rc('adm_int_min', ['value' => $min]);
если задан только $max — не формируется (см. часть V, замечание 1).

cot_config_type_int_filter()

Категория: фильтр значений.
Назначение: пример функции-фильтра для типа COT_CONFIG_TYPE_CUSTOM. Фильтрует значение как целое число в диапазоне.

Сигнатура:
cot_config_type_int_filter(string $new_value, array $cfg_var, string $min = '', string $max = '', bool $skip_warnings = false): int|NULL

Параметры:

$new_value — пользовательское значение.
$cfg_var — массив переменной конфигурации; используются config_name и config_text.
$min, $max — границы допустимого диапазона.
$skip_warnings — если истина, сообщения не выводятся.

Возврат:

int — отфильтрованное значение, приведённое к границам;
NULL — если значение нечисловое.

Поведение:

Если !is_numeric($new_value) — $not_num = true, сообщение error.
Иначе значение приводится к целому через floor().
Если значение ниже $min — приводится к $min, сообщение warning.
Если значение выше $max — приводится к $max, сообщение warning.

Побочные эффекты: вызов cot_message() при $skip_warnings = false. Тексты сообщений формируются через cot_rc() с шаблонами adm_invalid_input, adm_set, adm_int_min, adm_int_max.

cot_config_add()

Категория: регистрация.
Назначение: регистрирует набор конфигурационных записей одним вызовом.

Сигнатура:
cot_config_add(string $name, array $options, mixed $is_module = false, string $category = '', string $donor = ''): bool

Параметры:

$name — код расширения.
$options — массив опций; каждая — ассоциативный массив с ключами name, type, default, variants, order, text.
$is_module — булево или строка. Булево true → 'module'; булево false → 'plug'. Строка вне ['plug', 'core'] → 'module'; иначе — сама строка.
$category — код категории (config_subcat).
$donor — имя расширения-донора.

Возврат: true, если вставлено ровно count($options) записей; иначе false.

Записываемые поля: config_owner, config_cat, config_subcat, config_order, config_name, config_type, config_value, config_default, config_variants, config_text, config_donor.

Автоматический порядок: если ключ order не задан, значение поля config_order формируется через str_pad($i, 2, 0, STR_PAD_LEFT).

cot_config_implant()

Категория: имплантация.
Назначение: добавляет в конфигурацию модуля только отсутствующие параметры.

Сигнатура:
cot_config_implant(string $module_name, array $options, bool $into_struct, string $donor): int

Параметры:

$module_name — код модуля-акцептора.
$options — массив опций.
$into_struct — если истина, используются cat___default и категория __default; иначе — корневая конфигурация.
$donor — имя расширения-донора.

Возврат: int — число имплантированных параметров.

Проверка наличия:

при $into_struct = false: !isset($cfg[$module_name][$opt['name']]);
при $into_struct = true: !isset($cfg[$module_name]['cat___default'][$opt['name']]).

cot_config_implanted()

Категория: имплантация.
Назначение: проверяет, были ли уже имплантированы записи от указанного донора.

Сигнатура:
cot_config_implanted(string $acceptor, string $donor): bool

Возврат: true, если найдена хотя бы одна запись с config_owner = 'module', config_cat = $acceptor и config_donor = $donor.

cot_config_load()

Категория: чтение.
Назначение: читает записи конфигурации расширения из БД.

Сигнатура:
cot_config_load(string $name, mixed $is_module = false, string $category = '', string $donor = ''): array

Возврат: массив записей с ключами name, type, order, value, default, variants.

Фильтры SQL: config_owner, config_cat, config_subcat, config_donor.

Исключения: записи с типом COT_CONFIG_TYPE_HIDDEN в результат не попадают.

cot_config_modify()

Категория: изменение свойств.
Назначение: обновляет служебные свойства существующих записей: тип, порядок, текст, варианты.

Сигнатура:
cot_config_modify(string $name, array $options, mixed $isModule = false, string $category = '', string $donor = ''): int

Возврат: int — суммарное количество затронутых записей.

Особенности: ключ name извлекается отдельно и используется в WHERE; остальные ключи получают префикс config_.

cot_config_parse()

Категория: парсинг.
Назначение: разбирает массив setup-строк в структурированный массив опций.

Сигнатура:
cot_config_parse(array $info_cfg): array

Формат строки: порядок:тип:варианты:default:текст.

Распознаваемые типы: string, select, radio, callback, hidden, separator, range, custom; иначе — COT_CONFIG_TYPE_TEXT.

Возврат: массив опций с ключами name, order, type, variants, default, text; пустой массив, если вход не массив.

cot_config_remove()

Категория: удаление.
Назначение: удаляет одну или несколько конфигурационных записей.

Сигнатура:
cot_config_remove(string $name, mixed $is_module = false, mixed $option = '', string $category = '', string $donor = null): int

Возврат: int — количество удалённых записей.

Особенности:

при $option — массиве из одного элемента, он преобразуется в строку;
при массиве из нескольких — формируется config_name IN (...);
при пустом $option — удаляются все записи по заданным фильтрам;
при $donor = null фильтр по донору не применяется.

cot_config_set()

Категория: обновление значений.
Назначение: обновляет значения конфигурации.

Сигнатура:
cot_config_set(string $name, array $options, mixed $isModule = false, string $category = ''): int

Возврат: int — количество обновлённых записей.

Подготовка:

при заданной категории, отличной от __default — $default_options = cot_config_load($name, $isModule, '__default');
при пустой категории — $structure_val = cot_config_list($type, $name, '__default').

Условие обновления: категория пуста, или равна __default, или значение отличается от $default_options[$key].

Обходной путь обновления структуры: если параметр присутствует в $structure_val и является массивом, обновление идёт с config_subcat = '__default'.

cot_config_update()

Категория: синхронизация.
Назначение: приводит карту конфигурации в соответствие с актуальным списком опций.

Сигнатура:
cot_config_update(string $name, array $options, bool $is_module = false, string $category = '', string $donor = ''): int

Возврат: int — суммарное количество затронутых записей.

Алгоритм: удаление устаревших, добавление новых, изменение модифицированных. Скрытые параметры не удаляются. Значение принудительно ставится в default только если одновременно изменились тип и default.

cot_config_reset()

Категория: сброс.
Назначение: сбрасывает значение к config_default.

Сигнатура:
cot_config_reset(string $name, string $option, mixed $is_module = false, string $category = ''): int

Поведение: при заданной категории — DELETE; иначе — UPDATE ... SET config_value = config_default для subcat пустого, NULL или __default.

cot_config_list()

Категория: чтение для отображения.
Назначение: возвращает конфигурацию, пригодную для отображения в административной панели.

Сигнатура:
cot_config_list(string $owner, string $cat, string $subcat = ""): array

Возврат: ассоциативный массив, ключ — config_name; при заданном $subcat для переопределённых параметров добавляется ключ config_subdefault.

Исключения: COT_CONFIG_TYPE_HIDDEN не попадает.

Слияние: при заданном $subcat — array_merge; при пустом — оператор +.

cot_config_import()

Категория: импорт.
Назначение: импортирует значение или массив значений из внешнего источника с фильтрацией.

Сигнатура:
cot_config_import(string|array $name, string $source = 'POST', string|array $filter = 'NOC', mixed $defvalue = null): mixed

Возврат: одиночное значение или массив имя => значение.

Особенности: использует cot_import(), глобальный $cot_import_filters; при NULL-результате формирует сообщение adm_invalid_input; при заданном $defvalue подставляет значение и дополняет сообщение через adm_set_default.

cot_config_update_options()

Категория: сохранение.
Назначение: сохраняет значения из списка, полученного через cot_config_list().

Сигнатура:
cot_config_update_options(string $name, array &$optionslist, mixed $is_module = false, bool $update_new_only = true, string $source = 'POST'): bool|int

Возврат: false, если $optionslist не массив; иначе — число обновлённых записей.

Особенности: пропускает COT_CONFIG_TYPE_SEPARATOR; обрабатывает CUSTOM; сериализует массивы; обновляет $optionslist по ссылке.

cot_config_input()

Категория: генерация HTML.
Назначение: возвращает HTML-код поля ввода по типу.

Сигнатура:
cot_config_input(array $cfg_var): string

Возврат по типам:

STRING → cot_inputbox('text', ...);
SELECT → cot_selectbox() (или текстовое поле, если вариантов нет);
RADIO → cot_radiobox(); при отсутствии вариантов — [1, 0] с подписями Yes/No; пустое значение заменяется на default;
RANGE → cot_selectbox() из range(min, max, step);
CUSTOM → вызов функции; при отсутствии — текстовое поле;
CALLBACK → cot_selectbox() из результата callback-функции;
HIDDEN, SEPARATOR → пустая строка;
по умолчанию → cot_textarea($name, $value, 8, 56).

cot_config_titles()

Категория: локализация.
Назначение: возвращает пару [заголовок, подсказка].

Сигнатура:
cot_config_titles(string $name, string $text = ''): array

Источники: $L['cfg_' . $name] и $L['cfg_' . $name . '_hint'].

Fallback: $text через htmlspecialchars, при пустом — $name.

cot_config_selecttitles()

Категория: локализация.
Назначение: формирует массив подписей для значений списка.

Сигнатура:
cot_config_selecttitles(string $name, array $params): array

Источник: $L['cfg_' . $name . '_params'].

Поддерживаемые форматы: массив с числовыми ключами; строка через запятую; строка ключ:значение,...; ассоциативный массив.

Часть IV. Комплексные примеры

Пример 1. Регистрация конфигурации модуля при установке

$config_options = [
    [
        'name' => 'enable_cache',
        'type' => COT_CONFIG_TYPE_RADIO,
        'default' => '1'
    ],
    [
        'name' => 'items_per_page',
        'type' => COT_CONFIG_TYPE_RANGE,
        'default' => '20',
        'variants' => '10,50,10'  // min, max, step
    ],
    [
        'name' => 'sort_field',
        'type' => COT_CONFIG_TYPE_SELECT,
        'default' => 'date',
        'variants' => 'date,title,views'
    ],
    [
        'name' => 'secret_key',
        'type' => COT_CONFIG_TYPE_HIDDEN,
        'default' => ''
    ]
];

cot_config_add('mymodule', $config_options, 'module');

Здесь:

enable_cache — переключатель, по умолчанию включён;
items_per_page — целочисленный диапазон от 10 до 50 с шагом 10;
sort_field — выпадающий список из трёх значений;
secret_key — скрытый параметр, не отображается в интерфейсе.

Пример 2. Чтение и отображение конфигурации

// Получить все параметры модуля mymodule
$options = cot_config_list('module', 'mymodule', '');

foreach ($options as $name => $opt) {
    // Заголовок и подсказка
    list($title, $hint) = cot_config_titles($name, $opt['config_text']);
    // HTML-поле
    $input = cot_config_input($opt);
    // Вывод: label, input, hint
    echo $title . $input . ' ' . $hint;
}

Пример 3. Сохранение формы с конфигурацией

$options = cot_config_list('module', 'mymodule', '');
$updated = cot_config_update_options('mymodule', $options, true);
if ($updated > 0) {
    cot_message('Настройки сохранены.');
}

Функция cot_config_update_options() обновит только те параметры, которые отличаются от текущих значений.

Пример 4. Импорт одного значения с фильтром

$itemsPerPage = cot_config_import('items_per_page', 'POST', 'INT');

Если пользователь ввёл нечисловое значение, будет сформировано сообщение об ошибке, а возвращён NULL.

Пример 5. Импорт массива значений

$values = cot_config_import(
    ['enable_cache', 'items_per_page'],
    'POST',
    ['BOL', 'INT']
);

Для каждого параметра применяется свой фильтр. Возвращается массив имя => значение.

Пример 6. Имплантация опций в конфигурацию модуля page

$plugin_options = [
    [
        'name' => 'mymodule_enable',
        'type' => COT_CONFIG_TYPE_RADIO,
        'default' => '0'
    ],
    [
        'name' => 'mymodule_limit',
        'type' => COT_CONFIG_TYPE_STRING,
        'default' => '100'
    ]
];

cot_config_implant('page', $plugin_options, false, 'mymodule');

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

Пример 7. Проверка, была ли имплантация

if (!cot_config_implanted('page', 'mymodule')) {
    cot_config_implant('page', $plugin_options, false, 'mymodule');
}

Пример 8. Сброс значения к default

cot_config_reset('mymodule', 'items_per_page', true);

Значение параметра items_per_page будет установлено в config_default.

Пример 9. Удаление параметра

cot_config_remove('mymodule', true, 'secret_key');

Пример 10. Синхронизация конфигурации при обновлении расширения

$new_options = [
    ['name' => 'enable_cache', 'type' => COT_CONFIG_TYPE_RADIO, 'default' => '1'],
    ['name' => 'items_per_page', 'type' => COT_CONFIG_TYPE_RANGE, 'default' => '20', 'variants' => '10,50,10'],
    ['name' => 'sort_field', 'type' => COT_CONFIG_TYPE_SELECT, 'default' => 'date', 'variants' => 'date,title,views,rating']
];

cot_config_update('mymodule', $new_options, true);

В этом примере:

параметр secret_key отсутствует в новом списке, но так как он HIDDEN, он не будет удалён;
параметр sort_field изменился (добавлено значение rating), он будет модифицирован;
другие параметры останутся без изменений.

Часть V. Замечания по исходному коду

Ниже перечислены замечания, прямо следующие из анализа файла. Они фиксируют фактическое поведение кода, а не предположения о замысле.

cot_config_type_int(). Ветка elseif повторяется с одним и тем же условием !empty($min). Вторая ветка, по логике, должна проверять $max. Как следствие — при заданном только $max переменная $placeholder не устанавливается, что может привести к предупреждению PHP о неопределённой переменной.
cot_config_set(). Переменная $default_options определяется только в ветке, когда категория задана и отлична от __default. В остальных случаях она используется в условии без инициализации.
cot_config_set(). Переменная $structure_val определяется в двух разных ветках по-разному: как пустой массив (при конкретной категории) и как результат cot_config_list() (при пустой категории).
cot_config_remove(). При $donor = null фильтр по донору не применяется — удаляются записи как с донором, так и без него. Для точного удаления необходимо передавать конкретное значение донора, в том числе пустую строку.
cot_config_list(). При заданном $subcat используется array_merge(), при пустом — оператор +. Это приводит к разному приоритету: array_merge перезаписывает одноимённые ключи значениями из второго массива, а + — нет.
cot_config_update_options(). Строка list($base_filter) = array_reverse(explode('_', strtoupper($custom_func))); извлекает последний сегмент имени функции и использует его как встроенный фильтр. Например, для функции с именем my_int базовым фильтром будет INT.
cot_config_update(). Параметры типа COT_CONFIG_TYPE_HIDDEN не удаляются даже при отсутствии в новом списке. Это позволяет сохранять скрытые служебные значения.
cot_config_update(). Значение принудительно ставится в default только в случае, когда одновременно изменились и тип, и значение по умолчанию. Если изменился только тип или только default — значение сохраняется.
cot_config_import(). При NULL-результате фильтрации формируется сообщение adm_invalid_input. Если задан $defvalue, подстановка значения и уточнение к сообщению выполняются до вызова cot_message().
cot_config_list(). Тип COT_CONFIG_TYPE_SEPARATOR не исключается из выборки в SQL. Его отображение зависит от cot_config_input(), где он возвращает пустую строку.
cot_config_type_int_filter(). Переменная $hint получается через list($title, $hint) = cot_config_titles(...), но не используется внутри функции. Это не влияет на логику, но создаёт неиспользуемую переменную.
cot_config_add(). Если $is_module — строка, не входящая в ['plug', 'core'], она трактуется как 'module'. Например, строка 'something_else' приведёт к 'module'. Это следует из условия !in_array($is_module, ['plug', 'core']).
cot_config_reset(). При заданной категории выполняется DELETE, а не UPDATE. Это означает, что строка для конкретной категории исчезает, и при последующем чтении через cot_config_list() будет использоваться значение __default.
cot_config_parse(). Доступ к $line[4] выполняется без предварительной проверки его существования. Если строка содержит меньше пяти сегментов, может возникнуть предупреждение PHP.
cot_config_update_options(). При $custom_type = true и отсутствии функции function_name_filter вызывается ветка встроенных фильтров. Условие проверяет sizeof($cot_import_filters[$base_filter]) без предварительной проверки на существование ключа $base_filter в массиве.

19 минут чтения Sodium Carbonate

Комментарии (0)

Комментарии отсутствуют

Добавление комментариев доступно только зарегистрированным пользователям

Мультикатегории статьи

Дополнительные категории, в которых эта статья показывается как похожая.

Cotonti - чтиво. Документация.

Автор контента

Оффлайн

Sodium Carbonate

Последняя авторизация: 20.09.2026 04:00

Обо мне кратко

Поддержка и разработка веб-проектов на CMF Cotonti: приватные мессенджеры через сайт, открытые и закрытые небольшие социальные сети, торговые площадки и маркетплейсы, портал биржи фриланса и услуг, каталоги товаров оптовых поставщиков, дропшиппинг-платформы, интернет-магазины и многое другое.

Смотреть разработки и скачать

Публичное портфолио моих работ и разработок

Телеграм для сообщений

@webitproff

Телеграм-канал

@s/aBuyFILE

Страница размещена: 20.09.2026 03:52
Последнее обновление: 20.09.2026 03:52

Справка и поддержка

Статьи и блоги

Configuration Management API Cotonti — детальный обзор и справочник

Содержание

Часть I. Обзор файла

1.1. Назначение и место в системе

1.2. Структура файла

1.3. Константы типов конфигурации

1.4. Основные понятия и термины

1.5. Модель данных конфигурации

Часть II. Механизмы и сценарии

2.1. Регистрация конфигурации

2.2. Чтение конфигурации

2.3. Обновление значений

2.4. Обновление свойств (modify)

2.5. Синхронизация (update)

2.6. Удаление и сброс

2.7. Имплантация (donor / acceptor)

2.8. Конфигурация на уровне категорий

2.9. Парсинг setup-строк

2.10. Импорт значений из формы

2.11. Сохранение списка опций

2.12. Генерация HTML-полей

2.13. Локализация заголовков и подписей

2.14. Кастомные типы: CUSTOM и CALLBACK

2.15. Встроенные фильтры

Часть III. Справочник по функциям

cot_config_type_int()

cot_config_type_int_filter()

cot_config_add()

cot_config_implant()

cot_config_implanted()

cot_config_load()

cot_config_modify()

cot_config_parse()

cot_config_remove()

cot_config_set()

cot_config_update()

cot_config_reset()

cot_config_list()

cot_config_import()

cot_config_update_options()

cot_config_input()

cot_config_titles()

cot_config_selecttitles()

Часть IV. Комплексные примеры

Пример 1. Регистрация конфигурации модуля при установке

Пример 2. Чтение и отображение конфигурации

Пример 3. Сохранение формы с конфигурацией

Пример 4. Импорт одного значения с фильтром

Пример 5. Импорт массива значений

Пример 6. Имплантация опций в конфигурацию модуля page

Пример 7. Проверка, была ли имплантация

Пример 8. Сброс значения к default

Пример 9. Удаление параметра

Пример 10. Синхронизация конфигурации при обновлении расширения

Часть V. Замечания по исходному коду

Комментарии (0)

Мультикатегории статьи

Автор контента

Sodium Carbonate

Похожие страницы