Plugin manifest (conf.yml)

Every key of a FeatherPanel plugin conf.yml: flags, dependencies, panel version limits, required settings and the config schema behind the settings form.

Every plugin has a conf.yml at the root of its folder. The top-level plugin: block describes the plugin; the optional config: block describes the settings an admin can change.

plugin:
  name: DemoShowcase
  identifier: demoshowcase
  description: 'Shows how pages, widgets and settings work'
  flags:
    - hasEvents
  version: 1.0.0
  target: v2
  author:
    - Your Name
  icon: 'https://example.com/icon.png'
  requiredConfigs: []
  dependencies:
    - php=8.3
    - php-ext=pdo
  minimum_panel_version: 1.0.0
config:
  - name: hide_dashboard_banner
    display_name: 'Hide dashboard banner widget'
    type: boolean
    description: 'When true, the dashboard banner widget is hidden.'
    required: false
    validation: {}
    default: 'false'

The plugin block

Flags

flags may contain only these values; any other value makes the manifest invalid.

Dependencies

Each entry is type=value:

A plugin whose dependencies are missing is not loaded, and the admin plugin page lists what is missing.

The config block

config: is a list of fields. The admin plugin page turns it into a form on the Settings tab.

v1.5.2 and v1.5.3

The settings form changed in v1.5.3 (PR #365).

On v1.5.2, seed defaults in pluginInstall() and validate values in your own code. That code keeps working after the update.

Validation rules

The validation map is read from v1.5.3 (on v1.5.2 it is accepted and ignored, so you can add it now). Every rule is optional and only runs on a non-empty value; an empty optional field is always accepted.

config:
  - name: api_key
    display_name: 'API key'
    type: password
    required: true
    default: ''
    validation:
      regex: '/^[A-Za-z0-9$._-]{20,}$/'
      min: 20
      max: 120
      message: 'Paste the API key from the provider console.'
  - name: query_port
    display_name: 'Query port'
    type: text
    required: false
    default: '25565'
    validation:
      type: integer
      min: 1
      max: 65535

A value that fails is rejected by POST /api/admin/plugins/{identifier}/settings/set with status 400 and error_code: PLUGIN_SETTING_INVALID. The text is in message, and data holds the key and the list of errors, for example {"key": "query_port", "errors": ["Query port must be at most 65535."]}. The developer bulk endpoint PUT/PATCH /api/admin/plugin-manager/{identifier}/settings applies the same rules. Keys that are not declared in config: are not checked, and neither is PluginSettings::setSetting() called from PHP.

Values are saved per plugin and read with PluginSettings:

use App\Plugins\PluginSettings;

$hide = PluginSettings::getSetting('demoshowcase', 'hide_dashboard_banner') === 'true';

Keys you list in requiredConfigs that have no saved value are reported as missing on the admin plugin page and logged. The plugin still loads. From v1.5.3 an empty value also counts as missing, config: fields with required: true count the same way, and the admin API adds plugin.configured: false while anything is missing (fixed in v1.5.3, PR #365). Settings covers the form, the API and the events in detail. Widgets and pages can also be hidden from a setting without code, see the hidden rule on Widget slots.

Mixins

A mixin is a PHP class that implements App\Plugins\Mixins\AppMixin. A plugin asks for mixins by id, with an options map that is passed to the mixin’s initialize():

mixins:
  RateLimiter:
    per_minute: 30

On v1.5.2 and earlier nothing registers mixin classes, so this has no effect beyond a No mixin registered with identifier log line per entry. Mixin registration is fixed in v1.5.3 (PR #365). From then on:

• the web kernel registers every class in backend/app/Plugins/Mixins/Custom/ once, before plugins load, and attaches the declared mixins while each plugin loads,
• the panel ships no built-in mixins, so an id only resolves if such a class has been added to the panel,
• plugin.mixins is read too; when both declare the same id, the top-level entry wins,
• a mixins value that is not a map, or an entry whose options are not a map, makes conf.yml invalid,
• mixins are not attached in the cron runner or php cli,
• your code reads them with PluginProcessor::getMixin($identifier, $mixinId) or PluginProcessor::getMixins($identifier).

Related

• Plugin structure
• Lifecycle and events
• Packaging and publishing