Форма настроек

Форма настроек — страница в панели, где администратор меняет конфигурацию модуля. Для неё есть готовый базовый класс ConfigFormBase: он добавляет кнопку «Сохранить конфигурацию» и сообщение об успехе. Остаётся описать поля и записать значения.

Где лежит форма

Как и обычная форма — в папке src/Form модуля. Создайте файл вручную.

Класс формы

// web/modules/custom/blog/src/Form/SettingsForm.php
namespace Drupal\blog\Form;
 
use Drupal\Core\Form\ConfigFormBase;
use Drupal\Core\Form\FormStateInterface;
 
class SettingsForm extends ConfigFormBase
{
    public function getFormId(): string
    {
        return 'blog_settings_form';
    }
 
    protected function getEditableConfigNames(): array
    {
        return ['blog.settings'];
    }
 
    public function buildForm(array $form, FormStateInterface $form_state): array
    {
        $form['list_title'] = [
            '#type' => 'textfield',
            '#title' => $this->t('Заголовок списка'),
            '#default_value' => $this->config('blog.settings')->get('list_title'),
        ];
 
        return parent::buildForm($form, $form_state);
    }
 
    public function submitForm(array &$form, FormStateInterface $form_state): void
    {
        $this->config('blog.settings')
            ->set('list_title', $form_state->getValue('list_title'))
            ->save();
 
        parent::submitForm($form, $form_state);
    }
}

Отличий от обычной формы три. Метод getEditableConfigNames() называет объекты конфигурации, которые форма изменяет, — благодаря ему $this->config() здесь возвращает объект для записи. #default_value подставляет в поле текущее значение. А вызовы parent::buildForm() и parent::submitForm() добавляют кнопку и сообщение.

Маршрут

Страницы панели начинаются с /admin. Страницы настроек размещают внутри /admin/config:

# web/modules/custom/blog/blog.routing.yml
blog.settings:
  path: '/admin/config/content/blog'
  defaults:
    _form: '\Drupal\blog\Form\SettingsForm'
    _title: 'Настройки блога'
  requirements:
    _permission: 'administer site configuration'

Право administer site configuration есть у администратора. После drush cr откройте /admin/config/content/blog, измените заголовок и сохраните — страница /blog из прошлого урока покажет новый текст.

Ссылка в панели

Чтобы страницу можно было найти, добавьте ссылку в blog.links.menu.yml:

# web/modules/custom/blog/blog.links.menu.yml
blog.settings:
  title: 'Настройки блога'
  description: 'Заголовок списка и число статей на странице.'
  route_name: blog.settings
  parent: system.admin_config_content

Ссылка появится на странице «Конфигурация» в группе «Работа с содержимым».

Кнопка в списке модулей

# web/modules/custom/blog/blog.info.yml
configure: blog.settings

Строку добавляют в файл описания модуля. После drush cr на странице «Расширения» рядом с модулем Blog появится ссылка «Настроить».

Несколько полей

Остальные настройки добавляют так же — поле в buildForm() и строка в submitForm():

// web/modules/custom/blog/src/Form/SettingsForm.php
$form['items_per_page'] = [
    '#type' => 'number',
    '#title' => $this->t('Статей на странице'),
    '#default_value' => $this->config('blog.settings')->get('items_per_page'),
    '#min' => 1,
    '#max' => 50,
];

// web/modules/custom/blog/src/Form/SettingsForm.php
$this->config('blog.settings')
    ->set('list_title', $form_state->getValue('list_title'))
    ->set('items_per_page', (int) $form_state->getValue('items_per_page'))
    ->save();

Значение из формы приходит строкой, а в схеме поле объявлено как integer, поэтому его приводят к числу.

Частая ошибка

Каждое значение, которое форма сохраняет, должно быть описано в схеме config/schema/blog.schema.yml из прошлого урока. Без этого Drupal сообщает об отсутствующей схеме, а значение может сохраниться не того типа. Добавили поле в форму — добавьте его в схему и в config/install/blog.settings.yml, затем выполните drush cr.

Спасибо, что читаете!