Defining configuration in .schema.ymlfor Drupal 8 , 9 , 10 , and 11

As we continue to build on the foundational skills of Drupal module development, understanding configuration management becomes increasingly essential. In this lesson, we will explore the importance of defining configuration schemas in .schema.yml files—a practice crucial for ensuring data integrity and enabling translations within your modules.

Why Define Configuration Schemas?

Configuration schemas in Drupal serve multiple purposes:

• Data Validation: They assure that configuration data conforms to a predefined structure, preventing unexpected errors.
• UI Support: Automatically provides UI components with the necessary hints to render fields in the Configuration Synchronization user interface.
• Language Translation: Enabling configuration translation support by providing the information needed to integrate with Drupal's translation management system.

What is a .schema.yml File?

A .schema.yml file is used to define the expected structure of configuration data associated with your module. Each configuration entity must have a corresponding schema definition to tell Drupal how to interpret it.

Example Scenario: A Weather Module Configuration

Building on our previous examples, let's define a configuration schema for a settings form in our weather module. The schema will describe settings like API keys and location defaults.

Step 1: Identify Configuration Data

Identify what configurations your module will require. For this example, we’ll configure:

• api_key: A string field for the weather API key.
• default_location: A string field to set a default location for weather data.

Step 2: Create the .schema.yml File

Create a config/schema directory within your module, then create a file named weather_module.schema.yml.

// weather_module/config/schema/weather_module.schema.yml

weather_module.settings:
  type: config_object
  label: 'Weather Module Configuration'
  mapping:
    api_key:
      type: string
      label: 'API Key'
    default_location:
      type: string
      label: 'Default Location'

Explanation of YML Structure

The YAML structure begins with the unique key weather_module.settings, indicating the configuration object name. It consists of:

• type: Sets the type as a config_object.
• label: A human-readable label for the configuration object.
• mapping: Describes the configuration items within the object, assigning each item a type and a label.

Step 3: Implement Configuration Management

After defining the schema, ensure your module implements the configuration settings accurately. Use Drupal's configuration API to read and write values, thereby integrating with other Drupal systems.

Step 4: Develop a Configuration Form

You can create a configuration form to facilitate user input for the settings defined in your schema. The configuration schema ensures that these input settings are validated and correctly processed.

// weather_module/src/Form/WeatherSettingsForm.php

namespace Drupal\weather_module\Form;

use Drupal\Core\Form\ConfigFormBase;
use Drupal\Core\Form\FormStateInterface;

class WeatherSettingsForm extends ConfigFormBase {
    
  protected function getEditableConfigNames() {
    return ['weather_module.settings'];
  }
  
  public function getFormId() {
    return 'weather_settings_form';
  }
  
  public function buildForm(array $form, FormStateInterface $form_state) {
    $config = $this->config('weather_module.settings');

    $form['api_key'] = [
      '#type' => 'textfield',
      '#title' => $this->t('API Key'),
      '#default_value' => $config->get('api_key'),
    ];

    $form['default_location'] = [
      '#type' => 'textfield',
      '#title' => $this->t('Default Location'),
      '#default_value' => $config->get('default_location'),
    ];

    return parent::buildForm($form, $form_state);
  }

  public function submitForm(array &$form, FormStateInterface $form_state) {
    $this->config('weather_module.settings')
      ->set('api_key', $form_state->getValue('api_key'))
      ->set('default_location', $form_state->getValue('default_location'))
      ->save();

    parent::submitForm($form, $form_state);
  }
}

Conclusion and Next Steps

Knowing how to define configuration schemas in .schema.yml files ensures that your Drupal module configurations are flexible, validated, and translatable. It's an essential skill for creating robust, production-ready modules.

In the next lesson, we will cover "Using config.factory to save module settings". You’ll learn how to leverage Drupal's powerful configuration API to reliably store and retrieve your module's settings.

Happy coding, and see you in the next lesson!