Creating a Configuration Form

Extend ConfigFormBase

Return the editable configuration names, build defaults from configuration, and save through the editable object. Use dependency injection for validation that requires services.

Validate relationships

Element constraints such as required and maxlength are only the first layer. Validate relationships between values and normalize input before saving.

Ship configuration schema

Schema describes the data types and labels under your configuration key. Without it, translations and automated configuration validation lose important context.

Working example

public function submitForm(array &$form, FormStateInterface $form_state): void {
  $this->config('developer_journal.settings')
    ->set('featured_count', (int) $form_state->getValue('featured_count'))
    ->save();
  parent::submitForm($form, $form_state);
}

Configuration is not runtime state

Drupal configuration is designed for values that describe how the application should behave and can move between environments. Feature flags owned by deployment, view settings, thresholds, and module options often fit that model. Temporary progress, queue position, session data, and rapidly changing operational values usually do not.

Making that distinction prevents configuration exports from becoming polluted with values that should never be promoted from one environment to another.

Schema makes configuration understandable

Configuration schema tells Drupal whether a value is a string, integer, boolean, mapping, sequence, or translatable label. That information supports validation and translation and makes the configuration less ambiguous to both Drupal and future maintainers.

A form that successfully saves without schema can appear complete while leaving other parts of the configuration system with less information than they need.

Account for environment overrides

Some values should differ by environment, especially secrets and infrastructure-specific settings. Those values should not be solved by manually changing active configuration after every import. Use settings overrides or another intentional environment mechanism so the repository can continue to own the canonical deployable configuration.