312: Added OS2Forms handler interface for validating handler configurations

Author: jekuaitk

CHANGELOG.md

@@ -11,6 +11,13 @@ before starting to add changes. Use example [placed in the end of the page](#exa
 
 ## [Unreleased]
 
+- [PR-340](https://github.com/OS2Forms/os2forms/pull/340)
+  - Added `OS2FormsHandlerInterface` for reporting misconfigured webform
+  handlers on the webform build and handlers pages.
+  - Implemented configuration validation for the Digital Post handler
+  - Added empty options to the Digital Post handler element selects, so
+  dangling element references no longer display as valid configuration.
+
 ## [5.1.0] 2026-06-03
 
 - [PR-326](https://github.com/OS2Forms/os2forms/pull/326)

modules/os2forms_digital_post/os2forms_digital_post.info.yml

@@ -5,6 +5,7 @@ package: 'OS2Forms'
 core_version_requirement: ^9 || ^10
 dependencies:
   - 'beskedfordeler:beskedfordeler'
+  - 'os2forms:os2forms'
   - 'drupal:advancedqueue'
   - 'os2web_datalookup:os2web_datalookup'
   - 'os2web_key:os2web_key'

modules/os2forms_digital_post/src/Plugin/WebformHandler/WebformHandlerSF1601.php

@@ -3,6 +3,7 @@
 namespace Drupal\os2forms_digital_post\Plugin\WebformHandler;
 
 use Drupal\Core\Form\FormStateInterface;
+use Drupal\os2forms\Plugin\WebformHandler\OS2FormsHandlerInterface;
 use Drupal\os2forms_digital_post\Helper\MeMoHelper;
 use Drupal\os2forms_digital_post\Helper\WebformHelperSF1601;
 use Drupal\webform\Plugin\WebformHandlerBase;
@@ -23,7 +24,7 @@
  *   submission = \Drupal\webform\Plugin\WebformHandlerInterface::SUBMISSION_REQUIRED,
  * )
  */
-final class WebformHandlerSF1601 extends WebformHandlerBase {
+final class WebformHandlerSF1601 extends WebformHandlerBase implements OS2FormsHandlerInterface {
   public const MEMO_MESSAGE = 'memo_message';
   public const MEMO_ACTIONS = 'memo_actions';
   public const TYPE = 'type';
@@ -110,6 +111,7 @@ public function buildConfigurationForm(array $form, FormStateInterface $formStat
       '#required' => TRUE,
       '#default_value' => $this->configuration[self::MEMO_MESSAGE][static::RECIPIENT_ELEMENT] ?? NULL,
       '#options' => $availableElements,
+      '#empty_option' => $this->t('- Select -'),
     ];
 
     $availableElements = $this->getAttachmentElements();
@@ -119,6 +121,7 @@ public function buildConfigurationForm(array $form, FormStateInterface $formStat
       '#required' => TRUE,
       '#default_value' => $this->configuration[self::MEMO_MESSAGE][static::ATTACHMENT_ELEMENT] ?? NULL,
       '#options' => $availableElements,
+      '#empty_option' => $this->t('- Select -'),
     ];
 
     $form[self::MEMO_MESSAGE][self::SENDER_LABEL] = [
@@ -264,6 +267,37 @@ static function (array $element) use ($elementTypes) {
     }, $elements);
   }
 
+  /**
+   * {@inheritdoc}
+   *
+   * @phpstan-return array<int, mixed>
+   */
+  public function validateConfiguration(): array {
+    $problems = [];
+
+    $recipientElement = $this->configuration[self::MEMO_MESSAGE][static::RECIPIENT_ELEMENT] ?? NULL;
+    if (NULL === $recipientElement || '' === $recipientElement) {
+      $problems[] = $this->t('No recipient element is configured.');
+    }
+    elseif (!isset($this->getRecipientElements()[$recipientElement])) {
+      $problems[] = $this->t('The recipient element (%element) does not exist or does not have a supported type.', [
+        '%element' => $recipientElement,
+      ]);
+    }
+
+    $attachmentElement = $this->configuration[self::MEMO_MESSAGE][static::ATTACHMENT_ELEMENT] ?? NULL;
+    if (NULL === $attachmentElement || '' === $attachmentElement) {
+      $problems[] = $this->t('No attachment element is configured.');
+    }
+    elseif (!isset($this->getAttachmentElements()[$attachmentElement])) {
+      $problems[] = $this->t('The attachment element (%element) does not exist or does not have a supported type.', [
+        '%element' => $attachmentElement,
+      ]);
+    }
+
+    return $problems;
+  }
+
   /**
    * {@inheritdoc}
    *

os2forms.services.yml

@@ -0,0 +1,10 @@
+services:
+  Drupal\os2forms\Helper\HandlerConfigurationValidator: ~
+
+  Drupal\os2forms\EventSubscriber\HandlerConfigurationValidationSubscriber:
+    arguments:
+      - "@Drupal\\os2forms\\Helper\\HandlerConfigurationValidator"
+      - "@current_route_match"
+      - "@messenger"
+    tags:
+      - { name: event_subscriber }

src/EventSubscriber/HandlerConfigurationValidationSubscriber.php

@@ -0,0 +1,74 @@
+<?php
+
+namespace Drupal\os2forms\EventSubscriber;
+
+use Drupal\Core\Messenger\MessengerInterface;
+use Drupal\Core\Routing\RouteMatchInterface;
+use Drupal\Core\StringTranslation\StringTranslationTrait;
+use Drupal\os2forms\Helper\HandlerConfigurationValidator;
+use Drupal\webform\WebformInterface;
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\HttpKernel\Event\RequestEvent;
+use Symfony\Component\HttpKernel\KernelEvents;
+
+/**
+ * Reports misconfigured webform handlers on webform admin pages.
+ *
+ * @see \Drupal\os2forms\Plugin\WebformHandler\OS2FormsHandlerInterface
+ */
+class HandlerConfigurationValidationSubscriber implements EventSubscriberInterface {
+  use StringTranslationTrait;
+
+  /**
+   * Routes on which to report misconfigured handlers.
+   */
+  private const ROUTE_NAMES = [
+    // The webform build page (where elements are renamed or deleted).
+    'entity.webform.edit_form',
+    // The webform handlers page.
+    'entity.webform.handlers',
+  ];
+
+  public function __construct(
+    private readonly HandlerConfigurationValidator $validator,
+    private readonly RouteMatchInterface $routeMatch,
+    private readonly MessengerInterface $messenger,
+  ) {
+  }
+
+  /**
+   * Reports misconfigured webform handlers to the current user.
+   */
+  public function onRequest(RequestEvent $event): void {
+    if (!in_array($this->routeMatch->getRouteName(), self::ROUTE_NAMES, TRUE)) {
+      return;
+    }
+
+    $webform = $this->routeMatch->getParameter('webform');
+    if (!$webform instanceof WebformInterface) {
+      return;
+    }
+
+    foreach ($this->validator->validate($webform) as $handlerId => $result) {
+      foreach ($result['problems'] as $problem) {
+        $this->messenger->addWarning($this->t('The handler @handler (@id) is misconfigured: @problem', [
+          '@handler' => $result['label'],
+          '@id' => $handlerId,
+          '@problem' => $problem,
+        ]));
+      }
+    }
+  }
+
+  /**
+   * {@inheritdoc}
+   *
+   * @phpstan-return array<string, mixed>
+   */
+  public static function getSubscribedEvents(): array {
+    return [
+      KernelEvents::REQUEST => ['onRequest'],
+    ];
+  }
+
+}

src/Helper/HandlerConfigurationValidator.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace Drupal\os2forms\Helper;
+
+use Drupal\os2forms\Plugin\WebformHandler\OS2FormsHandlerInterface;
+use Drupal\webform\WebformInterface;
+
+/**
+ * Validates configuration of webform handlers.
+ */
+class HandlerConfigurationValidator {
+
+  /**
+   * Validates configuration of all handlers on a webform.
+   *
+   * @param \Drupal\webform\WebformInterface $webform
+   *   The webform.
+   *
+   * @return array
+   *   Problems keyed by handler ID. Each value is an array with two keys:
+   *   - label: the webform handler label
+   *   - problems: a list of problems (translatable markup)
+   *   Handlers without problems are not included.
+   *
+   * @phpstan-return array<string, mixed>
+   */
+  public function validate(WebformInterface $webform): array {
+    $problems = [];
+    foreach ($webform->getHandlers() as $handler) {
+      if ($handler instanceof OS2FormsHandlerInterface) {
+        if ($handlerProblems = $handler->validateConfiguration()) {
+          $problems[$handler->getHandlerId()] = [
+            'label' => $handler->label(),
+            'problems' => $handlerProblems,
+          ];
+        }
+      }
+    }
+
+    return $problems;
+  }
+
+}

src/Plugin/WebformHandler/OS2FormsHandlerInterface.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Drupal\os2forms\Plugin\WebformHandler;
+
+/**
+ * Interface for webform handlers that can validate their configuration.
+ */
+interface OS2FormsHandlerInterface {
+
+  /**
+   * Validates the handler configuration against the current webform.
+   *
+   * @return \Drupal\Core\StringTranslation\TranslatableMarkup[]
+   *   A list of problems with the handler configuration. An empty list means
+   *   that the configuration is valid.
+   *
+   * @phpstan-return array<int, mixed>
+   */
+  public function validateConfiguration(): array;
+
+}