kimaai_settings_schema_files

When it fires

Whenever KimaAI builds its settings schema: on init, when it registers its settings with WordPress, and again when the settings app, the settings export and import, the admin assistant or the MCP tools read the schema. So add the filter when your plugin loads, not on init, or your settings cannot be saved.

Each file returns an array with the schema of one settings group. The file’s name is the group’s key: myAddon.php is stored under myAddon in the option kimaai_options, and the REST route /wp/v2/settings reads and saves it with KimaAI’s settings. A group holds pages (link, pageTitle, pageDescription, sections) and a page holds fields (type, default, component, props, section). A page shows in the KimaAI menu at the end, under the group’s title. A field’s component is a key of the field components (TextField, TextareaField, ToggleField, SelectField and others, or your own through kimaai.admin.fieldComponents); a field with an unknown component is not shown. A section’s icon is one of the Lucide names KimaAI bundles (src/admin/app/sectionIcons.js); any other name shows the default icon.

A string is saved through sanitize_text_field() unless the field names a sanitize_callback. A field with 'isSensitive' => true is a secret: the settings app gets “saved” instead of its value, and the settings export leaves it blank.

Callbacks add files, they cannot remove any: KimaAI adds its own files back after the filter, so their settings are never dropped, and a key stays secret when any file marks it. Give your file a name of its own: a file with the name of a KimaAI group (chatbot.php, tools.php) defines that group a second time, and only one of the two definitions is used.

Stored values whose keys leave the schema are removed the next time the schema changes. When your add-on is deactivated, its group leaves the schema and its values in kimaai_options are removed on the next request; they are not there when it is activated again.

Parameters

NameTypeDescription
filesstring[]The paths of the settings files, KimaAI’s own (app/Admin/config/*.php) first.

Returns

string[]: The files. KimaAI adds its own back if a callback removed them, and ignores what is not a path.

Example

add_filter(
  'kimaai_settings_schema_files',
  function (array $files): array {
    $files[] = __DIR__ . '/settings/myAddon.php';
    return $files;
  }
);

The file settings/myAddon.php of the add-on, one page with one setting:

<?php
return [
  'schema' => [
    'type' => 'object',
    'title' => __('My add-on', 'my-addon'),
    'properties' => [
      'general' => [
        'type' => 'object',
        'title' => __('My add-on', 'my-addon'),
        'link' => 'my-addon',
        'pageTitle' => __('My add-on', 'my-addon'),
        'pageDescription' => __('Where my add-on sends its weekly report.', 'my-addon'),
        'sections' => [
          'report' => [
            'icon' => 'Send',
            'title' => __('Weekly report', 'my-addon'),
          ],
        ],
        'properties' => [
          'reportEmail' => [
            'section' => 'report',
            'type' => 'string',
            'default' => '',
            'component' => 'TextField',
            'sanitize_callback' => 'sanitize_email',
            'props' => [
              'type' => 'email',
              'label' => __('Report address', 'my-addon'),
              'description' => __('Leave it empty for no report.', 'my-addon'),
            ],
          ],
        ],
      ],
    ],
  ],
];

The page opens at admin.php?page=kimaai&tab=my-addon. Your code reads the value from the option:

$options = get_option('kimaai_options', []);
$report_email = $options['myAddon']['general']['reportEmail'] ?? '';
  • kimaai.admin.fieldComponents: draws a field with your own component.
  • kimaai_trigger_button_click: reacts to a button on your settings page.

What are your feelings